History
The Realtime client library provides message and presence event history for channels. Channel history can be used to return continuous message history up to the exact point a realtime channel was attached, and combines both instantaneous “live” history as well as the longer term persisted history. If persisted history is enabled for the channel, then messages will typically be stored for 24 – 72 hours on disk. If persisted history is not enabled, Ably retains the last two minutes of instantaneous “live” message history in memory.
Getting started
The Ably Realtime client library provides a straightforward API to retrieve paginated message or presence event history. Each page of history, by default, contains up to 100 messages. Message ordering, by default, is from most recent to oldest.
var realtime = new Ably.Realtime('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo');
var channel = realtime.channels.get('law-pea-web');
channel.publish('example', 'message data', function(err) {
channel.history(function(err, resultPage) {
var lastMessage = resultPage.items[0];
alert('Last message: ' + lastMessage.id + ' - ' + lastMessage.data);
});
});
var realtime = new Ably.Realtime('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo');
var channel = realtime.channels.get('law-pea-web');
channel.publish('example', 'message data', function(err) {
channel.history(function(err, resultPage) {
var lastMessage = resultPage.items[0];
console.log('Last message: ' + lastMessage.id + ' - ' + lastMessage.data);
});
});
realtime = Ably::Realtime.new('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo')
channel = realtime.channels.get('law-pea-web')
channel.publish 'example', 'message data' do
channel.history do |result_page|
last_message = result_page.items.last
puts "Last message: #{last_message.message.id} - #{last_message.data}")
end
end
AblyRealtime realtime = new AblyRealtime("xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo");
Channel channel = realtime.channels.get("law-pea-web");
channel.publish("example", "message data", new CompletionListener() {
@Override
public void onError(ErrorInfo reason) {
System.out.println("Unable to publish message; err = " + reason.message);
}
@Override
public void onSuccess() {
PaginatedResult<Message> resultPage = channel.history(null);
Message lastMessage = resultPage.items[0];
System.out.println("Last message: " + lastMessage.id + " - " + lastMessage.data);
}
});
AblyRealtime realtime = new AblyRealtime("xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo");
IRealtimeChannel channel = realtime.Channels.Get("law-pea-web");
channel.Publish("example", "message data", async (success, error) =>
{
PaginatedResult<Message> resultPage = await channel.HistoryAsync(null);
Message lastMessage = resultPage.Items[0];
Console.WriteLine("Last message: " + lastMessage.Id + " - " + lastMessage.Data);
});
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo"];
ARTRealtimeChannel *channel = [realtime.channels get:@"RANDOM_CHANNEL_NAME"];
[channel publish:@"example" data:@"message data" callback:^(ARTErrorInfo *error) {
if (error) {
NSLog(@"Unable to publish message; err = %@", error.message);
return;
}
[channel history:^(ARTPaginatedResult<ARTMessage *> *resultPage, ARTErrorInfo *error) {
ARTMessage *lastMessage = resultPage.items[0];
NSLog(@"Last message: %@ - %@", lastMessage.id,lastMessage.data);
}];
}];
let realtime = ARTRealtime(key: "xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo")
let channel = realtime.channels.get("law-pea-web")
channel.publish("example", data: "message data") { error in
if let error = error {
print("Unable to publish message; err = \(error.message)")
return
}
channel.history { resultPage, error in
let lastMessage = resultPage!.items[0] as! ARTMessage
print("Last message: \(lastMessage.id) - \(lastMessage.data)")
}
}
Note that all examples on this page assume you are running them within an EventMachine reactor. Find out more in our Realtime usage documentation.
If you would prefer to just dive into code and see some examples of how to use history via the Realtime API, then we recommend you take a look at our Realtime tutorials.
Channel & Presence history
Both the Channel
and Presence
objects provide history. The Channel
object provides the history of Message
objects published on the channel, whereas the Presence
object provides presence event history of that channel i.e. members entering, updating or leaving the channel as PresenceMessage
objects.
Enabling persistent history
By default, persisted history on channels is disabled and messages are only stored by the Ably service for two minutes in memory. If persisted history is enabled for the channel, then messages will typically be stored for 24 – 72 hours on disk.
Every message that is persisted to or retrieved from disk counts as an extra message towards your monthly quote. For example, for a channel that has persistence enabled, if a message is published, two messages will be deducted from your monthly quota. If the message is later retrieved from history, another message will be deducted from your monthly quota.
To enable history on a channel, it is necessary to add a channel rule in the settings of your application dashboard. See the documentation on channel rules for further information on what they are and how to configure them.
Continuous history
By using rewind or History’s untilAttach
, it is possible to obtain message history that is continuous with the realtime messages received on an attached channel.
Rewind
If you wish to obtain history as part of attaching to a channel, you can use the rewind channel parameter. This will act as though you had attached to a channel from a certain message or time in the past, and play through all messages since that point. Check out the main rewind documentation for further details.
In current Ably libraries, or when using the service without a library, this is done by qualifying the channel name. There is a future library release planned in which it will be possible to specify channel params directly via the API. As an example, if the channel were [some_metadata]my_channel
, you would specify the use of rewind via [some_metadata?rewind=1]my_channel
. You can specify either a number of messages up to 100 to rewind to (for example 10
), or a time specifier of either seconds (10s
), or minutes (2m
) up to 2 minutes.
Note that this will only work whilst attaching to a channel.
var realtime = new Ably.Realtime('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo');
var channel = realtime.channels.get('[?rewind=1]law-pea-web');
channel.subscribe(function(message) {
alert('Received: ' + message.data);
});
var Ably = require('ably');
var realtime = new Ably.Realtime('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo');
var channel = realtime.channels.get('[?rewind=1]law-pea-web');
channel.subscribe(function(message) {
console.log("Received: " message.data);
});
realtime = Ably::Realtime.new('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo')
channel = realtime.channels.get('[?rewind=1]law-pea-web')
channel.subscribe do |message|
puts "Received: #{message.data}"
end
AblyRealtime realtime = new AblyRealtime("xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo");
Channel channel = realtime.channels.get("[?rewind=1]law-pea-web");
channel.subscribe(new MessageListener() {
@Override
public void onMessage(Message message) {
System.out.println("New messages arrived. " + message.name);
}
});
AblyRealtime realtime = new AblyRealtime("xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo");
IRealtimeChannel channel = realtime.Channels.Get("[?rewind=1]law-pea-web");
channel.Subscribe(message => {
Console.WriteLine($"Message: {message.Name}:{message.Data} received");
});
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo"];
ARTRealtimeChannel *channel = [realtime.channels get:@"[?rewind=1]law-pea-web"];
[channel subscribe:^(ARTMessage *message) {
NSLog(@"Received: %@", message.data);
}];
let realtime = ARTRealtime(key: "xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo")
let channel = realtime.channels.get("[?rewind=1]law-pea-web")
channel.subscribe { message in
print("Received: \(message.data)")
}
History with untilAttach
It is possible to obtain message history that is continuous with the realtime messages received on an attached channel, in the backwards direction from the point of attachment. When a Channel
instance is attached, it’s automatically populated by the Ably service with the serial number of the last published message on the channel. As such, using this serial number, the client library is able to make a history request to the Ably service for all messages received since the channel was attached. Any new messages therefore are received in realtime via the attached channel, and any historical messages are accessible via the history method.
In order to benefit from this functionality, the untilAttach
option can be used when making history requests on attached channels. If the channel is not yet attached, this will result in an error.
var realtime = new Ably.Realtime('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo');
var channel = realtime.channels.get('law-pea-web');
channel.attach(function(err) {
channel.history({ untilAttach: true}, function(err, resultPage) {
var lastMessage = resultPage.items[0];
alert('Last message before attach: ' + lastMessage.data);
});
});
var realtime = new Ably.Realtime('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo');
var channel = realtime.channels.get('law-pea-web');
channel.attach(function(err) {
channel.history({ untilAttach: true}, function(err, resultPage) {
var lastMessage = resultPage.items[0];
console.log('Last message before attach: ' + lastMessage.data);
});
});
realtime = Ably::Realtime.new('xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo')
channel = realtime.channels.get('law-pea-web')
channel.attach do
channel.history(until_attach: true) do |result_page|
last_message = result_page.items.last
puts "Last message before attach: #{last_message.data}")
end
end
AblyRealtime realtime = new AblyRealtime("xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo");
Channel channel = realtime.channels.get("law-pea-web");
channel.on(ChannelState.attached, new ChannelStateListener() {
@Override
public void onChannelStateChanged(ChannelStateChange stateChange, ErrorInfo reason) {
Param[] options = new Param[]{ new Param("untilAttach", "true") };
PaginatedResult<Message> resultPage = channel.history(options);
Message lastMessage = resultPage.items[0];
System.out.println("Last message before attach: " + lastMessage.data);
}
});
channel.attach();
AblyRealtime realtime = new AblyRealtime("xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo");
IRealtimeChannel channel = realtime.Channels.Get("law-pea-web");
await channel.AttachAsync();
PaginatedResult<Message> resultPage = await channel.HistoryAsync(untilAttach: true);
Message lastMessage = resultPage.Items[0];
Console.WriteLine("Last message before attach: " + lastMessage.data);
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo"];
ARTRealtimeChannel *channel = [realtime.channels get:@"RANDOM_CHANNEL_NAME"];
[channel attach];
[channel on:ARTChannelEventAttached callback:^(ARTErrorInfo *error) {
ARTRealtimeHistoryQuery *query = [[ARTRealtimeHistoryQuery alloc] init];
query.untilAttach = YES;
[channel history:query callback:^(ARTPaginatedResult<ARTMessage *> *resultPage, ARTErrorInfo *error) {
ARTMessage *lastMessage = resultPage.items[0];
NSLog(@"Last message: %@ - %@", lastMessage.id,lastMessage.data);
} error:nil];
}];
let realtime = ARTRealtime(key: "xVLyHw.QYYqTw:xAWEPB-IY_P9nEzo")
let channel = realtime.channels.get("law-pea-web")
channel.attach()
channel.on(.attached) { error in
let query = ARTRealtimeHistoryQuery()
query.untilAttach = true
try! channel.history(query) { resultPage, error in
let lastMessage = resultPage!.items[0] as! ARTMessage
print("Last message before attach: \(lastMessage.id) - \(lastMessage.data)")
}
}
API reference
- Channel
- Presence
- Related types
Channel object
The Realtime Channel
object exposes the following public method to obtain Message
history.
Methods
historyHistory
history(Object option, callback(ErrorInfo err, PaginatedResult<Message> resultPage))Deferrable history(Hash option) → yields PaginatedResult<Message>PaginatedResult<Message> history(Param[] option)history(query: ARTRealtimeHistoryQuery?, callback: (ARTPaginatedResult<ARTMessage>?, ARTErrorInfo?) → Void) throwsTask<PaginatedResult
> HistoryAsync(PaginatedRequestParams dataQuery, bool untilAttach = false);
Gets a paginated set of historical messages for this channel.
Parameters
- optionqueryParam[] optionPaginatedRequestParams query
- an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified below.
- 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
options
parametersARTRealtimeHistoryQuery
propertiesPaginatedRequestParams
properties
- start:startStart
-
beginning of time earliest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any messages retrieved
Type:Long
Int or @Time
DateTimeOffset
- end:endEnd
-
current time latest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any messages retrieved
Type:Long
Int or @Time
DateTimeOffset
- direction:directionDirection
-
backwards
:
forwards
or:
backwards
Type:String
Symbol
Direction
enum - limit:limitLimit
-
100 maximum number of messages to retrieve up to 1,000
Type:Integer
- untilAttach:until_attach
-
false when true, ensures message history is up until the point of the channel being attached. See continuous history for more info. Requires the
direction
to bebackwards
(the default). If theChannel
is not attached, or ifdirection
is set toforwards
, this option will result in an error
Type:Boolean
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
Returns a Task
that 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.
Presence object
Realtime Presence
object exposes the following public method to obtain presence event history such as enter, update and leave events. These events are represented as PresenceMessage
objects.
Methods
historyHistory
history(Object option, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))Deferrable history(Hash option) → yields PaginatedResult<PresenceMessage>PaginatedResult<PresenceMessage> history(Param[] option)history(query: ARTRealtimeHistoryQuery?, callback: (ARTPaginatedResult<ARTPresenceMessage>?, ARTErrorInfo?) → Void) throwsTask<PaginatedResult<PresenceMessage>> HistoryAsync(PaginatedRequestParams query, bool untilAttach = false [deprecated])
Gets a paginated set of historical presence events for this channel.
Parameters
- optionqueryParam[] optionPaginatedRequestParams query
- an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified below.
- callback
- is a function of the form:
function(err, resultPage)
- &block
- yields a
PaginatedResult<PresenceMessage>
object - callback
- called with a ARTPaginatedResult<ARTPresenceMessage> object or an error
options
parametersARTRealtimeHistoryQuery
propertiesPaginatedRequestParams
properties
- start:startStart
-
beginning of time earliest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any presence events retrieved
Type:Long
Int or @Time
DateTimeOffset
- end:endEnd
-
current time latest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any presence events retrieved
Type:Long
Int or @Time
DateTimeOffset
- direction:directionDirection
-
backwards
:
forwards
or:
backwards
Type:String
Symbol
Direction
enum - limit:limitLimit
-
100 maximum number of presence events to retrieve up to 1,000
Type:Integer
Callback result
On success, resultPage
contains a PaginatedResult
encapsulating an array of PresenceMessage
objects corresponding to the current page of results. PaginatedResult
supports pagination using next()
and first()
methods.
On failure to retrieve presence event history, err
contains an ErrorInfo
object with the failure reason.
Returns
On success, the returned PaginatedResult
encapsulates an array of PresenceMessage
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
Failure to retrieve the presence event history will raise an AblyException
Returns
Returns a Task
that needs to be awaited.
On success, the returned PaginatedResult
encapsulates an array of PresenceMessage
objects corresponding to the current page of results. PaginatedResult
supports pagination using NextAsync
and FirstAsync
methods.
Failure to retrieve the presence event 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 PresenceMessage
objects corresponding to the current page of results. PaginatedResult
supports pagination using next()
and first()
methods.
Failure to retrieve the presence event history will trigger the errback
callbacks of the Deferrable
with an ErrorInfo
object with the failure reason.
Related types
MessageARTMessageAbly::Models::Message Enumio.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
- dataData
- The presence update payload, if provided
Type:String
,ByteArray
,JSONObject
,JSONArray
String
,byte[]
, plain C# object that can be converted to JsonString
,[]byte
String
,StringBuffer
,JSON Object
String
,Binary
(ASCII-8BIT String),Hash
,Array
String
,Bytearray
,Dict
,List
String
,NSData
,Dictionary
,Array
NSString *
,NSData *
,NSDictionary *
,NSArray *
String
,Binary String
,Associative Array
,Array
Object
- extrasExtras
- Metadata and/or ancillary payloads, if provided. The only currently valid payload for extras is the
push
object.
Type:JSONObject
,JSONArray
plain C# object that can be converted to JsonString
,[]byte
JSON Object
Hash
,Array
Dict
,List
Dictionary
,Array
NSDictionary *
,NSArray *
Associative Array
,Array
Map
,List
- idId
- Unique ID assigned by Ably to this message. Can optionally be assigned by the client as part of idempotent publishing
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 message was received by the Ably service, as milliseconds since the epocha
Time
object
Type:Integer
Long Integer
DateTimeOffset
Time
NSDate
DateTime
- 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
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
PresenceMessageARTPresenceMessageAbly::Models::PresenceMessage Enumio.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
,JSONArray
String
,byte[]
, plain C# object that can be converted to JsonString
,StringBuffer
,JSON Object
String
,[]byte
String
,Binary
(ASCII-8BIT String),Hash
,Array
String
,Bytearray
,Dict
,List
String
,NSData
,Dictionary
,Array
NSString *
,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
,JSONArray
plain C# object that can be converted to JsonString
,[]byte
JSON Object
Hash
,Array
Dict
,List
Dictionary
,Array
NSDictionary *
,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:Integer
Long Integer
DateTimeOffset
Time
NSDate
- 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
Presence
action
is a String with a value matching any of the Realtime Presence
states & events.
var PresenceActions = [
'absent', // (reserved for internal use)
'present',
'enter',
'leave',
'update'
]
io.ably.lib.types.PresenceMessage.Action
is an enum representing all the Realtime Presence
states & events.
public enum Action {
ABSENT, // 0 (reserved for internal use)
PRESENT, // 1
ENTER, // 2
LEAVE, // 3
UPDATE // 4
}
IO.Ably.PresenceAction
is an enum representing all the Realtime Presence
states & events.
public enum Action {
Absent, // 0 (reserved for internal use)
Present, // 1
Enter, // 2
Leave, // 3
Update // 4
}
PresenceAction
is an enum-like class representing all the Realtime Presence
states & events.
class PresenceAction(object):
ABSENT = 0 # (reserved for internal use)
PRESENT = 1
ENTER = 2
LEAVE = 3
UPDATE = 4
PresenceMessage Action
is one of the class constants representing all the Realtime Presence
states & events.
namespace Ably\Models;
class PresenceMessages {
const ABSENT = 0; /* (reserved for internal use) */
const PRESENT = 1;
const ENTER = 2;
const LEAVE = 3;
const UPDATE = 4;
}
Example usage
if ($presenceMessage->action == Ably\Models\PresenceMesage::ENTER) {
/* do something */
}
Ably::Models::PresenceMessage::ACTION
is an enum-like value representing all the Realtime Presence
states & events. ACTION
can be represented interchangeably as either symbols or constants.
Symbol states
:absent # => 0 (reserved for internal use)
:present # => 1
:enter # => 2
:leave # => 3
:update # => 4
Constant states
PresenceMessage::ACTION.Absent # => 0 (internal use)
PresenceMessage::ACTION.Present # => 1
PresenceMessage::ACTION.Enter # => 2
PresenceMessage::ACTION.Leave # => 3
PresenceMessage::ACTION.Update # => 4
Example usage
# Example with symbols
presence.on(:attached) { ... }
# Example with constants
presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... }
# Interchangeable
Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true
ARTPresenceAction
is an enum representing all the Realtime Presence
states & events.
typedef NS_ENUM(NSUInteger, ARTPresenceAction) {
ARTPresenceAbsent,
ARTPresencePresent,
ARTPresenceEnter,
ARTPresenceLeave,
ARTPresenceUpdate
};
enum ARTPresenceAction : UInt {
case Absent
case Present
case Enter
case Leave
case Update
}
Presence
action
is a String with a value matching any of the Realtime Presence
states & events.
const (
PresenceAbsent = 0
PresencePresent = 1
PresenceEnter = 2
PresenceLeave = 3
PresenceUpdate = 4
)
IO.Ably.PaginatedRequestParams
HistoryRequestParams
is a type that encapsulates the parameters for a history queries. For example usage see Channel#history
Channel#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
orBackwards
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>
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
orPresenceMessage
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 next
Next
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 next
Next
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 null
a blank PaginatedResult will be returnedNull
None
nil
is returned. The method is asynchronous and return a Task which needs to be awaited to get the PaginatedResult
When 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
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