Interop
6.8.3The Interop API enables applications to:
- offer functionality to other applications by registering Interop methods;
- discover applications which offer methods;
- invoke methods on the user's desktop and across the network;
- stream and subscribe for real-time data using the streaming methods of the Interop API;
Applications which offer methods and streams are called Interop servers, and applications which consume them - Interop clients, and collectively - Interop instances.
Any running instance of an application is identified by its Interop instance, which is a set of known key/value pairs uniquely identifying an application.
The Interop API is accessible through the io.interop
object.
APIobject
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
instance | Instance | Instance of the current application. |
Methods
createStreammethod
Signature
(methodDefinition: string | MethodDefinition, options?: StreamOptions, successCallback?: (args?: object) => void, errorCallback?: (error?: string | object) => void) => Promise<Stream>
Description
Creates a new Interop stream.
Parameters
Name | Type | Required | Description |
---|---|---|---|
methodDefinition | string | MethodDefinition | A unique string or a |
|
options | StreamOptions | The |
|
successCallback | (args?: object) => void | An optional handler to be called if the creation of the stream succeeds. |
|
errorCallback | (error?: string | object) => void | An optional handler to be called in case of an error when creating a stream. |
Example
io.interop
.createStream({
name: "MarketData.LastTrades",
displayName: "Publishes last trades for a symbol",
objectTypes: ["Symbol"],
accepts: "String symbol",
returns: "String symbol, Double lastTradePrice, Int lastTradeSize"
})
.then(stream =>
setInterval(
() =>
stream.push({
symbol: "GOOG",
lastTradePrice: 700.91,
lastTradeSize: 10500
}),
5000
)
)
.catch(console.error);
invokemethod
Signature
<T=any>(method: string | MethodDefinition, argumentObj?: object, target?: InstanceTarget, options?: InvokeOptions, success?: InvokeSuccessHandler<T>, error?: InvokeErrorHandler) => Promise<InvocationResult<T>>
Description
Invokes an Interop method with some arguments on target servers.
Parameters
Name | Type | Required | Description |
---|---|---|---|
method | string | MethodDefinition | The unique |
|
argumentObj | object | A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop method. |
|
target | InstanceTarget | Specifies which servers to target. Can be one of: "best", "all", |
|
options | InvokeOptions | An optional [ |
|
success | InvokeSuccessHandler<T> | An |
|
error | InvokeErrorHandler | An |
Example
io.interop
.invoke("Sum", { a: 37, b: 5 }) // everything else is optional
.then(successResult => {
console.log(`37 + 5 = ${successResult.returned.answer}`);
})
.catch(err => {
console.error(`Failed to execute Sum ${err.message}`);
});
methodAddedmethod
methodRemovedmethod
Signature
(callback: (method: Method) => void) => UnsubscribeFunction
Description
Subscribes to the event which fires when a method is removed from the last application offering it.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (method: Method) => void | A handler to be called when the event fires. |
methodsmethod
Signature
(filter?: string | MethodFilter) => Method[]
Description
Returns all methods that match the passed filter. If no filter is specified, returns all methods.
Parameters
Name | Type | Required | Description |
---|---|---|---|
filter | string | MethodFilter | An object describing a filter matching one or more Interop methods. If string will match the method by name |
methodsForInstancemethod
registermethod
Signature
<T=any,R=any>(name: string | MethodDefinition, handler: (args: T, caller: Instance) => void | R | Promise<R>) => Promise<void>
Description
Registers a new Interop method.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | MethodDefinition | A unique string or a |
|
handler | (args: T, caller: Instance) => void | R | Promise<R> | The JavaScript function that will be called when the method is invoked. |
Example
io.interop.register(
{
name: "Sum", // required - method name
accepts: "int a, int b", // optional - parameters signature
returns: "int answer" // optional - result signature
},
args => {
// required - handler function
return { answer: args.a + args.b };
}
);
serverAddedmethod
serverMethodAddedmethod
Signature
(callback: (info: { server: Instance; method: Method; }) => void) => UnsubscribeFunction
Description
Subscribes to the event which fires when an application starts offering a method. This will be called every time a server starts offering the method,
whereas methodAdded()
will be called only the first time the method is registered.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (info: { server: Instance; method: Method; }) => void |
serverMethodRemovedmethod
Signature
(callback: (info: { server: Instance; method: Method; }) => void) => UnsubscribeFunction
Description
Subscribes for the event which fires when a server stops offering a method. This will be called every time a server stops offering the method,
whereas methodRemoved()
will be called only when the method is removed from the last application offering it.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (info: { server: Instance; method: Method; }) => void | A handler to be called when the event fires. |
serverRemovedmethod
Signature
(callback: (server: Instance) => void) => UnsubscribeFunction
Description
Subscribes to the event which fires when an app offering methods stops offering them or exits.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (server: Instance) => void | A handler to be called when the event fires. |
serversmethod
Signature
(filter?: MethodFilter) => Instance[]
Description
Returns all Interop aware applications.
Optionally, the list can be filtered to return only servers providing specific Interop method(s)
by passing a methodFilter
.
Parameters
Name | Type | Required | Description |
---|---|---|---|
filter | MethodFilter | An object describing a filter matching one or more Interop methods. |
subscribemethod
Signature
(methodDefinition: string | MethodDefinition, parameters?: SubscriptionParams) => Promise<Subscription>
Description
Subscribes to an Interop stream.
Parameters
Name | Type | Required | Description |
---|---|---|---|
methodDefinition | string | MethodDefinition | The unique |
|
parameters | SubscriptionParams | An optional |
Example
io.interop
.subscribe("MarketData.LastTrades", {
arguments: { symbol: "GOOG" },
target: "all"
})
.then(subscription => {
// use subscription
})
.catch(error => {
// subscription rejected or failed
});
unregistermethod
Signature
(definition: string | MethodDefinition) => void
Description
Unregisters an Interop method.
Parameters
Name | Type | Required | Description |
---|---|---|---|
definition | string | MethodDefinition | The unique |
waitForMethodmethod
Signature
(name: string) => Promise<Method>
Description
Wait for a method to be available. If the method is already registered this will resolve immediately otherwise will wait until the method appears
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | Name of the method to wait for |
Instanceobject
Description
Each Interop application is identified by its Interop instance, which is a set of known key/value pairs.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
api | string | API version |
||
application | string | Unique application name. |
||
applicationName | string | Application name |
||
environment | string | Environment in which the application is running. |
||
instance | string | (IOConnect Desktop) Unique string identifying the application. |
||
isLocal | boolean | (IOConnect Desktop) A flag indicating whether the instance is running on a local machine or not. Taken into account when a Gateway mesh is present - local instances are preferred when invoking methods. |
||
machine | string | Name of the machine the instance is running on. |
||
peerId | string | (IOConnect Desktop) Gateway peer ID of the instance. |
||
pid | number | Process ID of the instance. |
||
region | string | Region in which the application is running. |
||
service | string | Service string of the application. |
||
user | string | Name of the user who has started the instance. |
||
windowId | string | (IOConnect Desktop) Window ID of the instance. Only set if running in a IOConnect window. |
Methods
getMethodsmethod
getStreamsmethod
InvocationResultobject
Description
Extends InvocationResultCore
. Results from a method invocation.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
all_errors | any[] | An array of error objects. |
||
all_return_values | InvocationResultCore<T>[] | An array of invocation results. |
||
called_with | any | Arguments of the invocation. |
||
executed_by | Instance | Instance of the application that executed the method. |
||
message | string | Message from the application that executed the method. |
||
method | MethodDefinition | Method definition of the method that was invoked. |
||
returned | T | Returned object. |
||
status | number | Status sent by the application that executed the method. |
InvocationResultCoreobject
Description
Result from a method invocation.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
called_with | any | Arguments of the invocation. |
||
executed_by | Instance | Instance of the application that executed the method. |
||
message | string | Message from the application that executed the method. |
||
method | MethodDefinition | Method definition of the method that was invoked. |
||
returned | T | Returned object. |
||
status | number | Status sent by the application that executed the method. |
InvokeOptionsobject
Description
Method invocation options.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
methodResponseTimeoutMs | number | 30000 | Timeout to wait for a method reply. |
|
waitTimeoutMs | number | 30000 | Timeout to discover the method, if not immediately available. |
Methodobject
Description
An interop method
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
accepts | string | Signature describing the parameters that the method expects. |
||
description | string | Description of what the method does. Useful for documentation purposes and for UI clients. |
||
displayName | string | The actual name of the method, used in UI applications. |
||
flags | { [key: string]: any; } | Optional flags attached to the method |
||
name | string | The name of the method. Must be unique. |
||
objectTypes | string[] | The entities this method is meant to work with. |
||
returns | string | Signature describing the properties of the object the method returns. |
||
supportsStreaming | boolean | If |
||
version | number | Method version. |
Methods
getServersmethod
MethodDefinitionobject
Description
An object describing an Interop method registered by an application.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
accepts | string | Signature describing the parameters that the method expects. |
||
description | string | Description of what the method does. Useful for documentation purposes and for UI clients. |
||
displayName | string | The actual name of the method, used in UI applications. |
||
flags | { [key: string]: any; } | Optional flags attached to the method |
||
name | string | The name of the method. Must be unique. |
||
objectTypes | string[] | The entities this method is meant to work with. |
||
returns | string | Signature describing the properties of the object the method returns. |
||
supportsStreaming | boolean | If |
||
version | number | Method version. |
Methods
getServersmethod
MethodFilterobject
Description
An object describing a filter matching one or more Interop methods.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
accepts | string | Signature describing the parameters that the method expects. |
||
description | string | Description of what the method does. Useful for documentation purposes and for UI clients. |
||
displayName | string | The actual name of the method, used in UI applications. |
||
name | string | The name of the method. Must be unique. |
||
objectTypes | string[] | The entities this method is meant to work with. |
||
returns | string | Signature describing the properties of the object the method returns. |
OnClosedInfoobject
Description
Addition information around subscription being closed
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
message | string | |||
requestArguments | object | |||
server | Instance | |||
stream | MethodDefinition |
Streamobject
Description
Object describing an Interop stream.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
definition | MethodDefinition | Stream definition object. |
||
name | string | Name of the stream. |
Methods
branchmethod
Signature
(key: string) => StreamBranch
Description
Returns a branch by key.
Parameters
Name | Type | Required | Description |
---|---|---|---|
key | string |
branchesmethod
branchesmethod
branchesmethod
Signature
(key?: string) => StreamBranch | StreamBranch[]
Parameters
Name | Type | Required | Description |
---|---|---|---|
key | string |
closemethod
Signature
() => void
Description
Closes the stream. This will close all subscriptions.
pushmethod
Signature
(data: object, branches?: string | string[]) => void
Description
Push data to the stream. If a branches
argument is passed, the data will be sent to the specified stream branch(es) only.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | object | Data to push. |
|
branches | string | string[] | To which branch(es) to push data. |
subscriptionsmethod
Signature
() => StreamSubscription[]
Description
Returns a list of active subscriptions to the stream.
StreamBranchobject
Description
A stream branch created by the application.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
key | string | Branch key. |
Methods
closemethod
Signature
() => void
Description
Closes the stream branch.
pushmethod
Signature
(data: object) => void
Description
Pushes data to this branch only.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | object | Data to push. |
subscriptionsmethod
StreamDataobject
Description
Stream data received by the subscriber.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
data | any | Data from the stream. |
||
message | string | Message from the publisher of the stream. |
||
private | boolean | If |
||
requestArguments | any | Arguments used when the subscription was made. |
||
server | Instance | Instance of the application publishing the stream. |
StreamOptionsobject
Description
Optional handlers that can be supplied when creating streams.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
subscriptionAddedHandler | (request: StreamSubscription) => void | Subscribes to the event which fires when a stream subscription is added. |
||
subscriptionRemovedHandler | (request: StreamSubscription) => void | Subscribes to the event which fires when a stream subscription is removed. |
||
subscriptionRequestHandler | (request: SubscriptionRequest) => void | Subscribes for subscription requests. These can be accepted, rejected or accepted on a custom branch. If this handler is attached, each request should be explicitly accepted. |
StreamSubscriptionobject
Description
An object describing a subscription to an Interop stream.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
arguments | any | Arguments used when the subscription was made. |
||
branchKey | string | The key of the stream branch to which the subscription was made. |
||
instance | Instance | Instance of the subscriber. |
||
stream | Stream | The stream to which the subscription was made. |
Methods
closemethod
Signature
() => void
Description
Closes the subscription. This will not close the stream.
pushmethod
Signature
(data: object) => void
Description
Pushes data to this subscription only.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | object | Data to push. |
Subscriptionobject
Description
Stream subscription made by an application.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
requestArguments | object | Arguments used to make the subscription. |
||
serverInstance | Instance | |||
servers | Instance[] | Instances of the applications providing the stream, that we have subscribed to |
||
stream | MethodDefinition | Stream definition. |
Methods
closemethod
Signature
() => void
Description
Closes the subscription.
onClosedmethod
Signature
(callback: (info: OnClosedInfo) => void) => void
Description
Subscribe for the event which fires when the subscription is closed.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (info: OnClosedInfo) => void |
onConnectedmethod
onDatamethod
Signature
(callback: (data: StreamData) => void) => void
Description
Subscribe for the event which fires when new data is received.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (data: StreamData) => void |
onFailedmethod
Signature
(callback: (err: any) => void) => void
Description
Subscribe for the event which fires if the subscription fails.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (err: any) => void |
SubscriptionParamsobject
Description
Optional object with parameters passed to subscribe()
when subscribing to a stream.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
arguments | object | A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop stream. |
||
methodResponseTimeout | number | 30000 | Timeout to wait for a stream reply. |
|
onClosed | () => void | Subscribe for the event which fires when the subscription is closed. |
||
onConnected | (server: Instance, reconnect: boolean) => void | Subscribe for the event which your subscription is connected to a server |
||
onData | (data: StreamData) => void | Subscribe for the event which fires when new data is received. |
||
target | InstanceTarget | Specifies which servers to target. Can be one of: "best", "all", |
||
waitTimeoutMs | number | 30000 | Timeout to discover the stream, if not immediately available. |
SubscriptionRequestobject
Description
A subscription request object handled by the server that has created the stream. It can be accepted or rejected.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
arguments | any | Arguments passed with the subscription request. |
||
instance | Instance | Instance of the application that wants to subscribe to the stream. |
Methods
acceptmethod
Signature
() => void
Description
Accepts the subscription request.
acceptOnBranchmethod
Signature
(branchKey: string) => void
Description
Accepts the request on a stream branch.
Parameters
Name | Type | Required | Description |
---|---|---|---|
branchKey | string | Key of the branch on which to accept the request. |
rejectmethod
Signature
(reason?: string) => void
Description
Rejects the request.
Parameters
Name | Type | Required | Description |
---|---|---|---|
reason | string | Reason for rejecting the request. |
InstanceTargetenumeration
Description
Which Interop server(s) to target when invoking Interop methods or subscribing to Interop streams.
- "best"
- "all"
- "skipMine"
- Instance
- Instance[]
InvokeErrorHandlerfunction
Signature
(error: { method: MethodDefinition; called_with: object; executed_by: Instance; message: string; status: number; returned: object; }) => void
Description
Handler to be called in case of method invocation error.
Parameters
Name | Type | Required | Description |
---|---|---|---|
error | { method: MethodDefinition; called_with: object; executed_by: Instance; message: string; status: number; returned: object; } | An error object. |
InvokeSuccessHandlerfunction
Signature
(result: InvocationResult<T>) => void
Description
Handler to be called if the method invocation succeeds.
Parameters
Name | Type | Required | Description |
---|---|---|---|
result | InvocationResult<T> | Result from the method invocation. |