Interop

3.4.6

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

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.

Properties

Property	Type	Default	Required	Description
instance	Instance			Instance of the current application.

methodsForInstance
register
serverAdded
serverMethodAdded
serverMethodRemoved

serverRemoved
servers
subscribe
unregister
waitForMethod

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	Description
methodDefinition	string \| MethodDefinition	A unique string or a `MethodDefinition` for the stream to be registered.
options	StreamOptions	The `StreamOptions` object allows you to pass several optional callbacks which let your application handle subscriptions in a more detailed manner.
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	Description
method	string \| MethodDefinition	The unique `name` or the `MethodDefinition` of the method to be invoked.
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", `Instance`, `Instance[]`.
options	InvokeOptions	An optional [`InvokeOptions`] object specifying the timeouts to discover a method and to wait for a method reply.
success	InvokeSuccessHandler<T>	An `InvokeSuccessHandler` handler to be called if the invocation succeeds.
error	InvokeErrorHandler	An `InvokeErrorHandler` handler to be called in case of error.

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

Signature

(callback: (method: Method) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when a method is added for the first time by any application.

Parameters

Name	Type	Required	Description
callback	(method: Method) => void		A handler to be called when the event fires.

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

Signature

(server: Instance) => Method[]

Description

Returns all Interop methods registered by a server.

Parameters

Name	Type	Required	Description
server	Instance		An Interop `Instance` identifying an application.

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 `MethodDefinition` for the method to be registered.
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

Signature

(callback: (server: Instance) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an application offering methods is discovered.

Parameters

Name	Type	Required	Description
callback	(server: Instance) => void		A handler to be called when the event fires.

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.

Signature

(methodDefinition: string | MethodDefinition, parameters?: SubscriptionParams) => Promise<Subscription>

Description

Subscribes to an Interop stream.

Parameters

Name	Type	Required	Description
methodDefinition	string \| MethodDefinition		The unique `name` or the `MethodDefinition` of the stream to subscribe to.
parameters	SubscriptionParams		An optional `SubscriptionParams` object with parameters.

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 `name` or the `MethodDefinition` of the method to be unregistered.

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

Description

Each Interop application is identified by its Interop instance, which is a set of known key/value pairs.

Properties

Property	Type	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

getMethods

getStreams

getMethodsmethod

Signature

() => Method[]

Description

Returns all methods registered by that instance.

getStreamsmethod

Signature

() => Method[]

Description

Returns all streams registered by that instance.

Description

Extends InvocationResultCore. Results from a method invocation.

Properties

Property	Type	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.

Description

Result from a method invocation.

Properties

Property	Type	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.

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.

Description

An interop method

Properties

Property	Type	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 `true`, the method is a stream.
version	number	Method version.

Methods

getServers

getServersmethod

Signature

() => Instance[]

Description

Returns all servers that provide the method.

Description

An object describing an Interop method registered by an application.

Properties

Property	Type	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 `true`, the method is a stream.
version	number	Method version.

Methods

getServers

getServersmethod

Signature

() => Instance[]

Description

Returns all servers that provide the method.

Description

An object describing a filter matching one or more Interop methods.

Properties

Property	Type	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.

Description

Addition information around subscription being closed

Properties

Property	Type	Default	Required	Description
message	string
requestArguments	object
server	Instance
stream	MethodDefinition

Description

Object describing an Interop stream.

Properties

Property	Type	Default	Required	Description
definition	MethodDefinition			Stream definition object.
name	string			Name of the stream.

Methods

branch
branches
branches

branches
close
push

subscriptions

branchmethod

Signature

(key: string) => StreamBranch

Description

Returns a branch by key.

Parameters

Name	Type	Required	Description
key	string

branchesmethod

Signature

() => StreamBranch[]

Description

Returns the list of available stream branches.

branchesmethod

Signature

(key: string) => StreamBranch

Parameters

Name	Type	Required	Description
key	string

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.

Description

A stream branch created by the application.

Properties

Property	Type	Default	Required	Description
key	string			Branch key.

Methods

close

push

subscriptions

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

Signature

() => StreamSubscription[]

Description

All subscriptions to that branch.

Description

Stream data received by the subscriber.

Properties

Property	Type	Description
data	any	Data from the stream.
message	string	Message from the publisher of the stream.
private	boolean	If `true`, the data was sent to this application only.
requestArguments	any	Arguments used when the subscription was made.
server	Instance	Instance of the application publishing the stream.

Description

Optional handlers that can be supplied when creating streams.

Properties

Property	Type	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.

Description

An object describing a subscription to an Interop stream.

Properties

Property	Type	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

close

push

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.

Description

Stream subscription made by an application.

Properties

Property	Type	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

close
onClosed

onConnected
onData

onFailed

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

Signature

(callback: (server: Instance, reconnect: boolean) => void) => void

Description

Subscribe for the event which your subscription is connected to a server

Parameters

Name	Type	Required	Description
callback	(server: Instance, reconnect: boolean) => void

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

Description

Optional object with parameters passed to subscribe() when subscribing to a stream.

Properties

Property	Type	Default	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", `Instance`, `Instance[]`.
waitTimeoutMs	number	30000	Timeout to discover the stream, if not immediately available.

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

accept

acceptOnBranch

reject

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.

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.

API Reference Documentation

Interop

APIobject

Properties

Methods

createStreammethod

Signature

Description

Parameters

Example

invokemethod

Signature

Description

Parameters

Example

methodAddedmethod

Signature

Description

Parameters

methodRemovedmethod

Signature

Description

Parameters

methodsmethod

Signature

Description

Parameters

methodsForInstancemethod

Signature

Description

Parameters

registermethod

Signature

Description

Parameters

Example

serverAddedmethod

Signature

Description

Parameters

serverMethodAddedmethod

Signature

Description

Parameters

serverMethodRemovedmethod

Signature

Description

Parameters

serverRemovedmethod

Signature

Description

Parameters

serversmethod

Signature

Description

Parameters

subscribemethod

Signature

Description

Parameters

Example

unregistermethod

Signature

Description

Parameters

waitForMethodmethod

Signature

Description

Parameters

Instanceobject

Description

Properties

Methods

getMethodsmethod

Signature

Description

getStreamsmethod

Signature

Description

InvocationResultobject