Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

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('{{API_KEY}}');
var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
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('{{API_KEY}}');
var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
channel.publish('example', 'message data', function(err) {
  channel.history(function(err, resultPage) {
    var lastMessage = resultPage.items[0];
    alert('Last message: ' + lastMessage.id + ' - ' + lastMessage.data);
  });
});
realtime = Ably::Realtime.new('{{API_KEY}}')
channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
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("{{API_KEY}}");
Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
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);
  }
});
var realtime = new AblyRealtime("{{API_KEY}}");
var channel = realtime.Channels.Get("{{RANDOM_CHANNEL_NAME}}");
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:@"{{API_KEY}}"];
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: "{{API_KEY}}")
let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}")
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

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('{{API_KEY}}');
var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
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('{{API_KEY}}');
var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
channel.attach(function(err) {
  channel.history({ untilAttach: true}, function(err, resultPage) {
    var lastMessage = resultPage.items[0];
    alert('Last message before attach: ' + lastMessage.data);
  });
});
realtime = Ably::Realtime.new('{{API_KEY}}')
channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
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("{{API_KEY}}");
Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
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();
var realtime = new AblyRealtime("{{API_KEY}}");
var channel = realtime.Channels.Get("{{RANDOM_CHANNEL_NAME}}");
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:@"{{API_KEY}}"];
ARTRealtimeChannel *channel = [realtime.channels get:@"RANDOM_CHANNEL_NAME"];
[channel attach];
[channel on:ARTChannelEventAttached call:^(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: "{{API_KEY}}")
let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}")
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 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(HistoryRequestParams dataQuery, bool untilAttach = false);

Gets a paginated set of historical messages for this channel.

Parameters

optionqueryParam[] optionHistoryRequestParams 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 propertiesHistoryRequestParams properties

start:startStart
beginning of time earliest DateTimeOffset or Time or time in milliseconds since the epoch for any messages retrieved
Type: LongInt or @TimeDateTimeOffset
end:endEnd
current time latest DateTimeOffset or Time or time in milliseconds since the epoch for any messages retrieved
Type: LongInt or @TimeDateTimeOffset
direction:directionDirection
backwards :forwards or :backwards
Type: StringSymbolDirection 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. If the Channel is not attached, enabling this option will result in 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(HistoryRequestParams query, bool untilAttach = false)

Gets a paginated set of historical presence events for this channel.

Parameters

optionqueryParam[] optionHistoryRequestParams 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 propertiesHistoryRequestParams properties

start:startStart
beginning of time earliest DateTimeOffset or Time or time in milliseconds since the epoch for any presence events retrieved
Type: LongInt or @TimeDateTimeOffset
end:endEnd
current time latest DateTimeOffset or Time or time in milliseconds since the epoch for any presence events retrieved
Type: LongInt or @TimeDateTimeOffset
direction:directionDirection
backwards :forwards or :backwards
Type: StringSymbolDirection enum
limit:limitLimit
100 maximum number of presence events to retrieve up to 1,000
Type: Integer
untilAttach:until_attach
false when true, ensures presence event history is up until the point of the channel being attached. See continuous history for more info. If the Channel is not attached, enabling this option will result in error
Type: Boolean

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.

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

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
data
The presence update payload, if provided
Type: String, ByteArray, JSONObject, JSONArray
Data
The presence update payload, if provided
Type: String, byte[], plain C# object that can be converted to Json
data
The presence update payload, if provided
Type: String, StringBuffer, JSON Object
data
The presence update payload, if provided
Type: String, Binary (ASCII-8BIT String), Hash, Array
data
The presence update payload, if provided
Type: String, Bytearray, Dict, List
data
The message payload, if provided
Type: String, NSData, Dictionary, Array
data
The message payload, if provided
Type: NSString *, NSData *, NSDictionary *, NSArray *
data
The message payload, if provided
Type: String, Binary String, 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

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
}

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

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)

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

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

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)

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

Back to top