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.
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
Classes
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
- .ConnectionStatus :
enum - .PresenceStatus :
enum - .StreamType :
enum - .StreamState :
enum - .CandidateType :
enum - .NetworkTopology :
enum - .PortForwardingProtocol :
enum - .CloseReason :
enum - .StreamMode :
enum - .getVersion(onSuccess, [onError], onSuccess)
- .isValidId(onSuccess, [onError], id)
- .isValidAddress(onSuccess, [onError], address)
- .getIdFromAddress(onSuccess, [onError], address)
- .createObject(onSuccess, [onError], [options], callbacks)
- .ConnectionStatus :
carrierPlugin.ConnectionStatus : enum
Carrier node connection status to the carrier network.
Kind: instance enum of 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
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
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
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
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
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
Properties
| Name | Type | Default | Description |
|---|---|---|---|
| TCP | number |
1 |
TCP protocol. |
carrierPlugin.CloseReason : enum
Multiplexing channel close reason mode.
Kind: instance enum of 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
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
| 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
| 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
| 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
| 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
| 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 |
The options to set for creating carrier node. If set to null, will use default. |
| callbacks | CarrierCallbacks |
The callbacks for carrier node. |
Stream
Kind: global class
- Stream
- new Stream()
- .id
- .carrier
- .session
- .on(name, callback)
- .getTransportInfo(onSuccess, [onError])
- .write(onSuccess, [onError], data)
- .openChannel(onSuccess, [onError], cookie)
- .closeChannel(onSuccess, [onError], channel)
- .writeChannel(onSuccess, [onError], channel, data)
- .pendChannel(onSuccess, [onError], channel)
- .resumeChannel(onSuccess, [onError], channel)
- .openPortForwarding(onSuccess, [onError], service, protocol, host, port)
- .closePortForwarding(onSuccess, [onError], portForwarding)
new Stream()
The class representing Carrier stream.
stream.id
Kind: instance property of Stream
Properties
| Name | Type | Description |
|---|---|---|
| id | number |
Stream ID. |
stream.carrier
Kind: instance property of Stream
Properties
| Name | Type | Description |
|---|---|---|
| carrier | Carrier |
Parent carrier object. |
stream.session
Kind: instance property of Stream
Properties
| Name | Type | Description |
|---|---|---|
| session | Session |
Parent session object. |
stream.on(name, callback)
Add or remove Stream callback.
Kind: instance method of 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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
- new Session()
- .peer
- .carrier
- .close()
- .request(onSuccess, [onError], handler)
- .replyRequest(onSuccess, [onError], status, reason)
- .start(onSuccess, [onError], sdp)
- .addStream(onSuccess, [onError], type, options, callbacks)
- .removeStream(onSuccess, [onError], stream)
- .addService(onSuccess, [onError], service, protocol, host, port)
- .removeService(onSuccess, [onError], service)
new Session()
The class representing Carrier Session.
session.peer
Kind: instance property of Session
Properties
| Name | Type | Description |
|---|---|---|
| peer | string |
The remote peer userid. |
session.carrier
Kind: instance property of Session
Properties
| Name | Type | Description |
|---|---|---|
| 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.request(onSuccess, [onError], handler)
Send session request to the friend.
Kind: instance method of 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 |
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
| 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
| 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
| 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 |
The stream callbacks. |
session.removeStream(onSuccess, [onError], stream)
Remove a stream from session.
Kind: instance method of 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
| 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
| 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
- new Carrier()
- .nodeId
- .userId
- .address
- .nospam
- .presence
- .on(name, callback)
- .start(onSuccess, [onError], iterateInterval)
- .getSelfInfo(onSuccess, [onError])
- .setSelfInfo(onSuccess, [onError], userinfo)
- .isReady(onSuccess, [onError])
- .getFriends(onSuccess, [onError])
- .getFriend(onSuccess, [onError], userId)
- .labelFriend(onSuccess, [onError], userId, label)
- .isFriend(onSuccess, [onError], userId)
- .addFriend(onSuccess, [onError], address, hello)
- .acceptFriend(onSuccess, [onError], userId)
- .removeFriend(onSuccess, [onError], userId)
- .sendFriendMessage(onSuccess, [onError], to, message)
- .inviteFriend(onSuccess, [onError], to, data, handler)
- .replyFriendInvite(onSuccess, [onError], to, status, reason, data)
- .newSession(onSuccess, [onError], to)
- .destroy(onSuccess, [onError])
new Carrier()
The class representing Carrier.
carrier.nodeId
Kind: instance property of Carrier
Properties
| Name | Type | Description |
|---|---|---|
| nodeId | string |
Node id. |
carrier.userId
Kind: instance property of Carrier
Properties
| Name | Type | Description |
|---|---|---|
| userId | string |
User id. |
carrier.address
Kind: instance property of Carrier
Properties
| Name | Type | Description |
|---|---|---|
| address | string |
Node address. |
carrier.nospam
Kind: instance property of 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
Properties
| Name | Type | Description |
|---|---|---|
| presence | number |
Presence status. |
carrier.on(name, callback)
Add or remove Carrier callback.
Kind: instance method of 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
| 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
| 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
| 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 |
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
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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 |
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
| 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
| 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
| 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. |
string |
The email address. | |
| region | string |
The region. |
FriendInfo : Object
The Carrier friend information.
Kind: global typedef Properties
| Name | Type | Description |
|---|---|---|
| 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 |
The local address. |
| remoteAddr | AddressInfo |
The remote address. |
CarrierCallbacks : Object
The Carrier callbacks.
Kind: global typedef Properties
| Name | Type | Description |
|---|---|---|
| onConnection | onConnection |
The callback function to process the self connection status. |
| onReady | onReady |
The callback function to process the ready notification. |
| onSelfInfoChanged | onSelfInfoChanged |
The callback function to process the self info changed event. |
| onFriends | onFriends |
The callback function to iterate the each friend item in friend list. |
| onFriendConnection | onFriendConnection |
The callback function to process the friend connections status changed event. |
| onFriendInfoChanged | onFriendInfoChanged |
The callback function to process the friend information changed event. |
| onFriendPresence | onFriendPresence |
The callback function to process the friend presence changed event. |
| onFriendRequest | onFriendRequest |
The callback function to process the friend request. |
| onFriendAdded | onFriendAdded |
The callback function to process the new friend added event. |
| onFriendRemoved | onFriendRemoved |
The callback function to process the friend removed event. |
| onFriendMessage | onFriendMessage |
The callback function to process the friend message. |
| onFriendInviteRequest | onFriendInviteRequest |
The callback function to process the friend invite request. |
| onSessionRequest | onSessionRequest |
The callback function that handle session request. |
StreamCallbacks : Object
The Stream callbacks.
Kind: global typedef Properties
| Name | Type | Description |
|---|---|---|
| onStateChanged | onStateChanged |
The callback function to report state of stream when it's state changes. |
| onStreamData | onStreamData |
The callback will be called when the stream receives incoming packet. |
| onChannelOpen | onChannelOpen |
The callback function to be called when new multiplexing channel opened. |
| onChannelOpened | onChannelOpened |
The callback function to be called when new multiplexing channel opened. |
| onChannelClose | onChannelClose |
The callback function to be called when channel close. |
| onChannelData | onChannelData |
The callback functiont to be called when channel received incoming data. |
| onChannelPending | onChannelPending |
The callback function to be called when remote peer ask to pend data sending. |
| 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 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 node instance |
onSelfInfoChanged : function
The callback function to process the self info changed event.
Kind: global typedef
| Param | Type | Description |
|---|---|---|
| carrier | Carrier |
Carrier node instance |
| 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 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 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 node instance |
| friendId | string |
The friend's user id |
| info | 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 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 node instance |
| userId | string |
The user id who want be friend with current user |
| info | 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 node instance |
| 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 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 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 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 node instance |
| from | string |
The id who send the message |
| sdp | string |
The remote users SDP. Reference: https://tools.ietf.org/html/rfc4566 |