@elastosfoundation/elastos-cordova-plugin-carrier

v1.0.6

Published

8 months ago

Elastos Carrier Plugin

Downloads

0High
0Medium
0Low

elastos-it

benjaminpiette

raozhiming

cordova carrier elastos ecosystem:cordova cordova-android cordova-ios cordova-browser

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

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

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

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

| 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

Session

Kind: global class

Session

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

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

| 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

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

Carrier

Kind: global class

Carrier

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