Warning: You are viewing an old version (0.8) of this documentation. We recommend you view the latest version 1.2.
API Reference

Channels

Channel PropertiesARTRealtimeChannel PropertiesAbly::Realtime::Channel Attributesio.ably.lib.realtime.Channel MembersIO.Ably.Realtime.RealtimeChannel Properties

The Channel object exposes the following public propertiesattributesmembers:

stateState

The current io.ably.lib.realtime.ChannelState stateIO.Ably.Realtime.ChannelState stateAbly::Realtime::Channel::STATE stateARTRealtimeChannelStateChannelState of this Channel. See the supported channel states for more information.

errorReasonreasonerror_reasonErrorReason

When a channel failure occurs this attributememberpropertyproperty is populated.
The type is ErrorInfoAblyException.

nameName

The name String unique to this channel.

presencePresence

Provides access to the Presence object for this channel which can be used to access members present on the channel, or participate in presence.

Methods

publishPublish

There are two overloaded versions of this method:

publish(String name, Object data, callback(ErrorInfo err))Deferrable publish(String name, Object data) → yieldsvoid publish(String name, Object data, CompletionListener listener)void Publish(string name, object data, Action<bool, ErrorInfo> callback = null, string clientId = null)publish(name: String?, data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)

Publish a single message on this channel based on a given event name and payload. A callbacklistener may optionally be passed in to this call to be notified of success or failure of the operation.

publish(Object[] messages, callback(ErrorInfo err))Deferrable publish(Message[] messages) → yieldsvoid publish(Message[] messages, CompletionListener listener)void Publish(IEnumerable<Message> messages, Action<bool, ErrorInfo> callback = null)publish(messages: [ ARTMessage ], callback: ((ARTErrorInfo?) → Void)?)

Publish several messages on this channel. A callbacklistenerblock may optionally be passed in to this call to be notified of success or failure of the operation.

Parameters

name
event name for the published message
Type: String
data
data payload for the message. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object
data
data payload for the message. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object
data
data payload for the message. The supported payload types are Strings, binary data as byte arrays, any plain c# class that can be serialized to Json, and null.
Type: Object
data
data payload for the message. The supported payload types are Strings, Hash or Array objects that can be serialised to JSON using to_json, binary data as ASCII-8BIT byte arrays, and null.
Type: Object
data
data payload for the message. The supported payload types are NSString, NSDictionary or NSArray objects that can be serialized to JSON, binary data as NSData, and nil.
Type: Object
messages
An array of message objects to publish
Type: Message []
callback
is a function of the form function(err) which is called upon completion
listener
Listener to be notified on completion
Type: CompletionListener
callback
is an action of the form Action<bool, ErrorInfo> which is called upon completion
&block
yields upon successfully publishing the message
callback
called upon publishing the message, or with an error

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.

Callback result

On successful publish of the message, error is null. On failure to publish the message, error contains an ErrorInfo object describing the failure reason.

Listener result

On successful publish of the message, the onSuccess method of the CompletionListener is called. On failure to publish the message, the onError method is called with an ErrorInfo argument describing the failure reason.

Returns

A Deferrable object is returned from the method.

On successful publish of the message, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to publish the message, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

subscribeSubscribe

There are overloaded versions of this method:

subscribe(listener(Message))void subscribe(MessageListener listener)void Subscribe(Action<Message> handler)subscribe → yields Messagesubscribe(callback: (ARTMessage) → Void) → ARTEventListener?

Subscribe to messages on this channel. The caller supplies a listener functiona lambda expressionan implementation of the MessageListener interfacea block, which is called each time one or more messages arrives on the channel.

subscribe(String name, listener(Message))void subscribe(String name, MessageListener listener)void Subscribe(string name, Action<Message> handler)subscribe(String name) → yields Messagesubscribe(name: String, callback: (ARTMessage) → Void) → ARTEventListener?

Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the MessageListener interfacea block, which is called each time one or more matching messages arrives on the channel.

subscribe(String[] names, listener(Message))void subscribe(String[] names, MessageListener listener)subscribe(String *names) → yields Message

Subscribe a single listener to messages on this channel for multiple event name values.

Parameters

name
The event name to subscribe to
Type: String
names
An argument array of event names to subscribe to
Type: String[] *argument
listener
is a function of the form function(message) to be called for each message
MessageListener listener
Message listener to be notified for matching messages
&block
yields each matching message when received on the channel
callback
called with each matching message when received on the channel
handler
called with each matching message when received on the channel
unsubscribeUnsubscribe

There are three overloaded versions of this method:

unsubscribe(String name, listenerCallback)void unsubscribe(String name, MessageListener listener)bool Unsubscribe(string eventName, Action<Message> handler)unsubscribe(String name, &listener_proc)unsubscribe(name: String, listener: ARTEventListener)

Unsubscribe to messages on this channel for the specified event name. This removes an earlier event-specific subscription.

unsubscribe(listenerCallback)void unsubscribe(MessageListener listener)bool Unsubscribe(Action<Message> handler)unsubscribe(&listener_proc)unsubscribe(listener: ARTEventListener)

Unsubscribe to messages on this channel. This removes an earlier subscription.

unsubscribe()void unsubscribe()void Unsubscribe()unsubscribe()

Unsubscribes all listeners to messages on this channel. This removes all earlier subscriptions.

Parameters

String name
The event name to unsubscribe from
listenerCallback
is the callback listener function that was previously subscribed
listener
previously registered listener
Type: MessageListener
&listener_block
previously registered listener block
listener
previous return value from a subscribe call
handler
is the lambda expression that was previously subscribed
historyHistory

history(Object options, callback(ErrorInfo err, PaginatedResult<Message> resultPage))Deferrable history(Hash options) → yields PaginatedResult<Message>PaginatedResult<Message> history(Param [] options)Task<PaginatedResult> HistoryAsync(HistoryRequestParams dataQuery, bool untilAttach = false)history(query: ARTRealtimeHistoryQuery?, callback: (ARTPaginatedResult<ARTMessage>?, ARTErrorInfo?) → Void) throws

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

optionsquerydataQuery
an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified in the message history API documentation.
Type: ObjectARTRealtimeHistoryQueryHistoryRequestParamsHashParam []
callback
is a function of the form: function(err, resultPage)
&block
yields a PaginatedResult<Message> object
callback
called with a ARTPaginatedResult<ARTMessage> object or an error

Further details of the supported options params, see message history API documentation.

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.

Returns

On success, the returned PaginatedResult encapsulates an array of Message objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

Failure to retrieve the message history will raise an AblyException

Returns

The return value is Task<PaginatedResult<Message>> which needs to be awaited.

On success, the returned PaginatedResult encapsulates an array of Message objects corresponding to the current page of results. PaginatedResult supports pagination using NextAsync and FirstAsync methods.

Failure to retrieve the message history will raise an AblyException

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield a PaginatedResult that encapsulates an array of Message objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

Failure to retrieve the message history will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

attachAttach

attach(callback(ErrorInfo err))void attach()void Attach(Action<TimeSpan, ErrorInfo?> callback = null)Deferrable attach → yieldsattach(callback: ((ARTErrorInfo?) → Void)?)

Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel will be received by any channel listeners registered using subscribe()Subscribe()subscribe. Any resulting channel state change will be emitted to any listeners registered using the onOn or onceOnce methods.

As a convenience, attach()Attach()attach will be called implicitly if either publish()Publish()publish or subscribe()Subscribe()subscribe for the Channel is called, or enter()Enter()enter or subscribe()Subscribe()subscribe is called on the Presence for this Channel.

Parameters

callback
is a function of the form function(err) and is called once the channel attach succeeds or fails
&block
yields once the channel becomes attached
callback
is a lambda expression of the form Action<TimeSpan, ErrorInfo> and is called once the channel attach succeeds or fails
callback
called once the channel becomes attached or if an error occurs

Returns

A Deferrable object is returned from the attach method.

On successful attachment, the success callbacks for the Deferrable are called and any block provided to the method is yielded. Failure to attach will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

detachDetach

detach(callback(ErrorInfo err))void detach()void Detach(Action<TimeSpan, ErrorInfo> callback = null)Deferrable detach → yieldsdetach(callback: ((ARTErrorInfo?) → Void)?)

Detach from this channel. Any resulting channel state change will be emitted to any listeners registered using the onOn or onceOnce methods.

Please note: Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes.

Parameters

callback
is a function of the form function(err) and is called once the channel detach succeeds or fails
callback
is a lambda expression in the form Action<TimeSpan, ErrorInfo> and is called once the channel detach succeeds or fails
&block
yields once the channel becomes detached
callback
called once the channel becomes detached or if an error occurs

Returns

A Deferrable object is returned from the detach method.

On successful detachment, the registered success blocks for the Deferrable and any block provided to the method are executed. Failure to detach will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

onOn

There are two overloaded versions of this method:

on(String state, listener())on(ChannelState *state) → yields ChannelStateChangevoid on(ChannelState state, ChannelStateListener listener)void On(ChannelState state, Action action)on(event: ARTChannelEvent, call: (ARTErrorInfo?) → Void) → ARTEventListener

Register the given listener blockfunction for the specified ChannelState statestate(s) changes on the Channel.
The listener is passed the current state as the event property of thisThe listener is passed a ChannelState object that contains the current state, previous state, and an optional reason for the state changeThe listener is passed an optional reason for the state change.

on(listener())on → yields ChannelStateChangevoid On(Action listener)void on(ChannelStateListener listener)on(call: (ARTErrorInfo?) → Void) → ARTEventListener

Register the given listener blockfunctionlambda expression for all ChannelState changes on the Channel, plus when an error happens when attaching, detaching, or encoding or decoding a message.
The listener is passed the current state as the event property of this.The listener is passed a ChannelState object that contains the current state, previous state, and an optional reason for the state changeThe callback is passed an optional reason for the state change or error.

Parameters

state
the channel state to subscribe to, see ChannelState for supported channel states
Type: String
state
the channel state to subscribe to
Type: ChannelState
event
the channel state to subscribe to
Type: ChannelState
state
the channel state as a Symbol such as :attached or a ChannelState object to subscribe to
Type: ChannelState
event
either a channel state to subscribe to, or ARTChannelEventError to subscribe to errors not related to state changes
Type: ARTChannelEvent
listener
is a function of the form function() to be notified for matching state changes. The current state is available as this.event
listener
listener to be notified for matching state changes
Type: ChannelStateListener
action
lambda expression to be notified for matching state changes
Type: ChannelStateChange
&block
listener block that is yielded to for matching state changes
call
called possibly with an ErrorInfo

Example

Browser ChannelState change example

onceOnce

There are two overloaded versions of this method:

once(String state, listener())once(ChannelState *state) → yields ChannelStateChangevoid once(ChannelState state, ChannelStateListener listener)void Once(ChannelState state, Action action)once(event: ARTChannelEvent, call: (ARTErrorInfo?) → Void) → ARTEventListener

Register the given listener blockfunctionlambda expression for a single occurrence of the specified ChannelState statestate(s)state change on the Channel. Once the listener has been called, it is removed as a registered listener and will not be called again.
The listener is passed the current state as the event property of thisThe listener is passed a ChannelState object that contains the current state, previous state, and an optional reason for the state changeThe listener is passed an optional reason for the state change.

once(listener())once → yields ChannelStateChangevoid once(ChannelStateListener listener)void Once(Action listener)once(call: (ARTErrorInfo?) → Void) → ARTEventListener

Register the given listener blockfunctionlambda expression for a single occurrence of any ChannelState change on the Channel. Once the listener has been called, it is removed as a registered listener and will not be called again.
The listener is passed the current state as the event property of thisThe listener is passed a ChannelState object that contains the current state, previous state, and an optional reason for the state changeThe listener is passed an optional reason for the state change.

Parameters

state
the channel state to subscribe to, see ChannelState for supported channel states
Type: String
state
the channel state to subscribe to
Type: ChannelState
event
the channel state to subscribe to
Type: ChannelState
state
the channel state as a Symbol such as :attached or a ChannelState object to subscribe to
Type: ChannelState
event
either a channel state to subscribe to, or ARTChannelEventError to subscribe to errors not related to state changes
Type: ARTChannelEvent
listener
is a function of the form function() to be notified for a single occurrence of a matching state change. The current state is available as this.event
listener
listener to be notified for a single occurrence of a matching state change
Type: ChannelStateListener
&block
listener block that is yielded to for a single occurrence of a matching state change
listener
listener lambda expression that is notified only once for a matching state change
call
called possibly with an ErrorInfo
offOff

There are two overloaded versions of this method:

off(String state, listener)off(ChannelState *state, &block)void off(ChannelState state, ChannelStateListener listener)void Off(ChannelState state, Action listener)off(event: ARTChannelEvent, listener: ARTEventListener)

Remove the given listener block for the ChannelState statestate(s).

off(listener)off(&block)void off(ChannelStateListener listener)void Off(Action listener)off(listener: ARTEventListener)

Remove the given listener block for all ChannelState states.

Parameters

state
the channel state to unsubscribe from
Type: String
state
the channel state to unsubscribe from
Type: ChannelState
event
the channel state to unsubscribe from
Type: ChannelState
state
the channel state as a Symbol such as :detached or a ChannelState object to unsubscribe from
Type: ChannelState
event
either a channel to unsubscribe from, or ARTChannelEventError to unsubscribe from errors not related to state changes
Type: ARTChannelEvent
listener
is the listener function to be removed
listener
is the listener to be removed
Type: @ChannelStateListener
listener
is the listener function to be removed
&block
is the listener block to be removed
listener
previous return value from a on or once call

ChannelStateARTRealtimeChannelStateChannel::STATE Enumio.ably.lib.realtime.ChannelState EnumIO.Ably.Realtime.ChannelState Enum

ChannelState is a String with a value matching any of the Realtime Channel states.

var allChannelStates = [
  'initialized',
  'attaching',
  'attached',
  'detaching',
  'detached',
  'failed'
]

io.ably.lib.realtime.ChannelState is an enum representing all the Realtime Channel states.

public enum ChannelState {
  initialized,  // 0
  attaching,    // 1
  attached,     // 2
  detaching,    // 3
  detached,     // 4
  failed        // 5
}

IO.Ably.Realtime.ChannelState is an enum representing all the Realtime Channel states.

public enum ChannelState
{
    Initialized = 0,
    Attaching = 1,
    Attached = 2,
    Detaching= 3,
    Detached = 4,
    Failed = 5
};

Ably::Realtime::Channel::STATE is an enum-like value representing all the Realtime Channel states. STATE can be represented interchangeably as either symbols or constants.

Symbol states

:initialized # => 0
:attaching # =>   1
:attached # =>    2
:detaching # =>   3
:detached # =>    4
:failed # =>      5

Constant states

Connection::STATE.Initialized # => 0
Connection::STATE.Attaching # =>   1
Connection::STATE.Attached # =>    2
Connection::STATE.Detaching # =>   3
Connection::STATE.Detached # =>    4
Connection::STATE.Failed # =>      5

Example usage

# Example with symbols
channel.on(:attached) { ... }

# Example with constants
channel.on(Ably::Realtime::Channel::STATE.Attached) { ... }

# Interchangeable
Ably::Realtime::Channel::STATE.Attached == :attached # => true

ARTRealtimeChannelState is an enum representing all the Realtime Channel states.

typedef NS_ENUM(NSUInteger, ARTRealtimeChannelState) {
    ARTRealtimeChannelInitialized,
    ARTRealtimeChannelAttaching,
    ARTRealtimeChannelAttached,
    ARTRealtimeChannelDetaching,
    ARTRealtimeChannelDetached,
    ARTRealtimeChannelFailed
};
public enum ARTRealtimeChannelState : UInt {
    case Initialized
    case Attaching
    case Attached
    case Detaching
    case Detached
    case Failed
}

MessageARTMessageAbly::Models::Messageio.ably.lib.types.MessageIO.Ably.Message

A Message represents an individual message that is sent to or received from Ably.

PropertiesMembersAttributesAttributes

nameName
Event name, if provided
Type: String
data
The message payload, if provided
Type: String, StringBuffer, JSON Object
data
The message payload, if provided
Type: String, ByteArray, JSONObject, JSONArray
Data
The message payload, if provided
Type: String, byte[], plain C# object that can be serialized to Json
data
The message payload, if provided
Type: String, Binary (ASCII-8BIT String), Hash, Array
data
The message payload, if provided
Type: String, Bytearray, Dict, List
data
The message payload, if provided
Type: String, Binary String, Associative Array, Array
data
The message payload, if provided
Type: NSString *, NSData *, NSDictionary *, NSArray *
data
The message payload, if provided
Type: String, NSData, Dictionary, Array
idId
Unique ID assigned by Ably to this message
Type: String
clientIdclient_idClientId
The client ID of the publisher of this message
Type: String
connectionIdconnection_idConnectionId
The connection ID of the publisher of this message
Type: String
timestampTimestamp
Timestamp when the presence update was received by the Ably the realtime service, as milliseconds since the epocha Time object
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate
encodingEncoding
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 data payload
Type: String

ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.lib.types.ChannelOptionsIO.Ably.Rest.ChannelOptions

Currently the supported channel options are only used for 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:

ChannelOptions, a Hash object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:

ChannelOptions, an Associative Array, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following named keys and values can be added to the Associated Array:

ARTio.ably.lib.types.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

IO.Ably.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

PropertiesMembersAttributes

cipher:cipherCipherParams
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key

Static methods

withCipherKey

static ChannelOptions.withCipherKey(Byte[] or String key)

A helper method to generate a ChannelOptions for the simple case where you only specify a key.

Parameters

key
A binary Byte[] array or a base64-encoded String.

Returns

On success, the method returns a complete ChannelOptions object. Failure will raise an AblyException.

ChannelStateChange

A Ably::Models::ChannelStateChange is a type encapsulating state change information emitted by the Channel object. See Channel#on to register a listener for one or more events.

Attributes

previous
the previous state
Type: Channel::STATE
current
the new state
Type: Channel::STATE
reason
an ErrorInfo containing any information relating to the transition
Type: ErrorInfo

ARTChannelEvent

ARTChannelEvent is the enum emitted as the event in ARTRealtimeChannel.on. The variants correspond to Realtime Channel state changes, plus an arbitrary Error.

typedef NS_ENUM(NSUInteger, ARTChannelEvent) {
    ARTChannelEventInitialized,
    ARTChannelEventAttaching,
    ARTChannelEventAttached,
    ARTChannelEventDetaching,
    ARTChannelEventDetached,
    ARTChannelEventFailed,
    ARTChannelEventError
};
enum ARTChannelEvent : UInt {
    case Initialized
    case Attaching
    case Attached
    case Detaching
    case Detached
    case Failed
    case Error
}

io.ably.lib.realtime.ChannelStateListener

A io.ably.lib.realtime.ChannelStateListener is an interface allowing a client to be notified of state changes for a Channel

public interface ChannelStateListener {
  // Called when the channel state changes
  public void onChannelStateChanged(ChannelState state, ErrorInfo reason);
}

io.ably.lib.realtime.CompletionListener

A io.ably.lib.realtime.CompletionListener is an interface allowing a client to be notified of the outcome of an asynchronous operation.

public interface CompletionListener {
  // Called when the associated operation completes successfully,
  public void onSuccess();

  // Called when the associated operation completes with an error.
  public void onError(ErrorInfo reason);
}

HistoryRequestParams

HistoryRequestParams is a type that encapsulates the parameters for a history queries. For example usage see Channel#historyChannel#History.

Members

Start
null The start of the queried interval
Type: DateTimeOffset
End
null The end of the queried interval
Type: DateTimeOffset
Limit
null By default it is null. Limits the number of items returned by history or stats
Type: Integer
Direction
Backwards Enum which is either Forwards or Backwards
Type: Direction enum
ExtraParameters
Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging.
Type: Dictionary<string, string>

io.ably.lib.realtime.Channel.MessageListener

A io.ably.lib.realtime.Channel.MessageListener is an interface allowing a client to be notified when messages are received on a channel using a channel subscription.

public interface MessageListener {
  // Called when one or more messages are received
  public void onMessage(Message message);
}

PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.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.

PropertiesMembersAttributesAttributes

itemsItems
contains a page of results (for example an Array of Message or PresenceMessage objects for a channel history request)
Type: Array <Message, Presence, Stats>Type: List <Message, Presence, Stats>
isLast
true if this page is the last page
Type: Boolean
last?
true if this page is the last page
Type: Boolean
isLast()
true if this page is the last page
Type: Boolean
is_last()
True if this page is the last page
Type: Boolean
hasNext
true if there are further pages
Type: Boolean
HasNext
true if there are further pages
Type: Boolean
has_next?
true if there are further pages
Type: Boolean
hasNext()
true if there are further pages
Type: Boolean
has_next()
True if there are further pages
Type: Boolean

Methods

firstFirst

first(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult firstPaginatedResult first()PaginatedResult first()Task<PaginatedResult> FirstAsync()PaginatedResult first()first(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)

Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.The method is asynchronous and returns a Task which needs to be awaited to get the PaginatedResult.

itemsItems

Object[] items()List items()Object[] itemsObject[] items()List Itemsitems: [AnyObject]

Returns the current page of results as an Arraya Lista List. The type of the objects in the arraylist is determined by the operation that provided the PaginatedResult. For example, a Message.history()Message.History() request will return an arraya list of Message objects.

nextNext

next(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult nextPaginatedResult next()PaginatedResult next()Task<PaginatedResult> NextAsync()PaginatedResult next()next(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then nulla blank PaginatedResult will be returnedNullNonenil is returned. The method is asynchronous and return a Task which needs to be awaited to get the PaginatedResultWhen using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

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;
  });
});
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;
  });
});
PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};
PaginatedResult<Message> firstPage = await channel.HistoryAsync(null);
Message firstMessage = firstPage.Items[0];
Console.WriteLine("Page 0 item 0: " + firstMessage.data);
if (firstPage.HasNext)
{
    var nextPage = await firstPage.NextAsync();
    Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data);
    Console.WriteLine("More pages?: " + nextPage.HasNext);
}
# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end
result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())
$firstPage = $channel.history();
echo("Page 0 item 0: " . $firstPage->items[0]->data);
if ($firstPage->hasNext()) {
  $nextPage = $firstPage->next();
  echo("Page 1 item 1: " . $nextPage->items[1]->data);
  echo("Last page?: " . $nextPage->isLast());
}
[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast);
    }];
}];
channel.history { paginatedResult, error in
    let paginatedResult = paginatedResult!
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        let nextPage = nextPage!
        print("Page 0 item 0: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast)")
    }
}

io.ably.lib.types.Param

Param is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see Channel#history for an example.

Please note that key and value attributes are always strings. If an Integer or other value type is expected, then you must coerce that type into a String.

Members

key
The key value
Type: String
value
The value associated with the key
Type: String

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.