Modules

msf

The 'msf' module/object is the entry point for the API. If including the library via script tag it will be a global object attached to the window or the export of the module if using amd/commonjs (requirejs/browserify)

Classes

Application ⇐ Channel

Channel ⇐ EventEmitter

Client

ClientList ⇐ Array

EventEmitter

Search ⇐ EventEmitter

Service

msf

The 'msf' module/object is the entry point for the API. If including the library via script tag it will be a global object attached to the window or the export of the module if using amd/commonjs (requirejs/browserify)

• msf
  • .search([callback]) ⇒ Search
  • .local(callback)
  • .remote(uri, callback)

msf.search([callback]) ⇒ Search

Searches the local network for compatible multiscreen services

Kind: static method of msf
Returns: Search - A search instance (a singleton is used to reduce page resources)

Example

msf.search(function(err, services){
  if(err) return console.error('something went wrong', err.message);
  console.log('found '+services.length+' services');
}

// OR

var search = msf.search();
search.on('found', function(service){
   console.log('found service '+service.name);
}
search.start();

msf.local(callback)

Retrieves a reference to the service running on the current device. This is typically only used on the 'host' device.

Kind: static method of msf

Example

msf.local(function(err, service){
  console.log('my service name is '+service.name);
}

msf.remote(uri, callback)

Retrieves a service instance by it's uri

Kind: static method of msf

Example

msf.remote('http://host:port/api/v2/',function(err, service){
  console.log('the service name is '+service.name);
}

Application ⇐ Channel

Kind: global class
Extends: Channel
Hide-constructor:

• Application ⇐ Channel
  • new Application(service, id, channelURI)
  • .id : String
  • .clients : ClientList
  • .isConnected : Boolean
  • .connectionTimeout : Boolean
  • .connect(attributes, callback)
  • .disconnect([exitOnRemote], [callback])
  • .install(callback)
  • .setSecurityMode(true)
  • .publish(event, [message], [target], [payload])
  • .on(type, listener) ⇒
  • .once(type, listener) ⇒
  • .off(type, listener) ⇒
  • .removeAllListeners(event) ⇒
  • "connect" (client)
  • "disconnect" (client)
  • "clientConnect" (client)
  • "clientDisconnect" (client)

new Application(service, id, channelURI)

An Application represents an application on the remote device. Use the class to control various aspects of the application such launching the app or getting information

application.id : String

The id of the application (this can be a url or installed application id)

Kind: instance property of Application
Read only: true

application.clients : ClientList

The collection of clients currently connected to the channel

Kind: instance property of Application
Read only: true

application.isConnected : Boolean

The connection status of the channel

Kind: instance property of Application
Read only: true

application.connectionTimeout : Boolean

Sets the connection timeout. When set the channel will utilize a connection health check while connected. If no pinging health check is not received within the given timeout the connection will close. To stop the health check set the timeout to 0

Kind: instance property of Application
Example

channel.connectionTimeout = 10000; // checks the connection every 10 seconds while connected
channel.connectionTimeout = 0; // stops the health check

application.connect(attributes, callback)

Starts and connects to the application on the remote device. Similar to the Channel 'connect' method but within an Application the 'connect' callback and event will be only be called when the remote application has launched and is ready to receive messages.

Kind: instance method of Application
Overrides: connect

Example

app.connect({displayName:'Wheezy'},function(err, client){
  if(err) return console.error('something went wrong : ', error.code, error.message);
  console.info('You are now connected');
});

application.disconnect([exitOnRemote], [callback])

Disconnects your client from the remote application. If the first argument is an optional param and can be used close the remote application The stop/exit command is only sent if you are the last connected client

Kind: instance method of Application
Overrides: disconnect

Example

app.disconnect(function(err){
    if(err) return console.error('something went wrong');
    console.info('You are now disconnected');
});

application.install(callback)

Installs the application on the remote device.

Kind: instance method of Application

Example

app.connect({name:'Jason'}, function(err, client){
   if(err.code === 404){
     var install = confirm('Would you like to install the MyApp on your TV?');
     if(install){
        app.install(function(err){
           alert('Please follow the prompts on your TV to install the application');
        });
    }
  }
 });

application.setSecurityMode(true)

set to the security mode

Kind: instance method of Application

application.publish(event, [message], [target], [payload])

Publish an event message to the specified target or targets. Targets can be in the for of a clients id, an array of client ids or one of the special message target strings (ie. "all" or "host"}

Kind: instance method of Application

Example

channel.publish('myCustomEventName',{custom:'data'});

application.on(type, listener) ⇒

Adds a listener for the event.

Kind: instance method of Application
Returns: EventEmitter

application.once(type, listener) ⇒

Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.

Kind: instance method of Application
Returns: EventEmitter

application.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of Application
Returns: EventEmitter

application.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of Application
Returns: EventEmitter

"connect" (client)

Fired when a channel makes a connection

Kind: event emitted by Application

Example

channel.on('connect',function(client){
 console.log('You are now connected');
});

"disconnect" (client)

Fired when a channel disconnects

Kind: event emitted by Application

Example

channel.on('disconnect',function(client){
 console.log('You are now disconnected');
});

"clientConnect" (client)

Fired when a peer client channel makes a connection

Kind: event emitted by Application

Example

channel.on('clientConnect',function(client){
 console.log(client.id + 'is now connected');
});

"clientDisconnect" (client)

Fired when a peer client disconnects

Kind: event emitted by Application

Example

channel.on('clientDisconnect',function(client){
 console.log(client.id + 'has disconnected');
});

Channel ⇐ EventEmitter

Kind: global class
Extends: EventEmitter
Hide-constructor:

• Channel ⇐ EventEmitter
  • new Channel()
  • .clients : ClientList
  • .isConnected : Boolean
  • .connectionTimeout : Boolean
  • .connect(attributes, callback)
  • .setSecurityMode(true)
  • .disconnect(callback)
  • .publish(event, [message], [target], [payload])
  • .on(type, listener) ⇒
  • .once(type, listener) ⇒
  • .off(type, listener) ⇒
  • .removeAllListeners(event) ⇒
  • "connect" (client)
  • "disconnect" (client)
  • "clientConnect" (client)
  • "clientDisconnect" (client)

new Channel()

A Channel is a discreet connection where multiple clients can communicate

channel.clients : ClientList

The collection of clients currently connected to the channel

Kind: instance property of Channel
Read only: true

channel.isConnected : Boolean

The connection status of the channel

Kind: instance property of Channel
Read only: true

channel.connectionTimeout : Boolean

Sets the connection timeout. When set the channel will utilize a connection health check while connected. If no pinging health check is not received within the given timeout the connection will close. To stop the health check set the timeout to 0

Kind: instance property of Channel
Example

channel.connectionTimeout = 10000; // checks the connection every 10 seconds while connected
channel.connectionTimeout = 0; // stops the health check

channel.connect(attributes, callback)

Connects to the channel

Kind: instance method of Channel

Example

channel.connect({name:'Wheezy'},function(err, client){
  if(err) return console.error('something went wrong : ', error.code, error.message);
  console.info(client.attributes.name+', you are now connected');
});

channel.setSecurityMode(true)

set to the security mode

Kind: instance method of Channel

channel.disconnect(callback)

Disconnects from the channel

Kind: instance method of Channel

Example

channel.disconnect(function(err, client){
  if(err) return console.error('something went wrong : ', error.code, error.message);
  console.info(client.attributes.name+', you are now disconnected');
});

channel.publish(event, [message], [target], [payload])

Publish an event message to the specified target or targets. Targets can be in the for of a clients id, an array of client ids or one of the special message target strings (ie. "all" or "host"}

Kind: instance method of Channel

Example

channel.publish('myCustomEventName',{custom:'data'});

channel.on(type, listener) ⇒

Adds a listener for the event.

Kind: instance method of Channel
Returns: EventEmitter

channel.once(type, listener) ⇒

Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.

Kind: instance method of Channel
Returns: EventEmitter

channel.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of Channel
Returns: EventEmitter

channel.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of Channel
Returns: EventEmitter

"connect" (client)

Fired when a channel makes a connection

Kind: event emitted by Channel

Example

channel.on('connect',function(client){
 console.log('You are now connected');
});

"disconnect" (client)

Fired when a channel disconnects

Kind: event emitted by Channel

Example

channel.on('disconnect',function(client){
 console.log('You are now disconnected');
});

"clientConnect" (client)

Fired when a peer client channel makes a connection

Kind: event emitted by Channel

Example

channel.on('clientConnect',function(client){
 console.log(client.id + 'is now connected');
});

"clientDisconnect" (client)

Fired when a peer client disconnects

Kind: event emitted by Channel

Example

channel.on('clientDisconnect',function(client){
 console.log(client.id + 'has disconnected');
});

Client

Kind: global class
Hide-constructor:

• Client
  • new Client()
  • .id : String
  • .attributes : Object
  • .isHost : Boolean
  • .connectTime : Number

new Client()

A representation of an individual device or user connected to a channel. Clients can have user defined attributes that are readable by all other clients.

client.id : String

The id of the client

Kind: instance property of Client
Read only: true

client.attributes : Object

A map of attributes passed by the client when connecting

Kind: instance property of Client
Read only: true

client.isHost : Boolean

Flag for determining if the client is the host

Kind: instance property of Client
Read only: true

client.connectTime : Number

The time which the client connected in epoch milliseconds

Kind: instance property of Client
Read only: true

ClientList ⇐ Array

Kind: global class
Extends: Array
Hide-constructor:

• ClientList ⇐ Array
  • new ClientList()
  • .me : Client
  • .getById(id) ⇒ Client

new ClientList()

A list of clients accessible through channel.clients. This list is managed by the channel and automatically adds and removes clients as they connect and disconnect

clientList.me : Client

A reference to your client

Kind: instance property of ClientList
Read only: true

clientList.getById(id) ⇒ Client

Returns a client by id

Kind: instance method of ClientList

EventEmitter

Kind: global class
Hide-constructor:

• EventEmitter
  • new EventEmitter()
  • .on(type, listener) ⇒
  • .once(type, listener) ⇒
  • .off(type, listener) ⇒
  • .removeAllListeners(event) ⇒

new EventEmitter()

All objects which emit events are instances of EventEmitter. The EventEmitter class is derived from the nodejs EventEmitter.

For simplicity only the most used members are documented here, for full documentation read http://nodejs.org/api/events.html

eventEmitter.on(type, listener) ⇒

Adds a listener for the event.

Kind: instance method of EventEmitter
Returns: EventEmitter

eventEmitter.once(type, listener) ⇒

Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.

Kind: instance method of EventEmitter
Returns: EventEmitter

eventEmitter.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of EventEmitter
Returns: EventEmitter

eventEmitter.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of EventEmitter
Returns: EventEmitter

Search ⇐ EventEmitter

Kind: global class
Extends: EventEmitter
Hide-constructor:

• Search ⇐ EventEmitter
  • new Search()
  • .start()
  • .stop()
  • .on(type, listener) ⇒
  • .once(type, listener) ⇒
  • .off(type, listener) ⇒
  • .removeAllListeners(event) ⇒
  • "found"
  • "error"
  • "start"
  • "stop"

new Search()

Provides members related to Service discovery.

search.start()

Starts the search, looking for devices it can reach on the network If a search is already in progress it will NOT begin a new search

Kind: instance method of Search
Example

var search = msf.search();
search.on('found', function(service){
   console.log('found service '+service.name);
}
search.start();

search.stop()

Stops the current search in progress (no 'found' events or search callbacks will fire)

Kind: instance method of Search
Example

search.stop();

search.on(type, listener) ⇒

Adds a listener for the event.

Kind: instance method of Search
Returns: EventEmitter

search.once(type, listener) ⇒

Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.

Kind: instance method of Search
Returns: EventEmitter

search.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of Search
Returns: EventEmitter

search.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of Search
Returns: EventEmitter

"found"

Fired when a search has discovered compatible services

Kind: event emitted by Search
Example

search.on('found', function(service){
   console.log('found '+service.name);
});

"error"

Fired when a search error has occurred

Kind: event emitted by Search
Example

search.on('error', function(err){
   console.error('something went wrong', err.message);
});

"start"

Fired when a search has been started

Kind: event emitted by Search
Example

search.on('start', function(){
   ui.setState('searching');
});

"stop"

Fired when a search has been stopped

Kind: event emitted by Search
Example

search.on('stop', function(){
   ui.setState('stopped');
});

Service

Kind: global class
Hide-constructor:

• Service
  • new Service()
  • .id : String
  • .name : String
  • .version : String
  • .type : String
  • .uri : String
  • .device : String
  • .application(id, channelUri) ⇒ Application
  • .channel(uri) ⇒ Channel

new Service()

A Service instance represents the multiscreen service running on the remote device, such as a SmartTV

service.id : String

The id of the service

Kind: instance property of Service
Read only: true

service.name : String

The name of the service (Living Room TV)

Kind: instance property of Service
Read only: true

service.version : String

The version of the service (x.x.x)

Kind: instance property of Service
Read only: true

service.type : String

The type of the service (Samsung SmartTV)

Kind: instance property of Service
Read only: true

service.uri : String

The uri of the service (http://:/api/v2/)

Kind: instance property of Service
Read only: true

service.device : String

A hash of additional information about the device the service is running on

Kind: instance property of Service
Read only: true

service.application(id, channelUri) ⇒ Application

Creates Application instances belonging to that service

Kind: instance method of Service

Example

var application = service.application('http://mydomain/myapp/', 'com.mydomain.myapp');

service.channel(uri) ⇒ Channel

creates a channel of the service ('mychannel')

Kind: instance method of Service

Example

var channel = service.channel('com.mydomain.myapp');