History

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

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

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

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

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 the Ably the realtime service, 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

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

var allPresenceActions = [
  '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,
    ARTPresenceLast
};

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

IO.Ably.HistoryRequestParams

PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult

A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.

PropertiesMembersAttributesAttributes

itemsItems

contains a page of results (for example an Array of Message or PresenceMessage objects for a channel history request)
Type: Array <Message, Presence, Stats>Type: List <Message, Presence, Stats>

isLast

true if this page is the last page
Type: Boolean

last?

true if this page is the last page
Type: Boolean

isLast()

true if this page is the last page
Type: Boolean

is_last()

True if this page is the last page
Type: Boolean

hasNext

true if there are further pages
Type: Boolean

HasNext

true if there are further pages
Type: Boolean

has_next?

true if there are further pages
Type: Boolean

hasNext()

true if there are further pages
Type: Boolean

has_next()

True if there are further pages
Type: Boolean

Methods

firstFirst

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

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

itemsItems

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

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

nextNext

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

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

Example

channel.history(function(err, paginatedResult) {
  console.log('Page 0 item 0:' + paginatedResult.items[0].data);
  paginatedResult.next(function(err, nextPage) {
    console.log('Page 1 item 1: ' + nextPage.items[1].data);
    console.log('Last page?: ' + nextPage.isLast;
  });
});

channel.history(function(err, paginatedResult) {
  console.log('Page 0 item 0:' + paginatedResult.items[0].data);
  paginatedResult.next(function(err, nextPage) {
    console.log('Page 1 item 1: ' + nextPage.items[1].data);
    console.log('Last page?: ' + nextPage.isLast;
  });
});

PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};

PaginatedResult<Message> firstPage = await channel.HistoryAsync(null);
Message firstMessage = firstPage.Items[0];
Console.WriteLine("Page 0 item 0: " + firstMessage.data);
if (firstPage.HasNext)
{
    var nextPage = await firstPage.NextAsync();
    Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data);
    Console.WriteLine("More pages?: " + nextPage.HasNext);
}

# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end

result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())

$firstPage = $channel.history();
echo("Page 0 item 0: " . $firstPage->items[0]->data);
if ($firstPage->hasNext()) {
  $nextPage = $firstPage->next();
  echo("Page 1 item 1: " . $nextPage->items[1]->data);
  echo("Last page?: " . $nextPage->isLast());
}

[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast);
    }];
}];

channel.history { paginatedResult, error in
    let paginatedResult = paginatedResult!
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        let nextPage = nextPage!
        print("Page 0 item 0: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast)")
    }
}

io.ably.lib.types.Param