Channels
6.9.0Channels are globally accessed named contexts that allow users to dynamically group apps, instructing them to work over the same shared data object. When apps are on the same Channel, they share a context data object which they can monitor and/or update.
The Channels API is accessible through the io.channels object.
APIobject
Description
Channels API.
Methods
addmethod
Signature
(info: ChannelContext) => Promise<ChannelContext>
Description
Adds a new Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| info | ChannelContext | Initial Channel context. |
allmethod
Signature
() => Promise<string[]>
Description
Retrieves a list of all Channel names.
getmethod
Signature
(name: string, options?: FDC3Options) => Promise<ChannelContext>
Description
Retrieves the context of a specified Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The name of the Channel whose context to retrieve. |
|
| options | FDC3Options | Settings for retrieving an FDC3 context published in the io.Connect Channel. Available since io.Connect Desktop 9.6. |
getMymethod
Signature
(options?: FDC3Options) => Promise<ChannelContext>
Description
Retrieves the context of the current Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | FDC3Options | Settings for retrieving an FDC3 context published in the io.Connect Channel. Available since io.Connect Desktop 9.6. |
getRestrictionsmethod
Signature
(windowId?: string) => Promise<Restrictions>
Description
Retrieves the restrictions applied to the current window for publishing or subscribing to Channels. Pass a window ID to retrieve the restrictions for the specified window.
Available since version io.Connect Desktop 9.3
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| windowId | string | ID of the window for which to retrieve the applied restrictions for publishing or subscribing to Channels. |
getWindowsOnChannelmethod
Signature
(channel: string) => Promise<IOConnectWindow[]>
Description
Retrieves all windows on a specified Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| channel | string |
getWindowsWithChannelsmethod
Signature
(filter?: WindowWithChannelFilter) => Promise<WindowOnChannelInfo[]>
Description
Retrieves all windows that can use Channels together with their current Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| filter | WindowWithChannelFilter | Filter describing which windows to retrieve. If no filter is supplied, will return all windows that can use Channels. |
joinmethod
Signature
(name: string, windowId?: string) => Promise<void>
Description
Joins a new Channel by name. Leaves the current Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The name of the Channel to join. |
|
| windowId | string | ID of a window which to join to a Channel. If not provided, will join the current window to the specified Channel. |
leavemethod
Signature
(windowId?: string) => Promise<void>
Description
Leaves the current Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| windowId | string | ID of a window which to force to leave a Channel. If not provided, will force the current window to leave the current Channel. |
listmethod
mymethod
Signature
() => string
Description
Retrieves the name of the current Channel.
onChangedmethod
Signature
(callback: (channel: string) => void) => () => void
Description
Notifies when a Channel is changed. Returns an unsubscribe function.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (channel: string) => void | Callback function for handling the event. |
publishmethod
Signature
(data: any, options?: string | PublishOptions) => Promise<void>
Description
Updates the context of the current or a specified Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| data | any | Data object with which to update the Channel context. |
|
| options | string | PublishOptions | The name of the Channel to update, or an object containing the name of the Channel to update and a flag indicating whether the published data is an FDC3 context. If no options are provided, the current Channel will be updated. |
removemethod
Signature
(channel: string) => Promise<void>
Description
Removes a Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| channel | string | The name of the Channel to remove. |
restrictmethod
Signature
(restrictions: ChannelRestrictions) => Promise<void>
Description
Prevents or allows the current or another window to publish or subscribe to a specific Channel.
Available since version io.Connect Desktop 9.3
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| restrictions | ChannelRestrictions | Restrictions for publishing or subscribing to a specific Channel. |
restrictAllmethod
Signature
(restrictions: RestrictionsConfig) => Promise<void>
Description
Prevents or allows the current or another window to publish or subscribe to all Channels.
Available since version io.Connect Desktop 9.3
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| restrictions | RestrictionsConfig | Restrictions for publishing or subscribing to all Channels. |
setPathmethod
Signature
(path: PathValue, name?: string) => Promise<void>
Description
Sets a specified path within the Channel context to the provided value. If the path doesn't exist, it will be created.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| path | PathValue | Object containing the path to update and the value with which to update it. The path must be specified as a dot-separated string (e.g., |
|
| name | string | Name of the Channel to update. If not specified, will update the current Channel. |
setPathsmethod
Signature
(paths: PathValue[], name?: string) => Promise<void>
Description
Sets a list of specified paths within the Channel context to the provided values. If a path doesn't exist, it will be created.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| paths | PathValue[] | List of objects each containing a path to update and the value with which to update it. The path must be specified as a dot-separated string (e.g., |
|
| name | string | Name of the Channel to update. If not specified, will update the current Channel. |
subscribemethod
Signature
(callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options) => () => void
Description
Subscribes for data updates of the current Channel. Persisted after a Channel change. Returns an unsubscribe function.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (data: any, context: ChannelContext, updaterId: string) => void | Callback function for handling the received data. The callback receives as arguments the updated Channel data, the current Channel context and the ID of the updating app instance. |
|
| options | FDC3Options | Settings for subscribing to an FDC3 context published in the io.Connect Channel. Available since io.Connect Desktop 9.6. |
subscribeFormethod
Signature
(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options) => Promise<() => void>
Description
Subscribes for data updates of a specified Channel. Resolves with an unsubscribe function.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The Channel to which to subscribe. |
|
| callback | (data: any, context: ChannelContext, updaterId: string) => void | Callback function for handling the received data. The callback receives as arguments the updated Channel data, the current Channel context and the ID of the updating app instance. |
|
| options | FDC3Options | Settings for subscribing to an FDC3 context published in the io.Connect Channel. Available since io.Connect Desktop 9.6. |
ChannelContextobject
Description
Describes a Channel context.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| data | { [key: string]: any; fdc3?: Context; } | Channel context data. |
||
| meta | any | Channel meta data (display name, color, image and more). |
||
| name | string | Unique name of the Channel context. |
ChannelRestrictionsobject
Description
Restrictions applied to a window for publishing or subscribing to a specific Channel.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| name | string | Name of the Channel for which the restrictions apply. |
||
| read | boolean | If |
||
| windowId | string | ID of the window for which apply the restrictions for publishing or subscribing to Channels. |
||
| write | boolean | If |
FDC3Optionsobject
Description
Settings for retrieving and subscribing for FDC3 contexts published in an io.Connect Channel.
Available since version io.Connect Desktop 9.6Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| contextType | string | Type of the FDC3 context to retrieve or to which to subscribe. |
PublishOptionsobject
Description
Options for updating a Channel context with the publish() method.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| fdc3 | boolean | Flag indicating whether the published data is an FDC3 context. If so, it must contain a required |
||
| name | string | The name of the Channel to update. If not provided, the current Channel will be updated. |
Restrictionsobject
Description
All restrictions applied to a window for publishing or subscribing to Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| channels | ChannelRestrictions[] | List of restrictions for publishing or subscribing to Channels. |
RestrictionsConfigobject
Description
Restrictions applied to a window for publishing or subscribing to all Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| read | boolean | If |
||
| windowId | string | ID of the window for which apply the restrictions for publishing or subscribing to Channels. |
||
| write | boolean | If |
WindowOnChannelInfoobject
Description
Describes an io.Connect Window that can use Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| application | string | The name of the app of which the io.Connect Window is an instance. |
||
| channel | string | The current Channel of the io.Connect Window. May be |
||
| window | IOConnectWindow | The io.Connect Window object. |
WindowWithChannelFilterobject
Description
Filter that will be applied when looking for io.Connect Windows that can use Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| application | string | Will retrieve only io.Connect Windows that are instances of the specified app. |
||
| channels | string[] | Will retrieve all io.Connect Windows that are on the specified list of Channels. |
||
| windowIds | string[] | IDs of io.Connect Windows which to retrieve. |