Merge pull request #1441 from kemerava/feature/dot-net-events

kriswest · web-flow · commit 57602f5d4687 · 2025-02-25T14:21:43.000Z
Adding .NET docs for Events to API reference
diff --git 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
@@ -90,6 +90,9 @@ interface IDesktopAgent
     Task<IPrivateChannel> CreatePrivateChannel();
     Task<IEnumerable<IChannel>> GetUserChannels();
 
+    // non-context events
+    Task<IListener> AddEventListener(string? eventType, Fdc3EventHandler handler);
+
     // OPTIONAL channel management functions
     Task JoinUserChannel(string channelId);
     Task<IChannel?> GetCurrentChannel();
@@ -189,8 +192,8 @@ addEventListener(type: FDC3EventTypes  | null, handler: EventHandler): Promise<L
 </TabItem>
 <TabItem value="dotnet" label=".NET">
 
-```
-Not implemented
+```csharp
+Task<IListener> AddEventListener(string? eventType, Fdc3EventHandler handler);
 ```
 
 </TabItem>
@@ -210,16 +213,20 @@ 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
 });
 ```
 </TabItem>
 <TabItem value="dotnet" label=".NET">
 
-```
-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}");
+});
 ```
 
 </TabItem>
diff --git 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.
 
+
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 interface ApiEvent {
   readonly type: string;
   readonly details: any;
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```
+Not implemented, as ApiEvent and Fdc3Event definitions are the same, given .NET can not restrict on a string enum. Use IFdc3Event instead
+```
+
+</TabItem>
+</Tabs>
 
 **See also:**
 
@@ -22,9 +38,21 @@ interface ApiEvent {
 
 ## `EventHandler`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 type EventHandler = (event: ApiEvent) => void;
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public delegate void Fdc3EventHandler(IFdc3Event fdc3Event);
+```
+
+</TabItem>
+</Tabs>
 
 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`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 type FDC3EventTypes = "userChannelChanged";
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public static class Fdc3EventType
+{
+    public const string UserChannelChanged = "userChannelChanged";
+}
+```
+
+</TabItem>
+</Tabs>
 
 Type defining valid type strings for DesktopAgent interface events.
 
@@ -50,12 +93,40 @@ Type defining valid type strings for DesktopAgent interface events.
 
 ## `FDC3Event`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 interface FDC3Event extends ApiEvent{
   readonly type: FDC3EventTypes;
   readonly details: any;
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```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;
+    }
+}
+```
+
+</TabItem>
+</Tabs>
 
 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`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 interface FDC3ChannelChangedEvent extends FDC3Event {
   readonly type: "userChannelChanged";
@@ -76,16 +150,63 @@ interface FDC3ChannelChangedEvent extends FDC3Event {
   };
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```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))
+    {
+    }
+}
+```
+
+</TabItem>
+</Tabs>
+
 
 Type representing the format of `userChannelChanged`  events.
 
 The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel.
 
 ## `PrivateChannelEventTypes`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect";
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public static class Fdc3PrivateChannelEventType
+{
+    public const string AddContextListener = "addContextListener";
+    public const string Unsubscribe = "unsubscribe";
+    public const string Disconnect = "disconnect";
+}
+```
+
+</TabItem>
+</Tabs>
 
 Type defining valid type strings for Private Channel events.
 
@@ -95,12 +216,37 @@ Type defining valid type strings for Private Channel events.
 
 ## `PrivateChannelEvent`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 interface PrivateChannelEvent extends ApiEvent {
   readonly type: PrivateChannelEventTypes;
   readonly details: any;
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public interface IFdc3PrivateChannelEventDetails
+{
+    string? ContextType { get; }
+}
+public class Fdc3PrivateChannelEventDetails : IFdc3PrivateChannelEventDetails
+{
+    public string? ContextType { get; }
+
+    public Fdc3PrivateChannelEventDetails(string? contextType)
+    {
+        this.ContextType = contextType;
+    }
+}
+```
+
+</TabItem>
+</Tabs>
+
 
 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`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
   readonly type: "addContextListener";
@@ -119,13 +268,31 @@ interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
   };
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public class Fdc3PrivateChannelAddContextListenerEvent : Fdc3Event
+{
+    public Fdc3PrivateChannelAddContextListenerEvent(string? contextType)
+        : base(Fdc3PrivateChannelEventType.AddContextListener, new Fdc3PrivateChannelEventDetails(contextType))
+  {
+  }
+}
+```
+
+</TabItem>
+</Tabs>
 
 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).
 
 The context type of the listener added is provided as `details.contextType`, which will be `null` if all event types are being listened to.
 
 ### `PrivateChannelUnsubscribeEvent`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
   readonly type: "unsubscribe";
@@ -134,19 +301,52 @@ interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
   };
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public class Fdc3PrivateChannelUnsubscribeListenerEvent : Fdc3Event
+{
+    public Fdc3PrivateChannelUnsubscribeListenerEvent(string? contextType)
+            : base(Fdc3PrivateChannelEventType.Unsubscribe, new Fdc3PrivateChannelEventDetails(contextType))
+    {
+    }
+}
+```
+
+</TabItem>
+</Tabs>
 
 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.
 
 The context type of the  listener removed is provided as `details.contextType`, which will be `null` if all event types were being listened to.
 
 ### `PrivateChannelDisconnectEvent`
 
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
 ```ts
 export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent {
   readonly type: "disconnect";
   readonly details: null | undefined;
 }
 ```
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+public class Fdc3PrivateChanneDisconnectEvent : Fdc3Event
+{
+    public Fdc3PrivateChanneDisconnectEvent()
+        : base(Fdc3PrivateChannelEventType.Disconnect)
+    {
+    }
+}
+```
+
+</TabItem>
+</Tabs>
 
 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
