Channel
interface Channel {
// properties
id: string;
type: string;
displayMetadata?: DisplayMetadata;
// methods
broadcast(context: Context): void;
getCurrentContext(contextType?: string): Promise<Context|null>;
addContextListener(handler: ContextHandler): Listener;
addContextListener(contextType: string, handler: ContextHandler): Listener;
}
Represents a context channel that applications can join to share context data.
A channel can be either a well-known "system" channel (retrieved with getSystemChannels) or a custom "app" channel (obtained through getOrCreateChannel).
Channels each have a unique identifier, some display metadata and operations for broadcasting context to other applications, or receiving context from other applications.
See also
Properties
id
public readonly id: string;
Uniquely identifies the channel. It is either assigned by the desktop agent (system channel) or defined by an application (app channel).
type
public readonly type: string;
Can be system or app.
displayMetadata
public readonly displayMetadata?: DisplayMetadata;
DisplayMetadata can be used to provide display hints for channels intended to be visualized and selectable by end users.
See also
Methods
addContextListener
public addContextListener(handler: ContextHandler): Listener;
Adds a listener for incoming contexts whenever a broadcast happens on the channel.
public addContextListener(contextType: string, handler: ContextHandler): Listener;
Adds a listener for incoming contexts of the specified context type whenever a broadcast happens on this channel.
Examples
Add a listener for any context that is broadcast on the channel:
const listener = channel.addContextListener(context => {
if (context.type === 'fdc3.contact') {
// handle the contact
} else if (context.type === 'fdc3.instrument') => {
// handle the instrument
}
});
// later
listener.unsubscribe();
Adding listeners for specific types of context that is broadcast on the channel:
const contactListener = channel.addContextListener('fdc3.contact', contact => {
// handle the contact
});
const instrumentListener = channel.addContextListener('fdc3.instrument', instrument => {
// handle the instrument
});
// later
contactListener.unsubscribe();
instrumentListener.unsubscribe();
See also
broadcast
public broadcast(context: Context): void;
Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on channels that they aren't a member of.
If the broadcast is denied by the channel or the channel is not available, the method will return an Error with a string from the ChannelError enumeration.
Example
const instrument = {
type: 'fdc3.instrument',
id: {
ticker: 'AAPL'
}
};
try {
channel.broadcast(instrument);
} catch (err: ChannelError) {
// handler errror
}
See also
getCurrentContext
public getCurrentContext(contextType?: string): Promise<Context|null>;
When a context type is provided, the most recent context matching the type will be returned, or null if no matching context is found.
If no context type is provided, the most recent context that was broadcast on the channel - regardless of type - will be returned. If no context has been set on the channel, it will return null.
It is up to the specific Desktop Agent implementation whether and how recent contexts are stored. For example, an implementation could store context history for a channel in a single array and search through the array for the last context matching a provided type, or context could be maintained as a dictionary keyed by context types. An implementation could also choose not to support context history, in which case this method will return null for any context type not matching the type of the most recent context.
If getting the current context fails, the promise will return an Error with a string from the ChannelError enumeration.
Examples
Without specifying a context type:
try {
const context = await channel.getCurrentContext();
} catch (err: ChannelError) {
// handler errror
}
Specifying a context type:
try {
const contact = await channel.getCurrentContext('fdc3.contact');
} catch (err: ChannelError) {
// handler errror
}