@elastosfoundation/elastos-cordova-plugin-carrier v1.0.6

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

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)

carrierPlugin.ConnectionStatus : enum

Carrier node connection status to the carrier network.

Kind: instance enum of carrierPlugin Properties

carrierPlugin.PresenceStatus : enum

Carrier node presence status.

Kind: instance enum of carrierPlugin Properties

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

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

carrierPlugin.CandidateType : enum

Carrier Stream's candidate type.

Kind: instance enum of carrierPlugin Properties

carrierPlugin.NetworkTopology : enum

Carrier network topology for session peers related to each other.

Kind: instance enum of carrierPlugin Properties

carrierPlugin.PortForwardingProtocol : enum

Port forwarding supported protocols.

Kind: instance enum of carrierPlugin Properties

carrierPlugin.CloseReason : enum

Multiplexing channel close reason mode.

Kind: instance enum of carrierPlugin Properties

carrierPlugin.StreamMode : enum

Carrier stream mode.

Kind: instance enum of carrierPlugin Properties

carrierPlugin.getVersion(onSuccess, onError, onSuccess)

Get current version of Carrier node.

Kind: instance method of carrierPlugin

carrierPlugin.isValidId(onSuccess, onError, id)

Check if the ID is Carrier node id.

Kind: instance method of carrierPlugin

carrierPlugin.isValidAddress(onSuccess, onError, address)

Check if the carrier node address is valid.

Kind: instance method of carrierPlugin

carrierPlugin.getIdFromAddress(onSuccess, onError, address)

Get carrier ID from carrier node address.

Kind: instance method of carrierPlugin

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

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

stream.carrier

Kind: instance property of Stream Properties

stream.session

Kind: instance property of Stream Properties

stream.on(name, callback)

Add or remove Stream callback.

Kind: instance method of Stream

stream.getTransportInfo(onSuccess, onError)

Get tranport info of carrier stream.

Kind: instance method of Stream

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

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

session.carrier

Kind: instance property of Session Properties

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

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.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.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.removeStream(onSuccess, onError, stream)

Remove a stream from session.

Kind: instance method of Session

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.removeService(onSuccess, onError, service)

Remove a portforwarding server to session.

This function has not effect on existing portforwarings.

Kind: instance method of Session

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

carrier.userId

Kind: instance property of Carrier Properties

carrier.address

Kind: instance property of Carrier Properties

carrier.nospam

Kind: instance property of Carrier Properties

carrier.presence

Kind: instance property of Carrier Properties

carrier.on(name, callback)

Add or remove Carrier callback.

Kind: instance method of Carrier

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.getSelfInfo(onSuccess, onError)

Get self user information.

Kind: instance method of Carrier

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.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.getFriends(onSuccess, onError)

Get friends list.

Kind: instance method of Carrier

carrier.getFriend(onSuccess, onError, userId)

Get specified friend information.

Kind: instance method of Carrier

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.isFriend(onSuccess, onError, userId)

Check if the user ID is friend.

Kind: instance method of Carrier

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.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.removeFriend(onSuccess, onError, userId)

Remove a friend.

This function will remove a friend on this carrier node.

Kind: instance method of Carrier

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

BootstrapNode : Object

The Carrier user information.

Kind: global typedef Properties

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

UserInfo : Object

The Carrier user information.

Kind: global typedef Properties

FriendInfo : Object

The Carrier friend information.

Kind: global typedef Properties

AddressInfo : Object

The netword address information.

Kind: global typedef Properties

TransportInfo : Object

The netword transport information.

Kind: global typedef Properties

CarrierCallbacks : Object

The Carrier callbacks.

Kind: global typedef Properties

StreamCallbacks : Object

The Stream callbacks.

Kind: global typedef Properties

onFriendInviteResponse : function

The callback function to process the friend invite response.

Kind: global typedef

onSessionRequestComplete : function

The callback function to receive session request complete event.

Kind: global typedef

onStateChanged : function

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

Kind: global typedef

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

onChannelOpen : function

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

Kind: global typedef

onChannelOpened : function

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

Kind: global typedef

onChannelClose : function

The callback function to be called when channel close.

Kind: global typedef

onChannelData : function

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

Kind: global typedef

onChannelPending : function

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

Kind: global typedef

onChannelResume : function

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

Kind: global typedef

onConnection : function

The callback function to process the self connection status.

Kind: global typedef

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

onSelfInfoChanged : function

The callback function to process the self info changed event.

Kind: global typedef

onFriends : function

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

Kind: global typedef

onFriendConnection : function

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

Kind: global typedef

onFriendInfoChanged : function

The callback function to process the friend information changed event.

Kind: global typedef

onFriendPresence : function

The callback function to process the friend presence changed event.

Kind: global typedef

onFriendRequest : function

The callback function to process the friend request.

Kind: global typedef

onFriendAdded : function

The callback function to process the new friend added event.

Kind: global typedef

onFriendRemoved : function

The callback function to process the friend removed event.

Kind: global typedef

onFriendMessage : function

The callback function to process the friend message.

Kind: global typedef

onFriendInviteRequest : function

The callback function to process the friend invite request.

Kind: global typedef

onSessionRequest : function

The callback function that handle session request.

Kind: global typedef