Channels
Channels
The Channels object, accessed from the rest library client constructor, is used to create and destroy Channel objects. It exposes the following public methods:
Channels Methods
get
Channel get(String channelName, ChannelOptions channelOptions)
Creates a new Channel object if none for the channel exists, or returns the existing channel object.
release
release(String channelName)
Releases a Channel object, deleting it and enabling it to be garbage collected.
Channel
The Channel object, created via the Channels object, is used to interact with a specific channel.
Channel Properties
The Channel object exposes the following public properties:
name
The name String unique to this channel.
presence
Provides access to the REST Presence object for this channel which can be used to get members present on the channel, or retrieve presence event history.
push
Provides access to the PushChannel object for this channel which can be used to access members present on the channel, or participate in presence.
Channel Methods
publish
There are two overloaded versions of this method:
publish(String name, Object data, callback(ErrorInfo err))
Publish a single message on this channel based on a given event name and payload. A callback may optionally be passed in to this call to be notified of success or failure of the operation.
It is also possible to publish a message to multiple channels at once using our batch publish feature.
publish(Object[] messages, callback(ErrorInfo err))
Publish several messages on this channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation.
The entire messages array is published atomically. This means that:
- Either they will all be successfully published or none of them will
- The max message size limit applies to the total size of all messages in the array
- The publish will only count as a single message for the purpose of per-channel rate limit
- If you are using client-specified message IDs for publish idempotency, they must conform to certain restrictions
Parameters
- data
- data payload for the message. The supported payload types are Strings, objects or arrays capable of JSON representation, buffers containing arbitrary binary data, and null. (Note that if sending a binary, that binary should be the entire payload; an object with a binary field within it may not be correctly encoded)Type:
Object - messages
- An array of message objects to publishType:
Message [] - callback
- is a function of the form
function(err)which is called upon completion
Callback result
On successful publish of the message, err is null. On failure to publish the message, err contains an ErrorInfo object describing the failure reason.
history
history(Object options, callback(ErrorInfo err, PaginatedResult<Message> resultPage))
Gets a paginated set of historical messages for this channel. If the channel is configured to persist messages to disk, then message history will typically be available for 24 – 72 hours. If not, messages are only retained in memory by the Ably service for two minutes.
Parameters
- options
- an optional object containing the query parameters, as specified in the message history API documentation.
- callback
- is a function of the form:
function(err, resultPage)
Callback result
On success, resultPage contains a PaginatedResult encapsulating an array of Message objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.
On failure to retrieve message history, err contains an ErrorInfo object with the failure reason.
Related types
Message
A Message represents an individual message that is sent to or received from Ably.
Properties
- name
- Event name, if providedType:
String - data
- The presence update payload, if providedType:
String,StringBuffer,JSON Object - extras
- Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the
push,refandprivilegedobjects.Type:JSON Object - id
- Unique ID assigned by Ably to this message. Can optionally be assigned by the client as part of idempotent publishingType:
String - clientId
- The client ID of the publisher of this messageType:
String - connectionId
- The connection ID of the publisher of this messageType:
String - timestamp
- Timestamp when the message was received by the Ably service, as milliseconds since the epochType:
Integer - encoding
- This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the
datapayloadType:String
Message constructors
Message.fromEncoded
Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) → Message
A static factory method to create a Message from a deserialized Message-like object encoded using Ably’s wire protocol.
Parameters
- encodedMsg
- a
Message-like deserialized object.Type:Object - channelOptions
- an optional
ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.Type:Object
Returns
A Message object
Message.fromEncodedArray
Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) → Message[]
A static factory method to create an array of Messages from an array of deserialized Message-like object encoded using Ably’s wire protocol.
Parameters
- encodedMsgs
- an array of
Message-like deserialized objects.Type:Array - channelOptions
- an optional
ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.Type:Object
Returns
An Array of Message objects
ChannelOptions Object
Channel options are used for setting channel parameters and configuring encryption.
ChannelOptions, a plain JavaScript object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following attributes can be defined on the object:
Properties
- params
- Optional parameters which specify behaviour of the channel.Type:
JSON Object - cipher
- Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an exampleType:
CipherParamsor an options object containing at a minimum akey
PaginatedResult
A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.
Properties
Methods
first
first(callback(ErrorInfo err, PaginatedResult resultPage))
Returns a new PaginatedResult for the first page of results.
hasNext
Boolean hasNext()
Returns true if there are more pages available by calling next and returns false if this page is the last page available.
isLast
Boolean isLast()
Returns true if this page is the last page and returns false if there are more pages available by calling next available.
next
next(callback(ErrorInfo err, PaginatedResult resultPage))
Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned.
Example
channel.history(function(err, paginatedResult) {
console.log('Page 0 item 0:' + paginatedResult.items[0].data);
paginatedResult.next(function(err, nextPage) {
console.log('Page 1 item 1: ' + nextPage.items[1].data);
console.log('Last page?: ' + nextPage.isLast());
});
});
CopyCopied!