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

Param | Type | Description
--- | --- | ---
[callback] | `function` | If a callback is passed the search is immediately started.
callback.err | `Error` | The callback handler
callback.result | `Array.<Service>` | An array of Service instances found on the network

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`

Param | Type | Description
--- | --- | ---
callback | `function` | The callback handler
callback.error | `Error` |
callback.service | `Service` | The service instance

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`

Param | Type | Description
--- | --- | ---
uri | `String` | The uri of the service (http://host:port/api/v2/)
callback | `function` | The callback handler
callback.error | `Error` |
callback.service | `Service` | The service instance

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

Param | Type | Description
--- | --- | ---
service | `Service` | the underlying service
id | `String` | can be an installed app id or url for a webapp
channelURI | `String` | a unique channel id (com.myapp.mychannel)

### 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`

Param | Type | Description
--- | --- | ---
attributes | `Object` | Any attributes to attach to your client
callback | `function` | The callback handler
callback.error | `Error` | Any error that may have occurred during the connection or application startup
callback.client | `Client` | Your client object

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`

Param | Type | Default | Description
--- | --- | --- | ---
[exitOnRemote] | `Boolean` | `true` | Issues a stop/exit on the remote application before disconnecting
[callback] | `function` |  | The callback handler
callback.error | `Error` |  | Any error that may have occurred during the connection or application startup
callback.client | `Client` |  | Your client object

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`

Param | Type | Description
--- | --- | ---
callback | `function` | The callback handler
callback.err | `function` | The callback handler

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`

Param | Type | Description
--- | --- | ---
true | `flag` | is SSL enabled

### 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`

Param | Type | Default | Description
--- | --- | --- | ---
event | `String` |  | The name of the event to emit
[message] | `any` |  | Any data associated with the event
[target] | `String` | `Array` | `'broadcast'` | The target recipient(s) of the message
[payload] | `Blob` | `ArrayBuffer` |  | Any binary data to send with the message

Example

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

### application.on(type, listener) ⇒

Adds a listener for the event.

Kind: instance method of `Application`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### 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

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### application.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of `Application`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
type | `String` | The event name to stop listening to
listener | `function` | The function that was originally add to handle the event

### application.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of `Application`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
event | `String` | The event name to stop listening to

### "connect" (client)

Fired when a channel makes a connection

Kind: event emitted by `Application`

Param | Type | Description
--- | --- | ---
client | `Client` | Your client

Example

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

### "disconnect" (client)

Fired when a channel disconnects

Kind: event emitted by `Application`

Param | Type | Description
--- | --- | ---
client | `Client` | Your client

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`

Param | Type | Description
--- | --- | ---
client | `Client` | The client that connected

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`

Param | Type | Description
--- | --- | ---
client | `Client` | The client that connected

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`

Param | Type | Description
--- | --- | ---
attributes | `Object` | Any attributes you want to associate with the client (ie. {name:"FooBar"}
callback | `function` | The success callback handler
callback.arg1 | `Error` | Any error that may have occurred
callback.arg2 | `Client` | The connecting client

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`

Param | Type | Description
--- | --- | ---
true | `flag` | is SSL enabled

### channel.disconnect(callback)

Disconnects from the channel

Kind: instance method of `Channel`

Param | Type | Description
--- | --- | ---
callback | `function` | The success callback handler
callback.error | `Error` | Any error that may have occurred
callback.client | `Client` | The disconnecting client

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`

Param | Type | Default | Description
--- | --- | --- | ---
event | `String` |  | The name of the event to emit
[message] | `any` |  | Any data associated with the event
[target] | `String` | `Array` | `'broadcast'` | The target recipient(s) of the message
[payload] | `Blob` | `ArrayBuffer` |  | Any binary data to send with the message

Example

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

### channel.on(type, listener) ⇒

Adds a listener for the event.

Kind: instance method of `Channel`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### 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

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### channel.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of `Channel`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
type | `String` | The event name to stop listening to
listener | `function` | The function that was originally add to handle the event

### channel.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of `Channel`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
event | `String` | The event name to stop listening to

### "connect" (client)

Fired when a channel makes a connection

Kind: event emitted by `Channel`

Param | Type | Description
--- | --- | ---
client | `Client` | Your client

Example

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

### "disconnect" (client)

Fired when a channel disconnects

Kind: event emitted by `Channel`

Param | Type | Description
--- | --- | ---
client | `Client` | Your client

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`

Param | Type | Description
--- | --- | ---
client | `Client` | The client that connected

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`

Param | Type | Description
--- | --- | ---
client | `Client` | The client that connected

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`

Param | Type | Description
--- | --- | ---
id | `String` | The client

## 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

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### 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

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### eventEmitter.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of `EventEmitter`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
type | `String` | The event name to stop listening to
listener | `function` | The function that was originally add to handle the event

### eventEmitter.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of `EventEmitter`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
event | `String` | The event name to stop listening to

## 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

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### 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

Param | Type | Description
--- | --- | ---
type | `String` | The event name to listen to
listener | `function` | The function to invoke when the event occurs

### search.off(type, listener) ⇒

Alias for removeListener

Kind: instance method of `Search`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
type | `String` | The event name to stop listening to
listener | `function` | The function that was originally add to handle the event

### search.removeAllListeners(event) ⇒

Removes all listeners, or those of the specified event.

Kind: instance method of `Search`
Returns: EventEmitter

Param | Type | Description
--- | --- | ---
event | `String` | The event name to stop listening to

### "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`

Param | Type | Description
--- | --- | ---
id | `String` | An installed application id or url of the web application
channelUri | `String` | The URI of the channel to connect to.

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`

Param | Type | Description
--- | --- | ---
uri | `String` | The uri of the Channel

Example

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