Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding .NET docs for Events to API reference #1441

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Adding .NET docs for Events to API reference #1441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c3197f3
Adding .NET docs for Events to API reference
kemerava Nov 15, 2024
16d5b2d
Changelog
kemerava Nov 15, 2024
be06f86
Update docs/api/ref/Events.md based on review
kemerava Nov 18, 2024
c0bfb3e
Apply suggestions from code review
kemerava Nov 22, 2024
9a9728d
Apply suggestions from code review
kemerava Nov 27, 2024
bc6881f
Merge remote-tracking branch 'origin/main' into feature/dot-net-events
kemerava Dec 3, 2024
924fd3b
Update CHANGELOG.md
kemerava Dec 4, 2024
3b4d107
Adding imports
kemerava Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
* Added utility functions `isStandardContextType(contextType: string)`, `isStandardIntent(intent: string)`,`getPossibleContextsForIntent(intent: StandardIntent)`. ([#1139](https://github.com/finos/FDC3/pull/1139))
* Added support for event listening outside of intent or context listnener. Added new function `addEventListener`, type `EventHandler`, enum `FDC3EventType` and interfaces `FDC3Event` and `FDC3ChannelChangedEvent`. ([#1207](https://github.com/finos/FDC3/pull/1207))
* Added new `CreateOrUpdateProfile` intent. ([#1359](https://github.com/finos/FDC3/pull/1359))

* Added .NET docs for Events to API reference. ([#1441](https://github.com/finos/FDC3/pull/1441))

### Changed

Expand Down
175 changes: 175 additions & 0 deletions docs/api/ref/Events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,38 @@
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">

```csharp
interface IApiEvent
{
string Type { get; }
string Details { get; }
}
```

</TabItem>
</Tabs>

**See also:**

Expand All @@ -22,9 +42,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
delegate void EventHandler<T>(T event) where T : IApiEvent;
```

</TabItem>
</Tabs>

Describes a callback that handles non-context and non-intent events. Provides the details of the event.

Expand All @@ -38,9 +70,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
enum FDC3EventType
{
UserChannelChanged
}
```

</TabItem>
</Tabs>

Type defining valid type strings for DesktopAgent interface events.

Expand All @@ -50,12 +97,28 @@ 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
interface IFDC3Event<T> : IApiEvent
{
FDC3EventType Type { get; }
T Details { get; }
}
```

</TabItem>
</Tabs>

Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function.

Expand All @@ -68,6 +131,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";
Expand All @@ -76,16 +142,52 @@ interface FDC3ChannelChangedEvent extends FDC3Event {
};
}
```
</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
class Details
{
string? CurrentChannelId { get; }
}

interface IFDC3ChannelChangedEvent : IFDC3Event
{
FDC3EventType Type { get; }
Details Details { get; } // TODO
}
```

</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
enum PrivateChannelEventType
{
AddContextListener,
Unsubscribe,
Disconnect
}
```

</TabItem>
</Tabs>

Type defining valid type strings for Private Channel events.

Expand All @@ -95,12 +197,29 @@ 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
interface IPrivateChannelEvent<T> : IApiEvent
{
PrivateChannelEventType Type { get; }
T Details { get; }
}
```

</TabItem>
</Tabs>


Type defining the format of event objects that may be received via a PrivateChannel's `addEventListener` function.

Expand All @@ -111,6 +230,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";
Expand All @@ -119,13 +241,34 @@ interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
};
}
```
</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
class Details
{
string? ContextType { get; }
}

interface IPrivateChannelAddContextListenerEvent : IPrivateChannelEvent
{
PrivateChannelEventType Type { get; }
Details Details { get; }
}
```

</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";
Expand All @@ -134,19 +277,51 @@ interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
};
}
```
</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
class Details
{
string? ContextType { get; }
}

interface IPrivateChannelUnsubscribeEvent : IPrivateChannelEvent
{
PrivateChannelEventType Type { get; }
Details Details { get; }
}
```

</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 interface IPrivateChannelDisconnectEvent : IPrivateChannelEvent {
PrivateChannelEventType Type { get; }
}
```

</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.

Expand Down