Presence

Presence PropertiesARTPresence PropertiesAbly::Realtime::Presence Attributesio.ably.lib.realtime.Presence MembersIO.Ably.Realtime.Presence Properties

The Presence object exposes the following public propertiesattributesmembers:

syncCompletesync_complete?SyncComplete

A boolean field indicating whether the presence member set is synchronized with server after a channel attach.
When a channel is attached, the Ably service immediately synchronizes the presence member set with the client. Typically this process completes in milliseconds, however when the presence member set is very large, bandwidth constraints may slow this synchronization process down.

Methods

enterEnterAsync

In order to enter and be present on a channel, the client must be identified by having a client ID, have permission to be present, and be attached to the channel. For simplicity, the library will implicitly attach to a channel when entering. Entering when already entered is treated as an update.

There are two overloaded versions of this method.
With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to enter.

enter(callback(ErrorInfo err))Deferrable enter() → yieldsvoid enter(CompletionListener listener)enter(data: nil, callback: ((ARTErrorInfo?) → Void)?)Task EnterAsync()

Enter a presence channel without any data. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

enter(Object data, callback(ErrorInfo err))Deferrable enter(Object data) → yieldsvoid enter(Object data, CompletionListener listener)enter(data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)Task EnterAsync(object clientData)

Enter a presence channel and provide data that is associated with the current present member. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

Parameters

data

data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object

data

data payload for the current present member. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object

data

data payload for the current present member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null.
Type: Object

data

data payload for the current present member. The supported payload types are Strings, Hash or Array objects that can be serialized 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

callback

is a function of the form function(err) which is called upon completion

listener

Listener to be notified on completion
Type: CompletionListener

&block

yields upon successfully entering the channel

callback

called upon successfully entering the channel, or with an error

leaveLeave

In order to leave the presence set of a channel, the client must have already entered and been present.

There are two overloaded versions of this method.
With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to leave.

leave(callback(ErrorInfo err))Deferrable leave() → yieldsvoid leave(CompletionListener listener)leave(data: nil, callback: ((ARTErrorInfo?) → Void)?)Task LeaveAsync()

Leave a presence channel without emitting any data.

leave(Object data, callback(ErrorInfo err))Deferrable leave(Object data) → yieldsvoid leave(Object data, CompletionListener listener)leave(data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)Task LeaveAsync(object clientData)

Leave a presence channel and emit data that is associated with the current leaving member.

Parameters

data

data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object

data

data payload for the current present member. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object

data

data payload for the current present member. The supported payload types are strings, plain objects convertible to json, binary data as byte arrays, and null.
Type: Object

data

data payload for the current present member. The supported payload types are Strings, Hash or Array objects that can be serialized 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

callback

is a function of the form function(err) which is called upon completion

listener

Listener to be notified on completion
Type: CompletionListener

&block

yields upon successfully leaving the channel

callback

called upon leaving the channel, or with an error

updateUpdate

Clients can update their member data on the channel which will trigger a broadcast of this update to all presence subscribers. The pre-requisites for updateUpdate are the same as for enterEnter. If an attempt to updateUpdate is made before the client has entered the channel, the update is treated as an enterEnter.

A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data.

update(Object data, callback(ErrorInfo err))Deferrable update(Object data) → yieldsvoid update(Object data, CompletionListener listener)update(data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)Task UpdateAsync(object clientData)

Update the current member’s data and broadcast an update event to all subscribers. data may be null. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling update will implicitly attach the channel.

Parameters

data

data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object

data

data payload for the current present member. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object

data

data payload for the current present member. The supported payload types are strings, plain objects convertible to json, binary data as byte arrays, and null.
Type: Object

data

data payload for the current present member. The supported payload types are Strings, Hash or Array objects that can be serialized 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

callback

is a function of the form function(err) which is called upon completion

listener

Listener to be notified on completion
Type: CompletionListener

&block

yields upon successfully updating the member data

callback

called upon updating the channel, or with an error

getGet

Get the current presence member set for this channel. Typically, this method returns the member set immediately as the member set is retained in memory by the client. However, by default this method will wait until the presence member set is synchronized, so if the synchronization is not yet complete following a channel being attached, this method will wait until the presence member set is synchronized.

When a channel is attached, the Ably service immediately synchronizes the presence member set with the client. Typically this process completes in milliseconds, however when the presence member set is very large, bandwidth constraints may slow this synchronization process down.

When a channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling get will implicitly attach the channel.

get(Object options, callback(ErrorInfo err, PresenceMessage[] members))Deferrable get(Hash options) → yields PresenceMessage[]PresenceMessage[] get(Param[] options)get(query: ARTRealtimePresenceQuery, callback: (ARTPresenceMessage, ARTErrorInfo?) → Void)Task<IEnumerable> GetAsync(GetOptions { bool waitForSync = true, string clientId = "", string connectionId = "" })

Gets an array of members present on the channel as PresenceMessage objects.

options parametersARTRealtimePresenceQuery propertiesGetOptions properties

clientId:client_id

when provided, will filter array of members returned that match the provided clientIdclient_idClientId string

connectionId:connection_id

when provided, will filter array of members returned that match the provided connectionIdConnectionIdconnection_id":/api/realtime-sdk/connection#id string

waitForSync:wait_for_sync

true A boolean value that by default waits for the initial presence synchronization following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronization

historyHistory

history(Object options, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))Deferrable history(Hash options) → yields PaginatedResult<PresenceMessage>PaginatedResult<PresenceMessage> history(Param[] options)history(query: ARTRealtimeHistoryQuery?, callback: (ARTPaginatedResult<ARTPresenceMessage>?, ARTErrorInfo?) → Void) throwsTask<PaginatedResult> HistoryAsync(PaginatedRequestParams query, bool untilAttach = false [deprecated])

Gets a paginated set of historical presence message events for this channel. If the channel is configured to persist messages to disk, then the presence message event history will typically be available for 24 – 72 hours. If not, presence message events are only retained in memory by the Ably service for two minutes.

Parameters

optionsqueryParam[] optionsPaginatedRequestParams query

an optional object containing query parametersan optional set of key value pairs containing query parameters, as specified in the presence history API documentation.

callback

is a function of the form: function(err, resultPage)

&block

yields a PaginatedResult<Message> object

callback

called with a ARTPaginatedResult<ARTPresenceMessage> object or an error

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

subscribeSubscribe

There are overloaded versions of this method:

subscribe(listener(PresenceMessage))void subscribe(PresenceListener listener)subscribe → yields PresenceMessagesubscribe(callback: (ARTPresenceMessage) → Void) → ARTEventListenervoid Subscribe(Action handler)

Subscribe to presence message events on this channel. The caller supplies a listener functionan implementation of the PresenceListener interfacea blocka handler, which is called each time one or more presence events occurs such as a member entering or leaving a channel.

subscribe(String action, listener(PresenceMessage))void subscribe(PresenceMessage.Action action, PresenceListener listener)subscribe(PresenceMessage::ACTION action) → yields PresenceMessagesubscribe(action: ARTPresenceAction, callback: (ARTPresenceMessage) → Void) → ARTEventListenervoid Subscribe(PresenceAction action, Action handler)

Subscribe to presence message events with a given action on this channel. The caller supplies a listener functionan implementation of the PresenceListener interfacea blocka handler, which is called each time one or more presence events occurs such as a member entering or leaving a channel.

Parameters

action

The presence action event to subscribe to
Type: StringPresenceMessage.ActionPresenceActionPresenceMessage::ACTION actionARTPresenceAction

listener

is a function of the form function(message) to be called for each matching presence message event

listener

Message listener to be notified for matching presence message event
Type: @PresenceListener

&block

yields matching presence message event when received on the channel

callback

called with each matching presence message when received on the channel

handler

called with each matching presence message when received on the channel

Considerations

• If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling subscribe will implicitly attach the channel. However, regardless of the implicit attach outcome, the listenerblockhandler will still be registered
• If subscribe is called more than once with the same listenerblockhandler, then duplicates will be registered. For example, if you subscribe twice with the same listenerblockhandler and a presence message is later received, the same listenerblockhandler will be invoked twice
• The registered listenerblockhandler remains active on the presence channel regardless of the underlying channel state. For example, if you call subscribe when the underlying channel is attached and it later becomes detached or even failed, when the channel is reattached and a presence message is received, the listenersblockshandlers originally registered will still be invoked. Listeners are only removed when calling unsubscribe or when the underlying channel is released using the Realtime.channels.release(name)Realtime.Channels.Release(name) method
• If an exception is thrown in the subscribe listener and bubbles up to the event emitter, it will be caught and logged at error level, so as not to affect other listeners for the same event

unsubscribeUnsubscribe

There are sixthree overloaded versions of this method:

unsubscribe(String action, listener)void unsubscribe(PresenceMessage.Action action, PresenceListener listener)unsubscribe(PresenceMessage::ACTION action, &listener_proc)unsubscribe(action: ARTPresenceAction, listener: ARTEventListener)bool Unsubscribe(PresenceAction presenceAction, Action handler)

Unsubscribe the given listener from presence message events on this channel for the given action. This removes an earlier event-specific subscription.

unsubscribe(listener)void unsubscribe(PresenceListener listener)unsubscribe(&listener_proc)unsubscribe(listener: ARTEventListener)bool Unsubscribe(Action handler)

Unsubscribe the given listener from presence message events on this channel. This removes an earlier subscription.

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

Unsubscribes all listeners to presence message events on this channel. This removes all earlier subscriptions.

Parameters

action

The presence action event to unsubscribe from
Type: StringPresenceMessage.ActionPresenceMessage::ACTION actionARTPresenceAction

actions

An array of actions to unsubscribe from
Type: String[]

listener

is the callback listener function that was previously subscribed

listener

previously registered listener
Type: @PresenceListener

handler

previously registered handler

&listener_block

previously registered listener block

listener

previous return value from a subscribe call

enterCliententer_clientEnterClientAsync

Enter this presence channel for the given clientIdclient_idClientId. This method is provided to support typically server instances that act on behalf of multiple client IDs. See Managing multiple client IDs for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an API key, or with a token bound to a wildcard client ID.

There are two overloaded versions of this method.

With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to enter.

enterClient(String clientId, callback(ErrorInfo err))Deferrable enter_client(String client_id) → yieldsvoid enterClient(String clientId, CompletionListener listener)enterClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) → Void)?)Task EnterClientAsync(string clientId)

Enter a presence channel on behalf of the provided clientIdclient_idClientId without any data. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

enterClient(String clientId, Object data, callback(ErrorInfo err))Deferrable enter_client(String client_id, Object data) → yieldsvoid enterClient(String clientId, Object data, CompletionListener listener)enterClient(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)Task EnterClientAsync(string clientId, object clientData)

Enter a presence channel and provide data that is associated with the current present member. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

Parameters

data

data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object

data

data payload for the member. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object

data

data payload for the member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null.
Type: Object

data

data payload for the member. The supported payload types are Strings, Hash or Array objects that can be serialized 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

callback

is a function of the form function(err) which is called upon completion

listener

Listener to be notified on completion
Type: CompletionListener

&block

yields upon successfully entering the channel

callback

called upon successfully entering the channel, or with an error

leaveClientleave_clientLeaveClientAsync

Leave this presence channel for the given clientIdclient_idClientId. This method is provided to support typically server instances that act on behalf of multiple client IDs. See Managing multiple client IDs for more info. In order to leave the presence set of a channel, the client must have already entered and been present.

There are two overloaded versions of this method.

With both versions, a callbackblockcompletion listenerhandler can optionally be passed in to be notified of success or failure to leave.

leaveClient(String clientId, callback(ErrorInfo err))Deferrable leave_client(String client_id) → yieldsvoid leaveClient(String clientId, CompletionListener listener)leaveClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) → Void)?)Task LeaveClientAsync(string clientId, object data)

Leave a presence channel on behalf of the provided clientIdclient_idClientId without emitting any data.

leaveClient(String clientId, Object data, callback(ErrorInfo err))Deferrable leave_client(String client_id, Object data) → yieldsvoid leaveClient(String clientId, Object data, CompletionListener listener)leave(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)Task LeaveClientAsync(string clientId)

Leave a presence channel on behalf of the provided clientIdclient_idClientId and emit data that is associated with the current leaving member.

Parameters

data

data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object

data

data payload for the member. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object

data

data payload for the member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null.
Type: Object

data

data payload for the member. The supported payload types are Strings, Hash or Array objects that can be serialized 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

callback

is a function of the form function(err) which is called upon completion

listener

Listener to be notified on completion
Type: CompletionListener

&block

yields upon successfully entering the channel

callback

called upon successfully entering the channel, or with an error

updateClientupdate_clientUpdateClientAsync

Clients can update the member data on behalf of the given clientIdclient_idClientId which will trigger a broadcast of this update to all presence subscribers. This method is provided to support typically server instances that act on behalf of multiple client IDs. See Managing multiple client IDs for more info. If an attempt to update is made before the member has entered the channel, the update is treated as an enter.

A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data.

updateClient(String clientId, Object data, callback(ErrorInfo err))Deferrable update_client(String client_id, Object data) → yieldsvoid updateClient(String clientId, Object data, CompletionListener listener)update(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)Task UpdateClientAsync(string clientId, object data)

Update the member data on behalf of the provided clientIdclient_idClientId and broadcast an update event to all subscribers. data may be null. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

Parameters

data

data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.
Type: Object

data

data payload for the member. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null.
Type: Object

data

data payload for the member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null.
Type: Object

data

data payload for the member. The supported payload types are Strings, Hash or Array objects that can be serialized 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

callback

is a function of the form function(err) which is called upon completion

listener

Listener to be notified on completion
Type: CompletionListener

&block

yields upon successfully entering the channel

callback

called upon successfully entering the channel, or with an error

Related types

PresenceMessageARTPresenceMessageAbly::Models::PresenceMessageio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage

A PresenceMessage represents an individual presence update that is sent to or received from Ably.

PropertiesMembersAttributes

action

the event signified by a PresenceMessage. See PresenceMessage.action
Type: enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }

Action

the event signified by a PresenceMessage. See PresenceMessage.action
Type: enum { Absent, Present, Enter, Leave, Update }

action

the event signified by a PresenceMessage. See Presence action
Type: int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }

action

the event signified by a PresenceMessage. See PresenceAction
Type: int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }

action

the event signified by a PresenceMessage. See PresenceMessage::ACTION
Type: enum { :absent, :present, :enter, :leave, :update }

action

the event signified by a PresenceMessage. See PresenceMessage::ACTION
Type: const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE

action

the event signified by a PresenceMessage. See PresenceMessage.action
Type: ARTPresenceAction

Action

the event signified by a PresenceMessage. See PresenceMessage::action
Type: const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate

dataData

The presence update payload, if provided
String, ByteArray, JSONObject, JSONArrayString, byte[], plain C# object that can be converted to JsonString, StringBuffer, JSON ObjectString, []byteString, Binary (ASCII-8BIT String), Hash, ArrayString, Bytearray, Dict, ListString, NSData, Dictionary, ArrayNSString *, NSData *, NSDictionary *, NSArray *String, Binary String, Associative Array, Array

extrasExtras

Metadata and/or ancillary payloads, if provided. The only currently valid payload for extras is the push object.
Type: JSONObject, JSONArrayplain C# object that can be converted to JsonString, []byteJSON ObjectHash, ArrayDict, ListDictionary, ArrayNSDictionary *, NSArray *Associative Array, Array

idId

Unique ID assigned by Ably to this presence update
Type: String

clientIdclient_idClientId

The client ID of the publisher of this presence update
Type: String

connectionIdconnection_idConnectionId

The connection ID of the publisher of this presence update
Type: String

timestampTimestamp

Timestamp when the presence update was received by Ably, as milliseconds since the epoch.
Type: IntegerLong IntegerDateTimeOffsetTimeNSDate

encodingEncoding

This will typically be empty as all presence updates 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

PresenceMessage constructors

PresenceMessage.fromEncoded

PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) → PresenceMessage

A static factory method to create a PresenceMessage from a deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsg

a PresenceMessage-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 PresenceMessage object

PresenceMessage.fromEncodedArray

PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) → PresenceMessage[]

A static factory method to create an array of PresenceMessages from an array of deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsgs

an array of PresenceMessage-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 PresenceMessage objects

Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction

var PresenceActions = [
  'absent', // (reserved for internal use)
  'present',
  'enter',
  'leave',
  'update'
]

public enum Action {
  ABSENT,  // 0 (reserved for internal use)
  PRESENT, // 1
  ENTER,   // 2
  LEAVE,   // 3
  UPDATE   // 4
}

public enum Action {
  Absent,  // 0 (reserved for internal use)
  Present, // 1
  Enter,   // 2
  Leave,   // 3
  Update   // 4
}

class PresenceAction(object):
  ABSENT = 0    # (reserved for internal use)
  PRESENT = 1
  ENTER = 2
  LEAVE = 3
  UPDATE = 4

namespace Ably\Models;
class PresenceMessages {
  const ABSENT  = 0; /* (reserved for internal use) */
  const PRESENT = 1;
  const ENTER   = 2;
  const LEAVE   = 3;
  const UPDATE  = 4;
}

if ($presenceMessage->action == Ably\Models\PresenceMesage::ENTER) {
  /* do something */
}

:absent  # => 0 (reserved for internal use)
:present # => 1
:enter   # => 2
:leave   # => 3
:update  # => 4

PresenceMessage::ACTION.Absent  # => 0 (internal use)
PresenceMessage::ACTION.Present # => 1
PresenceMessage::ACTION.Enter   # => 2
PresenceMessage::ACTION.Leave   # => 3
PresenceMessage::ACTION.Update  # => 4

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

# Example with constants
presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... }

# Interchangeable
Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true

typedef NS_ENUM(NSUInteger, ARTPresenceAction) {
    ARTPresenceAbsent, // reserved for internal use
    ARTPresencePresent,
    ARTPresenceEnter,
    ARTPresenceLeave,
    ARTPresenceUpdate
};

enum ARTPresenceAction : UInt {
  case Absent // reserved for internal use
  case Present
  case Enter
  case Leave
  case Update
}

const (
  PresenceAbsent = 0
  PresencePresent = 1
  PresenceEnter = 2
  PresenceLeave = 3
  PresenceUpdate = 4
)

PaginatedRequestParams

io.ably.lib.realtime.CompletionListener

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);
}

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.

PropertiesMembersAttributes

itemsItems

contains the current 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>

Methods

firstFirst

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

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.

hasNextHasNexthas_next?has_next

Boolean hasNext()Boolean has_next?Boolean hasNext()Boolean has_next()Boolean HasNext()Boolean hasNext()Boolean hasNext()HasNext() (bool)

Returns true if there are more pages available by calling nextNext and returns false if this page is the last page available.

isLastIsLastlast?is_last

Boolean isLast()Boolean last?Boolean isLast()Boolean is_last()Boolean IsLast()Boolean isLast()Boolean isLast()IsLast() (bool)

Returns true if this page is the last page and returns false if there are more pages available by calling nextNext available.

nextNext

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

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 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 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast())")
    }
}

page0, err := channel.History(nil)
fmt.Println("Page. 0 item 0: %s\n", page0.Messages[0].Data)
page1, err := page0.Next()
fmt.Println("Page. 1 item 1: %s\n", page1.Messages[1].Data)
fmt.Println("Last page? %s\n", page1.IsLast())

io.ably.lib.types.Param

io.ably.lib.realtime.PresenceListener

public interface PresenceListener {
  // Called when one or more presence messages are received
  public void onPresenceMessage(PresenceMessage message);
}