diff --git a/CHANGELOG.md b/CHANGELOG.md index abc10921b..2ebfd31f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added testing policy to [Contributing](CONTRIBUTING) page to address ([810](https://github.com/finos/FDC3/issues/810)) * Added the ability to control logging to the JS console from getAgent() and the DesktopAgentProxy via arguments to getAgent(). ([#1495](https://github.com/finos/FDC3/pull/1495)) * Added the ability for a browser-based DesktopAgent to control the timeouts used in the DesktopAgentProxy when making calls to it, via properties in WCP3Handshake message. ([#1497](https://github.com/finos/FDC3/pull/1497)) - +* Added .NET docs for Events to API reference. ([#1441](https://github.com/finos/FDC3/pull/1441)) ### Changed @@ -112,7 +112,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Further clarified the difference between the behavior of User channels and other channel types on joinUserChannel/addContextListener. ([#971](https://github.com/finos/FDC3/pull/971)) * Clarified description of the behavior of `IntentResolution.getResult()` when the intent handler returned void (which is not an error). ([#1004](https://github.com/finos/FDC3/pull/1004)) * An error was fixed in the appD schema where launch details sub-schemas were combined with `oneOf`, rather than `anyOf`. This causes validation errors for web or online native apps as their details elements overlap on a `url` field. ([#1034](https://github.com/finos/FDC3/pull/1034)) -* The appD `icon` and `screenshot` sub-schemas were updated to require the `src` value is set and restrict additional values, ensuring that common mistakes (such as using a `url` rather than `src` field are caught by the schemas when used to validate. ([#1037](https://github.com/finos/FDC3/pull/1037)) +* The appD `icon` and `screenshot` sub-schemas were updated to require the `src` value is set and restrict additional values, ensuring that common mistakes (such as using a `url` rather than `src` field are caught by the schemas when used to validate). ([#1037](https://github.com/finos/FDC3/pull/1037)) * Linting, spell checking other corrections were applied to markdown syntax throughout the FDC3 documentation ([#1032](https://github.com/finos/FDC3/pull/1032)) * Corrected bad example URLs in the App Directory overview/discovery page in the current and past versions as they did not agree with the paths provided in the API specification and OpenAPI schema. ([#1060](https://github.com/finos/FDC3/pull/1060)) diff --git a/website/docs/api/ref/DesktopAgent.md b/website/docs/api/ref/DesktopAgent.md index 9525418b7..47f1591d6 100644 --- a/website/docs/api/ref/DesktopAgent.md +++ b/website/docs/api/ref/DesktopAgent.md @@ -90,6 +90,9 @@ interface IDesktopAgent Task CreatePrivateChannel(); Task> GetUserChannels(); + // non-context events + Task AddEventListener(string? eventType, Fdc3EventHandler handler); + // OPTIONAL channel management functions Task JoinUserChannel(string channelId); Task GetCurrentChannel(); @@ -189,8 +192,8 @@ addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise -``` -Not implemented +```csharp +Task AddEventListener(string? eventType, Fdc3EventHandler handler); ``` @@ -210,7 +213,7 @@ Whenever the handler function is called it will be passed an event object with d const listener = await fdc3.addEventListener(null, event => { ... }); // listener for a specific event type that logs its details -const userChannelChangedListener = await fdc3.addEventListener("userChannelChanged ", event => { +const userChannelChangedListener = await fdc3.addEventListener("userChannelChanged", event => { console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); //do something else with the event }); @@ -218,8 +221,12 @@ const userChannelChangedListener = await fdc3.addEventListener("userChannelChang -``` -Not implemented +```csharp +var listener = await _desktopAgent.AddEventListener(null, (event) => { ... }); + +var userChannelChangedListener = await _desktopAgent.AddEventListener("userChannelChanged", (event) => { + System.Diagnostics.Debug.Write($"Received event ${event.Type}\n\tDetails: ${event.Details}"); +}); ``` diff --git a/website/docs/api/ref/Events.md b/website/docs/api/ref/Events.md index 3eb89230c..3b8c63e9d 100644 --- a/website/docs/api/ref/Events.md +++ b/website/docs/api/ref/Events.md @@ -2,18 +2,34 @@ title: Events --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + In addition to intent and context events, the FDC3 API and PrivateChannel API may be used to listen for other types of events via their `addEventListener()` functions. ## `ApiEvent` Type defining a basic event object that may be emitted by an FDC3 API interface such as DesktopAgent or PrivateChannel. There are more specific event types defined for each interface. + + + + ```ts interface ApiEvent { readonly type: string; readonly details: any; } ``` + + + +``` +Not implemented, as ApiEvent and Fdc3Event definitions are the same, given .NET can not restrict on a string enum. Use IFdc3Event instead +``` + + + **See also:** @@ -22,9 +38,21 @@ interface ApiEvent { ## `EventHandler` + + + ```ts type EventHandler = (event: ApiEvent) => void; ``` + + + +```csharp +public delegate void Fdc3EventHandler(IFdc3Event fdc3Event); +``` + + + Describes a callback that handles non-context and non-intent events. Provides the details of the event. @@ -38,9 +66,24 @@ Used when attaching listeners to events. ## `FDC3EventTypes` + + + ```ts type FDC3EventTypes = "userChannelChanged"; ``` + + + +```csharp +public static class Fdc3EventType +{ + public const string UserChannelChanged = "userChannelChanged"; +} +``` + + + Type defining valid type strings for DesktopAgent interface events. @@ -50,12 +93,40 @@ Type defining valid type strings for DesktopAgent interface events. ## `FDC3Event` + + + ```ts interface FDC3Event extends ApiEvent{ readonly type: FDC3EventTypes; readonly details: any; } ``` + + + +```csharp +public interface IFdc3Event +{ + public string Type { get; } + public object? Details { get; } +} + +public class Fdc3Event : IFdc3Event +{ + public string Type { get; } + public object? Details { get; } + + public Fdc3Event(string type, object? details = null) + { + this.Type = type ?? throw new ArgumentNullException(nameof(type)); + this.Details = details; + } +} +``` + + + Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function. @@ -68,6 +139,9 @@ Events will always include both `type` and `details` properties, which describe ### `FDC3ChannelChangedEvent` + + + ```ts interface FDC3ChannelChangedEvent extends FDC3Event { readonly type: "userChannelChanged"; @@ -76,6 +150,36 @@ interface FDC3ChannelChangedEvent extends FDC3Event { }; } ``` + + + +```csharp +public interface IFdc3ChannelChangedEventDetails +{ + string? CurrentChannelId { get; } +} +public class Fdc3ChannelChangedEventDetails : IFdc3ChannelChangedEventDetails +{ + public string? CurrentChannelId { get; } + + public Fdc3ChannelChangedEventDetails(string? channelId) + { + this.CurrentChannelId = channelId; + } +} + +public class Fdc3ChannelChangedEvent : Fdc3Event +{ + public Fdc3ChannelChangedEvent(string? channelId) + : base(Fdc3EventType.UserChannelChanged, new Fdc3ChannelChangedEventDetails(channelId)) + { + } +} +``` + + + + Type representing the format of `userChannelChanged` events. @@ -83,9 +187,26 @@ The identity of the channel joined is provided as `details.currentChannelId`, wh ## `PrivateChannelEventTypes` + + + ```ts type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect"; ``` + + + +```csharp +public static class Fdc3PrivateChannelEventType +{ + public const string AddContextListener = "addContextListener"; + public const string Unsubscribe = "unsubscribe"; + public const string Disconnect = "disconnect"; +} +``` + + + Type defining valid type strings for Private Channel events. @@ -95,12 +216,37 @@ Type defining valid type strings for Private Channel events. ## `PrivateChannelEvent` + + + ```ts interface PrivateChannelEvent extends ApiEvent { readonly type: PrivateChannelEventTypes; readonly details: any; } ``` + + + +```csharp +public interface IFdc3PrivateChannelEventDetails +{ + string? ContextType { get; } +} +public class Fdc3PrivateChannelEventDetails : IFdc3PrivateChannelEventDetails +{ + public string? ContextType { get; } + + public Fdc3PrivateChannelEventDetails(string? contextType) + { + this.ContextType = contextType; + } +} +``` + + + + Type defining the format of event objects that may be received via a PrivateChannel's `addEventListener` function. @@ -111,6 +257,9 @@ Type defining the format of event objects that may be received via a PrivateChan ### `PrivateChannelAddContextListenerEvent` + + + ```ts interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent { readonly type: "addContextListener"; @@ -119,6 +268,21 @@ interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent { }; } ``` + + + +```csharp +public class Fdc3PrivateChannelAddContextListenerEvent : Fdc3Event +{ + public Fdc3PrivateChannelAddContextListenerEvent(string? contextType) + : base(Fdc3PrivateChannelEventType.AddContextListener, new Fdc3PrivateChannelEventDetails(contextType)) + { + } +} +``` + + + Type defining the format of events representing a context listener being added to the channel (`addContextListener`). Desktop Agents MUST fire this event for each invocation of `addContextListener` on the channel, including those that occurred before this handler was registered (to prevent race conditions). @@ -126,6 +290,9 @@ The context type of the listener added is provided as `details.contextType`, whi ### `PrivateChannelUnsubscribeEvent` + + + ```ts interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { readonly type: "unsubscribe"; @@ -134,6 +301,21 @@ interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { }; } ``` + + + +```csharp +public class Fdc3PrivateChannelUnsubscribeListenerEvent : Fdc3Event +{ + public Fdc3PrivateChannelUnsubscribeListenerEvent(string? contextType) + : base(Fdc3PrivateChannelEventType.Unsubscribe, new Fdc3PrivateChannelEventDetails(contextType)) + { + } +} +``` + + + Type defining the format of events representing a context listener removed from the channel (`Listener.unsubscribe()`). Desktop Agents MUST call this when `disconnect()` is called by the other party, for each listener that they had added. @@ -141,12 +323,30 @@ The context type of the listener removed is provided as `details.contextType`, ### `PrivateChannelDisconnectEvent` + + + ```ts export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent { readonly type: "disconnect"; readonly details: null | undefined; } ``` + + + +```csharp +public class Fdc3PrivateChanneDisconnectEvent : Fdc3Event +{ + public Fdc3PrivateChanneDisconnectEvent() + : base(Fdc3PrivateChannelEventType.Disconnect) + { + } +} +``` + + + Type defining the format of events representing a remote app being terminated or is otherwise disconnecting from the PrivateChannel. This event is fired in addition to unsubscribe events that will also be fired for any context listeners the disconnecting app had added. diff --git a/website/docs/api/ref/PrivateChannel.md b/website/docs/api/ref/PrivateChannel.md index ddcb07f62..205eac6e5 100644 --- a/website/docs/api/ref/PrivateChannel.md +++ b/website/docs/api/ref/PrivateChannel.md @@ -40,6 +40,10 @@ interface PrivateChannel extends Channel { ```csharp interface IPrivateChannel : IChannel, IIntentResult { + //functions + Task AddEventListener(string? eventType, Fdc3EventHandler handler); + + //deprecated functions IListener OnAddContextListener(Action handler); IListener OnUnsubscribe(Action handler); IListener OnDisconnect(Action handler); @@ -233,7 +237,7 @@ addEventListener(type: PrivateChannelEventTypes | null, handler: EventHandler): ```csharp -Not implemented +Task AddEventListener(string? eventType, Fdc3EventHandler handler); ``` @@ -257,7 +261,10 @@ const listener: Listener = await myPrivateChannel.addEventListener(null, ```csharp -Not implemented +IChannel myPrivateChannel; +var listener = await myPrivateChannel.AddEventListener(null, (event) => { + System.Diagnostics.Debug.WriteLine($"Received event ${event.Type}\n\tDetails: ${event.Details}"); +}); ```