Context Clearing

docs/api/ref/Channel.md

@@ -36,6 +36,7 @@ interface Channel {
   broadcast(context: Context): Promise<void>;
   getCurrentContext(contextType?: string): Promise<Context|null>;
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
+  clearContext(contextType?: string): Promise<void>;
 
   //deprecated functions
   /**
@@ -57,6 +58,7 @@ interface IChannel: IIntentResult
     Task Broadcast(IContext context);
     Task<IContext?> GetCurrentContext(string? contextType);
     Task<IListener> AddContextListener<T>(string? contextType, ContextHandler<T> handler) where T : IContext;
+    Task ClearContext(string? contextType);
 }
 ```
 
@@ -431,6 +433,99 @@ catch (Exception ex)
 - [`broadcast`](#broadcast)
 - [`addContextListener`](#addcontextlistener)
 
+### `clearContext`
+
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
+```ts
+public clearContext(contextType?: string): Promise<void>;
+```
+
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+Task ClearContext(string? contextType);
+```
+
+</TabItem>
+</Tabs>
+
+Used to clear the specified context type if provided, otherwise, clear all contexts. Desktop Agent MUST update internal context. Any future calls to [`getCurrentContext`](#getcurrentcontext) and any new joiners on that channel (through [`joinUserChannel`](DesktopAgent#joinUserChannel) or [`addContextListener`](DesktopAgent#addContextListener)) will not receive anything for specified context type or all contexts accordingly. 
+Desktop Agent MUST update all channel listeners subscribed to the  [`fdc3.nothing`](../../context/ref/Nothing.md/#nothing) type. If `contextType` is provided, then `subType` will be specified, otherwise, it is ommitted. 
+
+
+**Examples:**
+
+Without specifying a context type:
+
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
+```ts
+try {
+    const context = await channel.clearContext();
+} catch (err: ChannelError) {
+    // handle error
+}
+```
+
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+try
+{
+    var context = await channel.ClearContext();
+}
+catch (Exception ex)
+{
+    // handle error
+}
+```
+
+</TabItem>
+</Tabs>
+
+Specifying a context type:
+
+<Tabs groupId="lang">
+<TabItem value="ts" label="TypeScript/JavaScript">
+
+```ts
+try {
+    const contact = await channel.clearContext('fdc3.contact');
+} catch (err: ChannelError) {
+    // handler error
+}
+```
+
+</TabItem>
+<TabItem value="dotnet" label=".NET">
+
+```csharp
+try
+{
+    var context = await channel.ClearContext("fdc3.contact");
+}
+catch (Exception ex)
+{
+    // handle error
+}
+```
+
+</TabItem>
+</Tabs>
+
+
+**See also:**
+
+- [`getCurrentContext`](#getcurrentcontext)
+- [`addContextListener`](DesktopAgent#addContextListener)
+- [`joinUserChannel`](DesktopAgent#joinUserChannel)
+- [`fdc3.nothing`](../../context/ref/Nothing.md/#nothing)
+
 ## Deprecated Functions
 
 ### `addContextListener` (deprecated)

docs/api/spec.md

@@ -241,7 +241,7 @@ When raising an intent a specific context is provided as input. The type of the
 
 A context type may also be associated with multiple intents. For example, an `fdc3.instrument` could be associated with `ViewChart`, `ViewNews`, `ViewAnalysis` or other intents.
 
-To raise an intent without a context, use the [`fdc3.nothing`](../context/ref/Nothing) context type. This type exists so that applications can explicitly declare that they support raising an intent without a context (when registering an `IntentHandler` or in an App Directory).
+To raise an intent without a context, use the [`fdc3.nothing`](../context/ref/Nothing) context type. This type exists so that applications can explicitly declare that they support raising an intent without a context (when registering an `IntentHandler` or in an App Directory). This type is also used when the context is cleared for the channel. If the optional context type is provided when performing [`clearContext`](ref/Channel.md#clearcontext), that type will be recorded in the field `subType` of [`fdc3.nothing`](../context/ref/Nothing) context type.
 
 As an alternative to raising a specific intent, you may also raise an unspecified intent with a known context allowing the Desktop Agent or the user (if the intent is ambiguous) to select the appropriate intent and then to raise it with the specified context for resolution.
 
@@ -585,7 +585,7 @@ Apps can join *User channels*.  An app can only be joined to one User channel at
 
 When an app is joined to a User channel, calls to [`fdc3.broadcast`](ref/DesktopAgent#broadcast) will be routed to that channel and listeners added through [`fdc3.addContextListener`](ref/DesktopAgent#addcontextlistener) will receive context broadcasts from other apps also joined to that channel. If an app is not joined to a User channel [`fdc3.broadcast`](ref/DesktopAgent#broadcast) will be a no-op and handler functions added with  [`fdc3.addContextListener`](ref/DesktopAgent#addcontextlistener) will not receive any broadcasts. However, apps can still choose to listen and broadcast to specific channels (both User and App channels) via the methods on the [`Channel`](ref/Channel) class.
 
-When an app joins a User channel, or adds a context listener when already joined to a channel, it will automatically receive the current context for that channel.
+When an app joins a User channel, or adds a context listener when already joined to a channel, it will automatically receive the current context for that channel, unless the context was cleared through [`clearContext`](ref/Channel.md#clearcontext).
 
 It is possible that a call to join a User channel could be rejected.  If for example, the desktop agent wanted to implement controls around what data apps can access.
 
@@ -830,6 +830,9 @@ The [Context specification](../context/spec#assumptions) recommends that complex
 
 To facilitate context linking in such situations it is recommended that applications `broadcast` each context type that other apps (listening on a User Channel or App Channel) may wish to process, starting with the simpler types, followed by the complex type. Doing so allows applications to filter the context types they receive by adding listeners for specific context types - but requires that the application broadcasting context make multiple broadcast calls in quick succession when sharing its context.
 
+### Context clearning on channels
+Channel interface provides the ability to [`clearContext`](ref/Channel.md#clearcontext) on the channel, either for the specific context type, if provided, or for all contexts on that channel. If provided, the specified type will be recorded in the `subType` field of the [`fdc3.nothing`](../context/ref/Nothing) context type. Once cleared, any subsequent new joiners on the channel, new context listeners on the context or calls to [`getCurrentContext`](ref/Channel.md#getcurrentcontext) will not return anything to the caller. 
+
 ### Originating App Metadata
 
 Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation to registered context handlers on all types of channel. As this metadata is optional, apps making use of it MUST handle cases where it is not provided.

schemas/context/nothing.schema.json

@@ -10,14 +10,19 @@
       "properties": {
         "type": {
           "const": "fdc3.nothing"
+        },
+        "subtype": {
+          "type": "string",
+          "description": "A subtype of the context type. This can be used to provide a specific context which should be cleared, if ommitted, all contexts will be cleared"
         }
       }
     },
     { "$ref": "context.schema.json#/definitions/BaseContext" }
   ],
   "examples": [
     {
-      "type": "fdc3.nothing"
+      "type": "fdc3.nothing",
+      "subtype": "fdc3.timeRange"
     }
   ]
 }

src/api/Channel.ts

@@ -73,6 +73,15 @@ export interface Channel {
    */
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
 
+  /**
+   * Provides the ability to clear context from the channel. Subsequent connection to this channel or calls to get current context will not return anything (accounting for contextType if specified). 
+   * 
+   * If a `contextType` is provided, only contexts of that type will be cleared. 
+   * 
+   * If no `contextType` is provided, all contexts will be cleared.
+   */
+  clearContext(contextType?: string): Promise<void>;
+
   /**
    * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`.
    */