@interopio/desktop API Reference

Access via:io.interop

Properties (1)

Property Type Default Required Description
instance⚓︎ Instance x

Instance of the current application.

17 Methods

createStream()⚓︎

(methodDefinition: string | MethodDefinition, options?: StreamOptions, successCallback?: (args?: object) => void, errorCallback?: (error?: string | object) => void) => Promise<Stream>

Creates a new Interop stream.

Parameters (4)

Name Type Required Description
methodDefinition⚓︎ string | MethodDefinition

A unique string or a MethodDefinition for the stream to be registered.
options⚓︎ StreamOptions x

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 x

An optional handler to be called if the creation of the stream succeeds.
errorCallback⚓︎ (error?: string | object) => void x

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);

invoke()⚓︎

<T>(method: string | MethodDefinition, argumentObj?: object, target?: InstanceTarget, options?: InvokeOptions, success?: InvokeSuccessHandler<T>, error?: InvokeErrorHandler) => Promise<InvocationResult<T>>

Invokes an Interop method with some arguments on target servers.

Parameters (6)

Name Type Required Description
method⚓︎ string | MethodDefinition

The unique name or the MethodDefinition of the method to be invoked.
argumentObj⚓︎ object x

A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop method.
target⚓︎ InstanceTarget x

Specifies which servers to target. Can be one of: "best", "all", Instance, Instance[].
options⚓︎ InvokeOptions x

An optional [InvokeOptions] object specifying the timeouts to discover a method and to wait for a method reply.
success⚓︎ InvokeSuccessHandler<T> x

An InvokeSuccessHandler handler to be called if the invocation succeeds.
error⚓︎ InvokeErrorHandler x

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}`);
    });

methodAdded()⚓︎

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

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

Parameters (1)

Name Type Required Description
callback⚓︎ (method: Method) => void

A handler to be called when the event fires.

methodRemoved()⚓︎

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

Subscribes to the event which fires when a method is removed from the last application offering it.

Parameters (1)

Name Type Required Description
callback⚓︎ (method: Method) => void

A handler to be called when the event fires.

methods()⚓︎

(filter?: MethodFilter | string) => Method[]

Returns all methods that match the passed filter. If no filter is specified, returns all methods.

Parameters (1)

Name Type Required Description
filter⚓︎ MethodFilter | string x

An object describing a filter matching one or more Interop methods. If string will match the method by name

methodsForInstance()⚓︎

(server: Instance) => Method[]

Returns all Interop methods registered by a server.

Parameters (1)

Name Type Required Description
server⚓︎ Instance

An Interop Instance identifying an application.

register()⚓︎

<T,R>(name: string | MethodDefinition, handler: (args: T, caller: Instance) => R | void | Promise<R>) => Promise<void>

Registers a new Interop method.

Parameters (2)

Name Type Required Description
name⚓︎ string | MethodDefinition

A unique string or a MethodDefinition for the method to be registered.
handler⚓︎ (args: T, caller: Instance) => R | void | 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 };
    },
);

serverAdded()⚓︎

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

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

Parameters (1)

Name Type Required Description
callback⚓︎ (server: Instance) => void

A handler to be called when the event fires.

serverMethodAdded()⚓︎

(callback: (info: { server: Instance; method: Method; }) => void) => UnsubscribeFunction

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 (1)

Name Type Required Description
callback⚓︎ (info: { server: Instance; method: Method; }) => void x

serverMethodRemoved()⚓︎

(callback: ( info: { server: Instance; method: Method; } ) => void) => UnsubscribeFunction

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 (1)

Name Type Required Description
callback⚓︎ ( info: { server: Instance; method: Method; } ) => void

A handler to be called when the event fires.

serverMethodUpdated()⚓︎

(callback: (info: { server: Instance; method: Method; }) => void) => UnsubscribeFunction

Notifies when an app updates the properties of an Interop method it offers. Returns an unsubscribe function.

@interopio/core 6.12.0@interopio/desktop 6.22.0

Parameters (1)

Name Type Required Description
callback⚓︎ (info: { server: Instance; method: Method; }) => void

Callback function for handling the event. Receives as an argument an object with server and method properties describing the Interop server that has registered the updated method and the Interop method whose properties have been updated.

serverRemoved()⚓︎

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

Subscribes to the event which fires when an app offering methods stops offering them or exits.

Parameters (1)

Name Type Required Description
callback⚓︎ (server: Instance) => void

A handler to be called when the event fires.

servers()⚓︎

(filter?: MethodFilter) => Instance[]

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 (1)

Name Type Required Description
filter⚓︎ MethodFilter x

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

subscribe()⚓︎

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

Subscribes to an Interop stream.

Parameters (2)

Name Type Required Description
methodDefinition⚓︎ string | MethodDefinition

The unique name or the MethodDefinition of the stream to subscribe to.
parameters⚓︎ SubscriptionParams x

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
    });

unregister()⚓︎

(definition: string | MethodDefinition) => Promise<void>

Unregisters an Interop method.

Parameters (1)

Name Type Required Description
definition⚓︎ string | MethodDefinition

The unique name or the MethodDefinition of the method to be unregistered.

updateMethod()⚓︎

(name: string, definition: MethodDefinitionUpdate) => Promise<void>

Updates the mutable properties of an Interop method registered by the current app. Properties that are omitted from the update, or explicitly set to undefined, will retain their current values.

@interopio/core 6.12.0@interopio/desktop 6.22.0

Parameters (2)

Name Type Required Description
name⚓︎ string

The name of the registered Interop method to update.
definition⚓︎ MethodDefinitionUpdate

The Interop method properties to update.

waitForMethod()⚓︎

(name: string) => Promise<Method>

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 (1)

Name Type Required Description
name⚓︎ string

Name of the method to wait for