An open API service indexing awesome lists of open source software.

https://github.com/elastos/elastos.net.carrier.cordova.sdk


https://github.com/elastos/elastos.net.carrier.cordova.sdk

Last synced: 2 months ago
JSON representation

Awesome Lists containing this project

README

        

---
title: Carrier
description: The carrier javascript API.
---

# elastos-cordova-plugin-carrier

This plugin defines a global `cordova.carrierPlugin` object, which provides an API for carrier library.

Although in the global scope, it is not available until after the `deviceready` event.

```js
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(carrierPlugin);
}
```
---

## Installation

The plugins field of dapp manifest.json adds Carrier values, such as "plugins": ["XXXX", "Carrier", "XXXX"]

## Supported Platforms

- Android
- iOS

# API Reference

## Modules


carrierPlugin


## Classes


Stream


Session


Carrier


## Typedefs



BootstrapNode : Object


The Carrier user information.




Options : Object


Options defines several settings that control the way the Carrier node connects to the carrier network.
Default values are not defined for bootstraps options, so application should be set bootstrap nodes clearly.




UserInfo : Object


The Carrier user information.




FriendInfo : Object


The Carrier friend information.




AddressInfo : Object


The netword address information.




TransportInfo : Object


The netword transport information.




CarrierCallbacks : Object


The Carrier callbacks.




StreamCallbacks : Object


The Stream callbacks.




onFriendInviteResponse : function


The callback function to process the friend invite response.




onSessionRequestComplete : function


The callback function to receive session request complete event.




onStateChanged : function


The callback function to report state of stream when it's state changes.




onStreamData : function


The callback will be called when the stream receives incoming packet.
If the stream enabled multiplexing mode, application will not
receive stream-layered data callback any more. All data will reported
as multiplexing channel data.




onChannelOpen : function


The callback function to be called when new multiplexing channel request to open.




onChannelOpened : function


The callback function to be called when new multiplexing channel opened.




onChannelClose : function


The callback function to be called when channel close.




onChannelData : function


The callback functiont to be called when channel received incoming data.




onChannelPending : function


The callback function to be called when remote peer ask to pend data sending.




onChannelResume : function


The callback function to be called when remote peer ask to resume data sending.




onConnection : function


The callback function to process the self connection status.




onReady : function


The callback function to process the ready notification.


Application should wait this callback invoked before calling any
function to interact with friends.




onSelfInfoChanged : function


The callback function to process the self info changed event.




onFriends : function


The callback function to iterate the each friend item in friend list.




onFriendConnection : function


The callback function to process the friend connections status changed event.




onFriendInfoChanged : function


The callback function to process the friend information changed event.




onFriendPresence : function


The callback function to process the friend presence changed event.




onFriendRequest : function


The callback function to process the friend request.




onFriendAdded : function


The callback function to process the new friend added event.




onFriendRemoved : function


The callback function to process the friend removed event.




onFriendMessage : function


The callback function to process the friend message.




onFriendInviteRequest : function


The callback function to process the friend invite request.




onSessionRequest : function


The callback function that handle session request.



## carrierPlugin

* [carrierPlugin](#module_carrierPlugin)
* [.ConnectionStatus](#module_carrierPlugin+ConnectionStatus) : enum
* [.PresenceStatus](#module_carrierPlugin+PresenceStatus) : enum
* [.StreamType](#module_carrierPlugin+StreamType) : enum
* [.StreamState](#module_carrierPlugin+StreamState) : enum
* [.CandidateType](#module_carrierPlugin+CandidateType) : enum
* [.NetworkTopology](#module_carrierPlugin+NetworkTopology) : enum
* [.PortForwardingProtocol](#module_carrierPlugin+PortForwardingProtocol) : enum
* [.CloseReason](#module_carrierPlugin+CloseReason) : enum
* [.StreamMode](#module_carrierPlugin+StreamMode) : enum
* [.getVersion(onSuccess, [onError], onSuccess)](#module_carrierPlugin+getVersion)
* [.isValidId(onSuccess, [onError], id)](#module_carrierPlugin+isValidId)
* [.isValidAddress(onSuccess, [onError], address)](#module_carrierPlugin+isValidAddress)
* [.getIdFromAddress(onSuccess, [onError], address)](#module_carrierPlugin+getIdFromAddress)
* [.createObject(onSuccess, [onError], [options], callbacks)](#module_carrierPlugin+createObject)

### carrierPlugin.ConnectionStatus : enum
Carrier node connection status to the carrier network.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| CONNECTED | number | 0 | Carrier node connected to the carrier network. |
| DISCONNECTED | number | 1 | There is no connection to the carrier network. |

### carrierPlugin.PresenceStatus : enum
Carrier node presence status.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| NONE | number | 0 | Carrier node is online and available. |
| AWAY | number | 1 | Carrier node is being away. |
| BUSY | number | 2 | Carrier node is being busy. |

### carrierPlugin.StreamType : enum
Carrier stream type. Reference: https://tools.ietf.org/html/rfc4566#section-5.14 https://tools.ietf.org/html/rfc4566#section-8

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| AUDIO | number | 0 | Audio stream. |
| VIDEO | number | 1 | Video stream. |
| TEXT | number | 2 | Text stream. |
| APPLICATION | number | 3 | Application stream. |
| MESSAGE | number | 4 | Message stream. |

### carrierPlugin.StreamState : enum
Carrier stream state The stream state will be changed according to the phase of the stream.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| RAW | number | 0 | Raw stream. |
| INITIALIZED | number | 1 | Initialized stream. |
| TRANSPORT_READY | number | 2 | The underlying transport is ready for the stream to start. |
| CONNECTING | number | 3 | The stream is trying to connect the remote. |
| CONNECTED | number | 4 | The stream connected with remove peer. |
| DEACTIVATED | number | 5 | The stream is deactived. |
| CLOSED | number | 6 | The stream closed gracefully. |
| ERROR | number | 7 | The stream is on error, cannot to continue. |

### carrierPlugin.CandidateType : enum
Carrier Stream's candidate type.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| HOST | number | 0 | Host candidate. |
| SERVE_RREFLEXIVE | number | 1 | Server reflexive, only valid to ICE transport. |
| PEER_REFLEXIVE | number | 2 | Peer reflexive, only valid to ICE transport. |
| RELAYED | number | 3 | Relayed Candidate, only valid to ICE tranport. |

### carrierPlugin.NetworkTopology : enum
Carrier network topology for session peers related to each other.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| LAN | number | 0 | LAN network topology. |
| P2P | number | 1 | P2P network topology. |
| RELAYED | number | 2 | Relayed netowrk topology. |

### carrierPlugin.PortForwardingProtocol : enum
Port forwarding supported protocols.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| TCP | number | 1 | TCP protocol. |

### carrierPlugin.CloseReason : enum
Multiplexing channel close reason mode.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| NORMAL | number | 0 | Channel closed normaly. |
| TIMEOUT | number | 1 | Channel closed because of timeout. |
| ERROR | number | 2 | Channel closed because error occured. |

### carrierPlugin.StreamMode : enum
Carrier stream mode.

**Kind**: instance enum of [carrierPlugin](#module_carrierPlugin)
**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| COMPRESS | number | 1 | Compress option, indicates data would be compressed before transmission. For now, just reserved this bit option for future implement. |
| PLAIN | number | 2 | Encrypt option, indicates data would be transmitted with plain mode. which means that transmitting data would be encrypted in default. |
| RELIABLE | number | 4 | Relaible option, indicates data transmission would be reliable, and be guranteed to received by remote peer, which acts as TCP transmission protocol. Without this option bitwised, the transmission would be unreliable as UDP transmission protocol. |
| MULTIPLEXING | number | 8 | Multiplexing option, indicates multiplexing would be activated on enstablished stream, and need to use multipexing APIs related with channel instread of APIs related strema to send/receive data. |
| PORT_FORWARDING | number | 16 | PortForwarding option, indicates port forwarding would be activated on established stream. This options should bitwise with 'Multiplexing' option. |

### carrierPlugin.getVersion(onSuccess, [onError], onSuccess)
Get current version of Carrier node.

**Kind**: instance method of [carrierPlugin](#module_carrierPlugin)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a String: The version of carrier node. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| onSuccess | callback | The version of carrier node |

### carrierPlugin.isValidId(onSuccess, [onError], id)
Check if the ID is Carrier node id.

**Kind**: instance method of [carrierPlugin](#module_carrierPlugin)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a Boolean: True if id is valid, otherwise false. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| id | string | The carrier node id to be check. |

### carrierPlugin.isValidAddress(onSuccess, [onError], address)
Check if the carrier node address is valid.

**Kind**: instance method of [carrierPlugin](#module_carrierPlugin)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a Boolean: True if key is valid, otherwise false. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| address | string | The carrier node address to be check. |

### carrierPlugin.getIdFromAddress(onSuccess, [onError], address)
Get carrier ID from carrier node address.

**Kind**: instance method of [carrierPlugin](#module_carrierPlugin)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a String: User id if address is valid, otherwise null. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| address | string | The carrier node address. |

### carrierPlugin.createObject(onSuccess, [onError], [options], callbacks)
Create a carrier object instance. After initializing the instance,
it's ready to start and therefore connect to carrier network.

**Kind**: instance method of [carrierPlugin](#module_carrierPlugin)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| [options] | [Options](#Options) | The options to set for creating carrier node. If set to null, will use default. |
| callbacks | [CarrierCallbacks](#CarrierCallbacks) | The callbacks for carrier node. |

## Stream
**Kind**: global class

* [Stream](#Stream)
* [new Stream()](#new_Stream_new)
* [.id](#Stream+id)
* [.carrier](#Stream+carrier)
* [.session](#Stream+session)
* [.on(name, callback)](#Stream+on)
* [.getTransportInfo(onSuccess, [onError])](#Stream+getTransportInfo)
* [.write(onSuccess, [onError], data)](#Stream+write)
* [.openChannel(onSuccess, [onError], cookie)](#Stream+openChannel)
* [.closeChannel(onSuccess, [onError], channel)](#Stream+closeChannel)
* [.writeChannel(onSuccess, [onError], channel, data)](#Stream+writeChannel)
* [.pendChannel(onSuccess, [onError], channel)](#Stream+pendChannel)
* [.resumeChannel(onSuccess, [onError], channel)](#Stream+resumeChannel)
* [.openPortForwarding(onSuccess, [onError], service, protocol, host, port)](#Stream+openPortForwarding)
* [.closePortForwarding(onSuccess, [onError], portForwarding)](#Stream+closePortForwarding)

### new Stream()
The class representing Carrier stream.

### stream.id
**Kind**: instance property of [Stream](#Stream)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| id | number | Stream ID. |

### stream.carrier
**Kind**: instance property of [Stream](#Stream)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Parent carrier object. |

### stream.session
**Kind**: instance property of [Stream](#Stream)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| session | [Session](#Session) | Parent session object. |

### stream.on(name, callback)
Add or remove Stream callback.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| name | string | The callback name. |
| callback | function | The function to add or change callback function. If set to null, will remove callback. |

### stream.getTransportInfo(onSuccess, [onError])
Get tranport info of carrier stream.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a TransportInfo object |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |

### stream.write(onSuccess, [onError], data)
Send outgoing data to remote peer.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a number: Bytes of data sent. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| data | base64 | The send data. |

### stream.openChannel(onSuccess, [onError], cookie)
Open a new channel on multiplexing stream.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a number: New channel ID. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| cookie | string | The application defined data passed to remote peer |

### stream.closeChannel(onSuccess, [onError], channel)
Close a new channel on multiplexing stream.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| channel | number | The channel ID to close |

### stream.writeChannel(onSuccess, [onError], channel, data)
Send outgoing data to remote peer.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a number: Bytes of data sent. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| channel | number | The current channel ID. |
| data | base64 | The send data. |

### stream.pendChannel(onSuccess, [onError], channel)
Request remote peer to pend channel data sending.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| channel | number | The current channel ID. |

### stream.resumeChannel(onSuccess, [onError], channel)
Request remote peer to resume channel data sending.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| channel | number | The current channel ID. |

### stream.openPortForwarding(onSuccess, [onError], service, protocol, host, port)
Open a port forwarding to remote service over multiplexing.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a number: Port forwarding ID. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| service | string | The remote service name |
| protocol | PortForwardingProtocol | Port forwarding protocol |
| host | string | Local host or ip to binding. If host is null, port forwarding will bind to localhost |
| port | number | Local port to binding. |

### stream.closePortForwarding(onSuccess, [onError], portForwarding)
Close a port forwarding.
If the stream is in multiplexing mode, application can not call this function.

**Kind**: instance method of [Stream](#Stream)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| portForwarding | number | The portforwarding ID. |

## Session
**Kind**: global class

* [Session](#Session)
* [new Session()](#new_Session_new)
* [.peer](#Session+peer)
* [.carrier](#Session+carrier)
* [.close()](#Session+close)
* [.request(onSuccess, [onError], handler)](#Session+request)
* [.replyRequest(onSuccess, [onError], status, reason)](#Session+replyRequest)
* [.start(onSuccess, [onError], sdp)](#Session+start)
* [.addStream(onSuccess, [onError], type, options, callbacks)](#Session+addStream)
* [.removeStream(onSuccess, [onError], stream)](#Session+removeStream)
* [.addService(onSuccess, [onError], service, protocol, host, port)](#Session+addService)
* [.removeService(onSuccess, [onError], service)](#Session+removeService)

### new Session()
The class representing Carrier Session.

### session.peer
**Kind**: instance property of [Session](#Session)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| peer | string | The remote peer userid. |

### session.carrier
**Kind**: instance property of [Session](#Session)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Parent carrier object. |

### session.close()
Close a session to friend. All resources include streams, channels, portforwardings
associated with current session will be destroyed.

**Kind**: instance method of [Session](#Session)

### session.request(onSuccess, [onError], handler)
Send session request to the friend.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| handler | [onSessionRequestComplete](#onSessionRequestComplete) | A handler to the SessionRequestCompleteHandler to receive the session response |

### session.replyRequest(onSuccess, [onError], status, reason)
Reply the session request from friend.

This function will send a session response to friend.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| status | number | The status code of the response. 0 is success, otherwise is error |
| reason | string | The error message if status is error, or null if success |

### session.start(onSuccess, [onError], sdp)
Begin to start a session.

All streams in current session will try to connect with remote friend,
The stream status will update to application by stream's StreamHandler.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| sdp | string | The remote user's SDP. Reference: https://tools.ietf.org/html/rfc4566 |

### session.addStream(onSuccess, [onError], type, options, callbacks)
Add a new stream to session.

Carrier stream supports several underlying transport mechanisms:

- Plain/encrypted UDP data gram protocol
- Plain/encrypted TCP like reliable stream protocol
- Multiplexing over UDP
- Multiplexing over TCP like reliable protocol

Application can use options to specify the new stream mode.
Multiplexing over UDP can not provide reliable transport.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a Stream object: The new added carrier stream. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| type | StreamType | The stream type defined in StreamType |
| options | number | The stream mode options. options are constructed by a bitwise-inclusive OR of flags |
| callbacks | [StreamCallbacks](#StreamCallbacks) | The stream callbacks. |

### session.removeStream(onSuccess, [onError], stream)
Remove a stream from session.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| stream | stream | The Stream to be removed |

### session.addService(onSuccess, [onError], service, protocol, host, port)
Add a new portforwarding service to session.

The registered services can be used by remote peer in portforwarding request.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| service | string | The new service name, should be unique in session scope. |
| protocol | PortForwardingProtocol | The protocol of the service. |
| host | string | The host name or ip of the service. |
| port | number | The port of the service. |

### session.removeService(onSuccess, [onError], service)
Remove a portforwarding server to session.

This function has not effect on existing portforwarings.

**Kind**: instance method of [Session](#Session)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| service | string | The service name. |

## Carrier
**Kind**: global class

* [Carrier](#Carrier)
* [new Carrier()](#new_Carrier_new)
* [.nodeId](#Carrier+nodeId)
* [.userId](#Carrier+userId)
* [.address](#Carrier+address)
* [.nospam](#Carrier+nospam)
* [.presence](#Carrier+presence)
* [.on(name, callback)](#Carrier+on)
* [.start(onSuccess, [onError], iterateInterval)](#Carrier+start)
* [.getSelfInfo(onSuccess, [onError])](#Carrier+getSelfInfo)
* [.setSelfInfo(onSuccess, [onError], userinfo)](#Carrier+setSelfInfo)
* [.isReady(onSuccess, [onError])](#Carrier+isReady)
* [.getFriends(onSuccess, [onError])](#Carrier+getFriends)
* [.getFriend(onSuccess, [onError], userId)](#Carrier+getFriend)
* [.labelFriend(onSuccess, [onError], userId, label)](#Carrier+labelFriend)
* [.isFriend(onSuccess, [onError], userId)](#Carrier+isFriend)
* [.addFriend(onSuccess, [onError], address, hello)](#Carrier+addFriend)
* [.acceptFriend(onSuccess, [onError], userId)](#Carrier+acceptFriend)
* [.removeFriend(onSuccess, [onError], userId)](#Carrier+removeFriend)
* [.sendFriendMessage(onSuccess, [onError], to, message)](#Carrier+sendFriendMessage)
* [.inviteFriend(onSuccess, [onError], to, data, handler)](#Carrier+inviteFriend)
* [.replyFriendInvite(onSuccess, [onError], to, status, reason, data)](#Carrier+replyFriendInvite)
* [.newSession(onSuccess, [onError], to)](#Carrier+newSession)
* [.destroy(onSuccess, [onError])](#Carrier+destroy)

### new Carrier()
The class representing Carrier.

### carrier.nodeId
**Kind**: instance property of [Carrier](#Carrier)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| nodeId | string | Node id. |

### carrier.userId
**Kind**: instance property of [Carrier](#Carrier)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| userId | string | User id. |

### carrier.address
**Kind**: instance property of [Carrier](#Carrier)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| address | string | Node address. |

### carrier.nospam
**Kind**: instance property of [Carrier](#Carrier)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| nospam | number | The nospam for Carrier address is used to eliminate spam friend. |

### carrier.presence
**Kind**: instance property of [Carrier](#Carrier)
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| presence | number | Presence status. |

### carrier.on(name, callback)
Add or remove Carrier callback.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| name | string | The callback name. |
| callback | function | The function to add or change callback function. If set to null, will remove callback. |

### carrier.start(onSuccess, [onError], iterateInterval)
Start carrier node asynchronously to connect to carrier network. If the connection
to network is successful, carrier node starts working.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| iterateInterval | number | Internal loop interval, in milliseconds. |

### carrier.getSelfInfo(onSuccess, [onError])
Get self user information.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a UserInfo: the user information to the carrier node. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |

### carrier.setSelfInfo(onSuccess, [onError], userinfo)
Update self user information.
After self user information changed, carrier node will update this information
to carrier network, and thereupon network broadcasts the change to all friends.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| userinfo | [UserInfo](#UserInfo) | The user information to update for this carrier node. |

### carrier.isReady(onSuccess, [onError])
Check if carrier node instance is being ready.

All carrier interactive APIs should be called only if carrier node instance
is being ready.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a Boolean: true if the carrier node instance is ready, or false if not. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |

### carrier.getFriends(onSuccess, [onError])
Get friends list.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a {friendId: info} Object: The list of friend information to current user. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |

### carrier.getFriend(onSuccess, [onError], userId)
Get specified friend information.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a FriendInfo: The friend information. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| userId | string | The user identifier of friend |

### carrier.labelFriend(onSuccess, [onError], userId, label)
Set the label of the specified friend.

The label of a friend is a private alias name for current user. It can be
seen by current user only, and has no impact to the target friend itself.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| userId | string | The friend's user identifier |
| label | string | The new label of specified friend |

### carrier.isFriend(onSuccess, [onError], userId)
Check if the user ID is friend.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a Boolean: True if the user is a friend, or false if not. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| userId | string | The userId to check. |

### carrier.addFriend(onSuccess, [onError], address, hello)
Add friend by sending a new friend request.

This function will add a new friend with specific address, and then
send a friend request to the target node.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| address | string | the target user address of remote carrier node. |
| hello | string | PIN for target user, or any application defined content. |

### carrier.acceptFriend(onSuccess, [onError], userId)
Accept the friend request.

This function is used to add a friend in response to a friend request.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| userId | string | The user id who want be friend with us. |

### carrier.removeFriend(onSuccess, [onError], userId)
Remove a friend.

This function will remove a friend on this carrier node.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| userId | string | The target user id to remove friendship |

### carrier.sendFriendMessage(onSuccess, [onError], to, message)
Send a message to a friend.

The message length may not exceed MAX_APP_MESSAGE_LEN, and message itself
should be text-formatted. Larger messages must be split by application
and sent as separate messages. Other nodes can reassemble the fragments.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| to | string | The target id |
| message | string | The message content defined by application |

### carrier.inviteFriend(onSuccess, [onError], to, data, handler)
Send invite request to a friend.

Application can attach the application defined data with in the invite
request, and the data will send to target friend.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| to | string | The target id |
| data | string | The application defined data send to target user |
| handler | [onFriendInviteResponse](#onFriendInviteResponse) | The handler to receive invite reponse |

### carrier.replyFriendInvite(onSuccess, [onError], to, status, reason, data)
Reply the friend invite request.

This function will send a invite response to friend.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| to | string | The id who send invite request |
| status | number | The status code of the response. 0 is success, otherwise is error |
| reason | string | The error message if status is error, or null if success |
| data | string | The application defined data send to target user. If the status is error, this will be ignored |

### carrier.newSession(onSuccess, [onError], to)
Create a new session to a friend.

The session object represent a conversation handle to a friend.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success, the param is a Session Object: The new Session object |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |
| to | string | The target id(userid or userid@nodeid). |

### carrier.destroy(onSuccess, [onError])
Disconnect carrier node from carrier network, and destroy all associated resources to carreier node instance.
After calling the method, the carrier node instance becomes invalid.

**Kind**: instance method of [Carrier](#Carrier)

| Param | Type | Description |
| --- | --- | --- |
| onSuccess | function | The function to call when success. |
| [onError] | function | The function to call when error, the param is a String. Or set to null. |

## BootstrapNode : Object
The Carrier user information.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| ipv4 | string | The server ipv4. |
| ipv6 | string | The server ipv6. |
| port | string | The server port. |
| publicKey | string | The publicKey. |

## Options : Object
Options defines several settings that control the way the Carrier node connects to the carrier network.
Default values are not defined for bootstraps options, so application should be set bootstrap nodes clearly.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| udpEnabled | Boolean | Set to use udp transport or not. Setting this value to false will force carrier node to TCP only, which will potentially slow down the message to run through. |
| persistentLocation | string | Set the persistent data location. The location must be set. |
| bootstraps | Array | BootstrapNode Array. |

## UserInfo : Object
The Carrier user information.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| userId | string | The user ID. |
| name | string | The nickname. |
| description | string | user's brief description. |
| hasAvatar | Boolean | Has avatar or not. |
| gender | string | The gender. |
| phone | string | The phone number. |
| email | string | The email address. |
| region | string | The region. |

## FriendInfo : Object
The Carrier friend information.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| userInfo | [UserInfo](#UserInfo) | The user info. |
| presence | PresenceStatus | The presence status. |
| connection | ConnectionStatus | The connection status. |
| label | string | The friend's label name. |

## AddressInfo : Object
The netword address information.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| type | CandidateType | The address type. |
| address | string | The address. |
| port | string | The port. |
| [relatedAddress] | string | The related address status. |
| [relatedPort] | string | The related port. |

## TransportInfo : Object
The netword transport information.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| topology | NetworkTopology | The network topology. |
| localAddr | [AddressInfo](#AddressInfo) | The local address. |
| remoteAddr | [AddressInfo](#AddressInfo) | The remote address. |

## CarrierCallbacks : Object
The Carrier callbacks.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| onConnection | [onConnection](#onConnection) | The callback function to process the self connection status. |
| onReady | [onReady](#onReady) | The callback function to process the ready notification. |
| onSelfInfoChanged | [onSelfInfoChanged](#onSelfInfoChanged) | The callback function to process the self info changed event. |
| onFriends | [onFriends](#onFriends) | The callback function to iterate the each friend item in friend list. |
| onFriendConnection | [onFriendConnection](#onFriendConnection) | The callback function to process the friend connections status changed event. |
| onFriendInfoChanged | [onFriendInfoChanged](#onFriendInfoChanged) | The callback function to process the friend information changed event. |
| onFriendPresence | [onFriendPresence](#onFriendPresence) | The callback function to process the friend presence changed event. |
| onFriendRequest | [onFriendRequest](#onFriendRequest) | The callback function to process the friend request. |
| onFriendAdded | [onFriendAdded](#onFriendAdded) | The callback function to process the new friend added event. |
| onFriendRemoved | [onFriendRemoved](#onFriendRemoved) | The callback function to process the friend removed event. |
| onFriendMessage | [onFriendMessage](#onFriendMessage) | The callback function to process the friend message. |
| onFriendInviteRequest | [onFriendInviteRequest](#onFriendInviteRequest) | The callback function to process the friend invite request. |
| onSessionRequest | [onSessionRequest](#onSessionRequest) | The callback function that handle session request. |

## StreamCallbacks : Object
The Stream callbacks.

**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| onStateChanged | [onStateChanged](#onStateChanged) | The callback function to report state of stream when it's state changes. |
| onStreamData | [onStreamData](#onStreamData) | The callback will be called when the stream receives incoming packet. |
| onChannelOpen | [onChannelOpen](#onChannelOpen) | The callback function to be called when new multiplexing channel opened. |
| onChannelOpened | [onChannelOpened](#onChannelOpened) | The callback function to be called when new multiplexing channel opened. |
| onChannelClose | [onChannelClose](#onChannelClose) | The callback function to be called when channel close. |
| onChannelData | [onChannelData](#onChannelData) | The callback functiont to be called when channel received incoming data. |
| onChannelPending | [onChannelPending](#onChannelPending) | The callback function to be called when remote peer ask to pend data sending. |
| onChannelResume | [onChannelResume](#onChannelResume) | The callback function to be called when remote peer ask to resume data sending. |

## onFriendInviteResponse : function
The callback function to process the friend invite response.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| from | string | The target user id who send friend invite response |
| status | number | The status code of invite response. 0 is success, otherwise error |
| reason | string | The error message if status is error, otherwise null |
| data | string | The application defined data return by target user |

## onSessionRequestComplete : function
The callback function to receive session request complete event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| session | [Session](#Session) | The carrier session instance. |
| status | number | The status code of the response. 0 is success, otherwise is error. |
| reason | string | The error message if status is error, or nil if session request error happened. |
| sdp | string | The remote users SDP. Reference: https://tools.ietf.org/html/rfc4566 |

## onStateChanged : function
The callback function to report state of stream when it's state changes.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| state | StreamState | Stream state defined in StreamState |

## onStreamData : function
The callback will be called when the stream receives incoming packet.
If the stream enabled multiplexing mode, application will not
receive stream-layered data callback any more. All data will reported
as multiplexing channel data.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| data | base64 | The received packet data. |

## onChannelOpen : function
The callback function to be called when new multiplexing channel request to open.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| | | |
| stream | [Stream](#Stream) | The carrier stream instance |
| channel | number | The current channel ID. |
| cookie | string | Application defined string data send from remote peer. |

## onChannelOpened : function
The callback function to be called when new multiplexing channel opened.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| channel | number | The current channel ID. |

## onChannelClose : function
The callback function to be called when channel close.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| channel | number | The current channel ID. |
| reason | string | Channel close reason code, defined in CloseReason. |

## onChannelData : function
The callback functiont to be called when channel received incoming data.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| channel | number | The current channel ID. |
| data | base64 | The received packet data. |

## onChannelPending : function
The callback function to be called when remote peer ask to pend data sending.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| channel | number | The current channel ID. |

## onChannelResume : function
The callback function to be called when remote peer ask to resume data sending.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| stream | [Stream](#Stream) | The carrier stream instance |
| channel | number | The current channel ID. |

## onConnection : function
The callback function to process the self connection status.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| status | number | Current connection status. @see ConnectionStatus |

## onReady : function
The callback function to process the ready notification.

Application should wait this callback invoked before calling any
function to interact with friends.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |

## onSelfInfoChanged : function
The callback function to process the self info changed event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| userInfo | [UserInfo](#UserInfo) | The updated user information |

## onFriends : function
The callback function to iterate the each friend item in friend list.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| friends | Array | The friends list. |

## onFriendConnection : function
The callback function to process the friend connections status changed event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| friendId | string | The friend's user id. |
| status | number | The connection status of friend. @see ConnectionStatus |

## onFriendInfoChanged : function
The callback function to process the friend information changed event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| friendId | string | The friend's user id |
| info | [FriendInfo](#FriendInfo) | The update friend information |

## onFriendPresence : function
The callback function to process the friend presence changed event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| friendId | string | The friend's user id |
| presence | number | The presence status of the friend |

## onFriendRequest : function
The callback function to process the friend request.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| userId | string | The user id who want be friend with current user |
| info | [UserInfo](#UserInfo) | The user information to `userId` |
| hello | string | The PIN for target user, or any application defined content |

## onFriendAdded : function
The callback function to process the new friend added event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| friendInfo | [FriendInfo](#FriendInfo) | The added friend's information |

## onFriendRemoved : function
The callback function to process the friend removed event.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| friendId | string | The friend's user id |

## onFriendMessage : function
The callback function to process the friend message.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| from | string | The id from who send the message |
| message | string | The message content |

## onFriendInviteRequest : function
The callback function to process the friend invite request.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| from | string | The user id from who send the invite request |
| data | string | The application defined data sent from friend |

## onSessionRequest : function
The callback function that handle session request.

**Kind**: global typedef

| Param | Type | Description |
| --- | --- | --- |
| carrier | [Carrier](#Carrier) | Carrier node instance |
| from | string | The id who send the message |
| sdp | string | The remote users SDP. Reference: https://tools.ietf.org/html/rfc4566 |