Presence
- Methods
- Related types
Methods
getGet
Get the current presence member set for this channel. In the REST client library this method directly queries Ably’s REST presence API
get(Object options, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))PaginatedResult<PresenceMessage> get(Hash options)PaginatedResult<PresenceMessage> get(kwargs_options)PaginatedResult<PresenceMessage> get(Array options)PaginatedResult<PresenceMessage> get(Param[] options)Task<PaginatedResult<PresenceMessage>> GetAsync(int? limit = null, string clientId = null, string connectionId = null);get(query: ARTPresenceQuery, callback: (ARTPresenceMessage, ARTErrorInfo?) → Void)(p *RestPresence) Get(options *PaginateParams) (*PaginatedResult, error)
Gets an array of members present on the channel as PresenceMessage objects.
Parameters
- optionsqueryParam[] options
- an optional object containing query parametersoptional keyword arguments containing the query parametersan optional set of symbol key and value pairs containing the query parametersan optional Associate Array containing the query parameters as specified below.
- callback
- is a function of the form:
function(err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage)
- callback
- called with a
PaginatedResult
<
PresenceMessage
>
, or with an error
options
parametersARTPresenceQuery
propertiesArguments
- clientIdclient_id:client_id
- when provided, will filter array of members returned that match the provided
clientId
client_id
ClientId
string - connectionIdconnection_id:connection_id
- when provided, will filter array of members returned that match the provided
connectionId
ConnectionId
connection_id
":/api/realtime-sdk/connection#id string
Callback result
On success, resultPage
contains a PaginatedResult
encapsulating an array of PresenceMessage
objects corresponding to the current page of members currently present on the channel. PaginatedResult
supports pagination using next()
and first()
methods.
On failure to retrieve the current presence member set, err
contains an ErrorInfo
object with the failure reason.
Returns
This method is asynchronous and needs to be awaited.
On success, the returned PaginatedResult
encapsulates an array of PresenceMessage
objects corresponding to the current page of members currently present on the channel. PaginatedResult
supports pagination using next
NextAsync
and first
FirstAsync
methods.
Failure to retrieve the current presence member set will raise an AblyException
Returns
This method is asynchronous and needs to be awaited.
On success, resultPage
contains a PaginatedResult
encapsulating an array of PresenceMessage
objects corresponding to the current page of members currently present on the channel. PaginatedResult
supports pagination using next()
and first()
methods.
Failure to retrieve the current presence member, the error
contains an ErrorInfo
object with the failure reason.
History
history(Object options, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))PaginatedResult<PresenceMessage> history(Hash options)PaginatedResult<PresenceMessage> history(kwargs_options)PaginatedResult<PresenceMessage> history(Array options)PaginatedResult<PresenceMessage> history(Param[] options)Task<PaginatedResult<PresenceMessage>> HistoryAsync(PaginatedRequestParams query);history(query: ARTDataQuery?, callback: (ARTPaginatedResult<ARTPresenceMessage>?, ARTErrorInfo?) → Void) throws(p *RestPresence) History(params *PaginateParams) (*PaginatedResult, error)
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
- optionsParam[] optionsqueryPaginatedRequestParams query
- an optional object containing query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing query parametersan optional Associate Array containing the query parameters, as specified in the presence history API documentation.
- callback
- is a function of the form:
function(err, resultPage)
- callback
- called with a ARTPaginatedResult<ARTPresenceMessage> object or an error
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 message history, err
contains an ErrorInfo
object with the failure reason.
Returns
This method is asynchronous and 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 next
NextAsync
and first
FirstAsync
methods.
Failure to retrieve the message history will raise an AblyException
Returns
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.
Upon failure to retrieve the message history, the error
contains an ErrorInfo
object with the failure reason.
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
,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 actionPresenceActionARTPresenceActionio.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, // 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
}
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
)
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