Types
The Ably REST client library defines both data types and option types. Data types are used to represent object such as messages; Option types are used in method arguments.
Where client libraries support both Realtime and REST APIs, the types are shared between both clients.
All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object.
If you are interested in finding out more about the exact types and options definitions in each language, we recommend you download our open source libraries and review the code.
- REST Data types
- REST Other Types
REST Data types
io.ably.lib.types.AblyExceptionAbly::Exceptions::BaseAblyExceptionAblyExceptionAbly\Exceptions\AblyExceptionIO.Ably.AblyException
An AblyException
is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable.
PropertiesMembersAttributes
- errorInfoErrorInfo
-
@ErrorInfo corresponding to this exception, where applicable
Type:ErrorInfo
A BaseAblyException
an AblyException
is an exception encapsulating error information containing an Ably-specific error code and generic status code, where applicable.
PropertiesMembersAttributesAttributes
- codeCode
- Ably error code (see ably-common/protocol/errors.json)
Type:Integer
- statusCodestatus_codeStatusCode
-
HTTP Status Code corresponding to this error, where applicable
Type:Integer
- messageMessage
- Additional message information, where available
Type:String
ChannelDetails
ChannelDetails
is an object returned when requesting or receiving channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.
- channelId
- the required name of the channel including any qualifier, if any
Type:string
- region
- in events relating to the activity of a channel in a specific region, this optionally identifies the region
Type:string
- isGlobalMaster
- in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel
Type:boolean
- status
- an optional
ChannelStatus
instance
Type: ChannelStatus
The following is an example of a ChannelDetails
JSON object:
{
"channelId": "foo",
"status": {
"isActive": true,
"occupancy": {
"metrics": {
"connections": 1,
"publishers": 1,
"subscribers": 1,
"presenceConnections": 1,
"presenceMembers": 0,
"presenceSubscribers": 1
}
}
}
}
ChannelDetails.ChannelStatus
ChannelStatus
is contained within the ChannelDetails
object, and optionally contains an Occupancy object.
- isActive
- a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity
Type:boolean
- occupancy
- an optional
Occupancy
instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
Type: Occupancy
ChannelDetails.ChannelStatus.Occupancy
Occupancy is optionally contained within the ChannelStatus
object, and contains metadata relating to the occupants of the channel. This is usually contained within the occupancy
attribute of the ChannelStatus
object.
The occupancy
attribute contains the metrics
attribute, which contains the following members:
- connections
- the number of connections
Type:integer
- publishers
- the number of connections attached to the channel that are authorised to publish
Type:integer
- subscribers
- the number of connections attached that are authorised to subscribe to messages
Type:integer
- presenceSubscribers
- the number of connections that are authorised to subscribe to presence messages
Type:integer
- presenceConnections
- the number of connections that are authorised to enter members into the presence channel
Type:integer
- presenceMembers
- the number of members currently entered into the presence channel
Type:integer
ErrorInfoARTErrorInfoio.ably.lib.types.ErrorInfoAbly::Models::ErrorInfoAbly\Models\ErrorInfoIO.Ably.ErrorInfo
An ErrorInfo
is a type encapsulating error information containing an Ably-specific error code and generic status code.
PropertiesMembersAttributes
- codeCode
- Ably error code (see ably-common/protocol/errors.json)
Type:Integer
- statusCodestatus_codeStatusCode
-
HTTP Status Code corresponding to this error, where applicable
Type:Integer
- messageMessage
- Additional message information, where available
Type:String
- causeCause
- Information pertaining to what caused the error where available
Type:ErrorInfo
{{LANG_BLOCK[flutter]}}
- href
- Link pointing to ably docs with more details on the error
Type:String
- requestId
- Request ID with which the error can be identified
Type:String
{{/LANG_BLOCK}}
MessageARTMessageio.ably.lib.types.MessageAbly::Models::MessageAbly\Models\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
PresenceMessageARTPresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageAbly\Models\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::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
)
PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::PaginatedResultAbly\Models\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())
HttpPaginatedResponse
An HttpPaginatedResponse
is a superset of PaginatedResult
, which is a type that represents a page of results plus metadata indicating the relative queries available to it. HttpPaginatedResponse
additionally carries information about the response to an HTTP request. It is used when making custom HTTP requests.
PropertiesMembersAttributesAttributes
- itemsItems
- contains a page of results (for example an Array of
Message
orPresenceMessage
objects for a channel history request).
Type:Array<>
Type:List<>
- statusCodestatus_codeStatusCode
- the HTTP status code of the response
Type:Number
- successSuccess
- whether that HTTP status code indicates success (equivalent to
200 <= statusCode < 300
)
Type:Boolean
- headersHeaders
- the response’s headers
Type:Object
Methods
firstFirst
first(callback(ErrorInfo err, HttpPaginatedResponse resultPage))HttpPaginatedResponse firstHttpPaginatedResponse first()HttpPaginatedResponse first()Task<HttpPaginatedResponse
> FirstAsync() HttpPaginatedResponse first()first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) → Void)First() (HttpPaginatedResponse, error)
Returns a new HttpPaginatedResponse
for the first page of results. When using the Realtime library, the first
method returns a Deferrable and yields an HttpPaginatedResponse
.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/api/realtime-sdk/types#http-paginated-response.
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, HttpPaginatedResponse resultPage))HttpPaginatedResponse nextHttpPaginatedResponse next()HttpPaginatedResponse next()Task<HttpPaginatedResponse
> NextAsync() HttpPaginatedResponse next()next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) → Void)Next() (HttpPaginatedResponse, error)
Returns a new HttpPaginatedResponse
loaded with the next page of results. If there are no further pages, then null
a blank HttpPaginatedResponse will be returnedNull
None
nil
is returned. The method is asynchronous and return a Task which needs to be awaited to get the HttpPaginatedResponse
When using the Realtime library, the first
method returns a Deferrable and yields an HttpPaginatedResponse.
Example
The HttpPaginatedResponse
interface is a superset of PaginatedResult
, see the PaginatedResult
example
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
TokenDetailsARTTokenDetailsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetailsAbly\Models\TokenDetailsIO.Ably.TokenDetails
TokenDetails
is a type providing details of Ably Token string and its associated metadata.
PropertiesMembersAttributes
- tokenToken
- The Ably Token itself. A typical Ably Token string may appear like
xVLyHw.A-pwh7wR9LihfnuyRs28QCPGgNuNnP5fpiNbMZlunrwHD48YHg
Type:String
- expiresExpires
-
The time (in milliseconds since the epoch)The time at which this token expires
Type:Integer
Long Integer
DateTimeOffset
Time
NSDate
- issuedIssued
-
The time (in milliseconds since the epoch)The time at which this token was issued
Type:Integer
Long Integer
DateTimeOffset
Time
NSDate
- capabilityCapability
- The capability associated with this Ably Token. The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. Read more about authentication and capabilities
Type:String
Capability
- clientIdclient_idClientId
- The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID. The client is then considered to be an identified client
Type:String
Methods
- expired?
- True when the token has expired
Type:Boolean
Methods
- is_expired()
- True when the token has expired
Type:Boolean
Methods
- IsValidToken()
- True if the token has not expired
Type:Boolean
TokenDetails constructors
TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap
TokenDetails.fromJson(String json) → TokenDetailsTokenDetails.from_json(String json) → TokenDetailsTokenDetails.fromMap(Map<String, dynamic> map)
A static factory methodnamed constructor to create a TokenDetails
from a deserialized TokenDetails
-like object or a JSON stringified TokenDetails
map. This method is provided to minimize bugs as a result of differing types by platform for fields such as timestamp
or ttl
. For example, in Ruby ttl
in the TokenDetails
object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json
it is automatically converted to the Ably standard which is milliseconds. By using the fromJson
fromMap
method when constructing a TokenDetails
, Ably ensures that all fields are consistently serialized and deserialized across platforms.
Parameters
- json
- a
TokenDetails
-like deserialized object or JSON stringifiedTokenDetails
.
Type:Object, String
- map
- a
TokenDetails
-like deserialized map.
Type:Map<String, dynamic>
Returns
A TokenDetails
object
TokenRequestARTTokenRequestio.ably.lib.types.TokenRequestAbly::Models::TokenRequestAbly\Models\TokenRequestIO.Ably.TokenRequest
TokenRequest
is a type containing parameters for an Ably TokenRequest
. Ably Tokens are requested using Auth#requestTokenAuth#request_token
PropertiesMembersAttributes
- keyNamekey_nameKeyName
- The key name of the key against which this request is made. The key name is public, whereas the key secret is private
Type:String
- ttlTtl
- Requested time to live for the Ably Token in millisecondsin secondsas a
TimeSpan
. If the AblyTokenRequest
is successful, the TTL of the returned Ably Token will be less than or equal to this value depending on application settings and the attributes of the issuing key.
Type:Integer
TimeSpan
NSTimeInterval
- timestampTimestamp
- The timestamp of this request in milliseconds
Type:Integer
Long Integer
Time
DateTimeOffset
NSDate
- capabilityCapability
- Capability of the requested Ably Token. If the Ably
TokenRequest
is successful, the capability of the returned Ably Token will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. Read more about authentication and capabilities
Type:String
- clientIdclient_idClientId
- The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to perform operations on behalf of that client ID
Type:String
- nonceNonce
- An opaque nonce string of at least 16 characters
Type:String
- macMac
- The Message Authentication Code for this request
Type:String
TokenRequest constructors
TokenRequest.fromJsonTokenRequest.from_jsonTokenRequest.fromMap
TokenRequest.fromJson(String json) → TokenRequestTokenRequest.from_json(String json) → TokenRequestTokenRequest.fromMap(Map<String, dynamic> map)
A static factory methodnamed constructor to create a TokenRequest
from a deserialized TokenRequest
-like object or a JSON stringified TokenRequest
/span>map. This method is provided to minimize bugs as a result of differing types by platform for fields such as timestamp
or ttl
. For example, in Ruby ttl
in the TokenRequest
object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json
it is automatically converted to the Ably standard which is milliseconds. By using the fromJson
fromMap
method when constructing a TokenRequest
, Ably ensures that all fields are consistently serialized and deserialized across platforms.
Parameters
- json
- a
TokenRequest
-like deserialized object or JSON stringifiedTokenRequest
.
Type:Object, String
- map
- a
TokenRequest
-like deserialized map.
Type:Map<String, dynamic>
Returns
A TokenRequest
object
Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsAbly\Models\StatsIO.Ably.Stats
A Stats
object represents an application’s statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our statistics API as well as your application dashboard.
Please note that most attributes of the Stats
type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the Ruby library stats documentation which contains exhaustive stats documentation. Ruby and Python however uses under_score
case instead of the default camelCase
in most languages, so please bear that in mind.
PropertiesMembersAttributesKeyword arguments
- unit
- the length of the interval that this statistic covers, such as
:minute
,:hour
,:day
,:month
Minute
,Hour
,Day
,Month
StatGranularityDay
,StatGranularityMonth
'minute'
,'hour'
,'day'
,'month'
.
Type:Stats::GRANULARITY
StatsIntervalGranularity enum
ARTStatsGranularity
String
- interval_granularityintervalGranularity
- Deprecated alias for
unit
; scheduled to be removed in version 2.x client library versions.
Type:Stats::GRANULARITY
StatsIntervalGranularity enum
ARTStatsGranularity
String
- intervalIdinterval_idIntervalId
- the UTC time at which the time period covered by this
Stats
object starts. For example, an interval ID value of “2018-03-01:10” in aStats
object whoseunit
isday
would indicate that the period covered is “2018-03-01:10 .. 2018-03-01:11”. AllStats
objects, except those whoseunit
isminute
, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer theunit
by looking at the resolution of theintervalId
.Stats
objects covering an individual minute will have an interval ID indicating that time; for example “2018-03-01:10:02”.
Type:String
- interval_timeIntervalTime
- A
Time
DateTime
DateTimeOffset
object representing the parsedintervalId
interval_id
IntervalId
(the UTC time at which the time period covered by thisStats
object starts)
Type:Time
DateTime
DateTimeOffset
- allAll
- aggregate count of both
inbound
andoutbound
message stats
Type:MessageTypes
- apiRequestsapi_requestsApiRequests
- breakdown of API requests received via the Ably REST API
Type:RequestCount
- channelsChannels
- breakdown of channel related stats such as min, mean and peak channels
Type:ResourceCount
- connectionsConnections
- breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections
Type:ConnectionTypes
- inboundInbound
- statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages
Type:MessageTraffic
- outboundOutbound
- statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messages
Type:MessageTraffic
- persistedPersisted
- messages persisted and later retrieved via the history API
Type:MessageTypes
- tokenRequeststoken_requestsTokenRequests
- breakdown of Ably Token requests received via the Ably REST API.
Type:RequestCount
- pushPush
- Detailed stats on push notifications, see our Push documentation for more details
Type:PushStats
ARTStatsGranularity
ARTStatsGranularity
is an enum specifying the granularity of a ARTStats interval
.
typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
ARTStatsGranularityMinute,
ARTStatsGranularityHour,
ARTStatsGranularityDay,
ARTStatsGranularityMonth
};
enum ARTStatsGranularity : UInt {
case Minute
case Hour
case Day
case Month
}
StatsIntervalGranularity
is an enum specifying the granularity of a Stats interval
.
public enum StatsGranularity
{
Minute,
Hour,
Day,
Month
}
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>
REST Other types
AuthOptions ObjectARTAuthOptionsAuthOptions HashAuthOptions Arrayio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions
AuthOptions
is a plain JavaScript object and is used when making authentication requests. If passed in, an authOptions
object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported:
AuthOptions
is a Hash object and is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash:
AuthOptions
is a Dict and is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Dict:
AuthOptions
is an Associative Array and is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated. The following named keys and values can be added to the Associative Array:
ART
AuthOptions
is used when making authentication requests. These options will supplement or override the corresponding options given when the library was instantiated.
PropertiesMembersAttributesAttributes
- authCallbackAuthCallbackauth_callback:auth_callback
- A functionfunction with the form
function(tokenParams, callback(err, tokenOrTokenRequest))
TokenCallback
instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signedTokenRequest
; aTokenDetails
(in JSON format); an Ably JWT. See an authentication callback example or our authentication documentation for details of the Ably TokenRequest format and associated API calls.
Type:Callable
TokenCallback
Proc
Func<TokenParams, Task<TokenDetails>>
- authUrlAuthUrl:auth_urlauth_url
- A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed
TokenRequest
; aTokenDetails
(in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.
Type:String
Uri
NSURL
- authMethodAuthMethodauth_method:auth_method
-
GET
:get
The HTTP verb to use for the request, eitherGET
:get
orPOST
:post
Type:String
Symbol
HttpMethod
- authHeadersAuthHeadersauth_headers:auth_headers
- A set of key value pair headers to be added to any request made to the
authUrl
AuthUrl
. Useful when an application requires these to be added to validate the request or implement the response. If theauthHeaders
object contains anauthorization
key, thenwithCredentials
will be set on the xhr request.
Type:Object
Dict
Hash
Associative Array
Param []
Dictionary<string, string>
Map<String, String>
- authParamsAuthParams:auth_paramsauth_params
- A set of key value pair params to be added to any request made to the
authUrl
AuthUrl
. When theauthMethod
AuthMethod
isGET
, query params are added to the URL, whereas whenauthMethod
AuthMethod
isPOST
, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type:Object
Hash
Associative Array
Param[]
Dictionary<string, string>
NSArray<NSURLQueryItem *>
[NSURLQueryItem]/Array<NSURLQueryItem>
Map<String, String>
- tokenDetailsTokenDetailstoken_details:token_details
- An authenticated
TokenDetails
object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such asauthUrl
AuthUrl
:auth_url
auth_url
orauthCallback
AuthCallbackauth_callback
:auth_callback
. Use this option if you wish to use Token authentication. Read more about Token authentication
Type:TokenDetails
- keyKey:keykey
- Optionally the API key to use can be specified as a full key string; if not, the API key passed into
ClientOptions
when instancing the Realtime or REST library is used
Type:String
- queryTimeQueryTime:query_timequery_time
-
false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
Type:Boolean
- tokenToken:token
- An authenticated token. This can either be a
TokenDetails
object, aTokenRequest
object, or token string (obtained from thetoken
Token
property of aTokenDetails
component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such asauthUrl
AuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type:String
,TokenDetails
orTokenRequest
ClientOptions ObjectARTClientOptionsClientOptions HashClientOptions Arrayio.ably.types.ClientOptionsIO.Ably.ClientOptions
ClientOptions
is a plain JavaScript object and is used in the Ably.Rest
constructor’s options
argument. The following attributes can be defined on the object:
ClientOptions
is a Hash object and is used in the Ably::Rest
constructor’s options
argument. The following key symbol values can be added to the Hash:
ClientOptions
is a associative array and is used in the Ably\AblyRest
constructor’s options
argument. The following named keys and values can be added to the associative array:
ART
ClientOptions
is used in the AblyRest
constructor’s options
argument.
ably.ClientOptions
is used in the ably.Rest
constructor’s options
named argument
PropertiesMembersAttributesKeyword arguments
- keyKey:key
- The full key string, as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about Basic authentication
Type:String
- tokenToken:token
- An authenticated token. This can either be a
TokenDetails
object, aTokenRequest
object, or token string (obtained from thetoken
Token
property of aTokenDetails
component of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such asauthUrl
AuthUrl
:auth_urlauth_url orauthCallback
AuthCallback
auth_callback
:auth_callback
. Read more about Token authentication
Type:String
,TokenDetails
orTokenRequest
- authCallbackAuthCallbackauth_callback:auth_callback
- A functionfunction with the form
function(tokenParams, callback(err, tokenOrTokenRequest))
TokenCallback
instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signedTokenRequest
; aTokenDetails
(in JSON format); an Ably JWT. See an authentication callback example or our authentication documentation for details of the Ably TokenRequest format and associated API calls.
Type:Callable
TokenCallback
Proc
Func<TokenParams, Task<TokenDetails>>
- authUrlAuthUrl:auth_urlauth_url
- A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed
TokenRequest
; aTokenDetails
(in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.
Type:String
Uri
NSURL
- authMethodAuthMethodauth_method:auth_method
-
GET
:get
The HTTP verb to use for the request, eitherGET
:get
orPOST
:post
Type:String
Symbol
HttpMethod
- authHeadersAuthHeadersauth_headers:auth_headers
- A set of key value pair headers to be added to any request made to the
authUrl
AuthUrl
. Useful when an application requires these to be added to validate the request or implement the response. If theauthHeaders
object contains anauthorization
key, thenwithCredentials
will be set on the xhr request.
Type:Object
Dict
Hash
Associative Array
Param []
Dictionary<string, string>
Map<String, String>
- authParamsAuthParams:auth_paramsauth_params
- A set of key value pair params to be added to any request made to the
authUrl
AuthUrl
. When theauthMethod
AuthMethod
isGET
, query params are added to the URL, whereas whenauthMethod
AuthMethod
isPOST
, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type:Object
Hash
Associative Array
Param[]
Dictionary<string, string>
NSArray<NSURLQueryItem *>
[NSURLQueryItem]/Array<NSURLQueryItem>
Map<String, String>
- tokenDetailsTokenDetailstoken_details:token_details
- An authenticated
TokenDetails
object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such asauthUrl
AuthUrl
:auth_url
auth_url
orauthCallback
AuthCallbackauth_callback
:auth_callback
. Use this option if you wish to use Token authentication. Read more about Token authentication
Type:TokenDetails
- tlsTls:tls
-
true A boolean value, indicating whether or not a TLS (“SSL”) secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. Find out more about TLS
Type:Boolean
- clientIdClientIdclient_id:client_id
- A client ID, used for identifying this client when publishing messages or for presence purposes. The
clientId
client_id
ClientId
can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that aclientId
client_id
ClientId
may also be implicit in a token used to instantiate the library; an error will be raised if aclientId
client_id
specified here conflicts with theclientId
client_id
ClientId
implicit in the token. Find out more about client identities
Type:String
- useTokenAuthUseTokenAuthuse_token_auth:use_token_auth
-
false When true, forces Token authentication to be used by the library. Please note that if a
client_id
clientId
is not specified in theClientOptions
orTokenParams
, then the Ably Token issued will be anonymous.
Type:Boolean
- environmentEnvironment:environment
-
nullNullNonenil Enables enterprise customers to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our platform customization guide for more details.
Type:String
- idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing
-
false When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
Type:Boolean
- fallbackHostsFallbackHostsfallback_hosts:fallback_hosts
-
[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]
An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host.
When a custom environment is specified, the fallback host functionality is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
Type:String []
- transportParamsTransportParamstransport_params:transport_params
- Optional. Can be used to pass in arbitrary connection parameters, such as
heartbeatInterval
andremainPresentFor
.
Type:Object
Dict
Hash
Associative Array
Param []
Dictionary<string, string>
Map<String, String>
- log
- Parameters to control the log output of the library. The supplied value must be an object that may contain one or both of the following entries:
-
level
: a number controlling the verbosity of the output. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (abbreviated debug output), and 4 (full debug output). -
handler
: a function to handle each line of log output. Ifhandler
is not specified,console.log
is used.
Note that the log level and log handler have global scope in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type:Object
-
- transports
- An optional array of transports to use, in descending order of preference. In the browser environment the available transports are:
web_socket
,xhr
,jsonp
.The transports available in the Node.js client library are:web_socket
,xhr
,comet
.
Type:String []
- logLevel
-
5 A number controlling the verbosity of the output from 2 (maximum, verbose) to 6 (errors only). A special value of 99 will silence all logging. Note that the
logLevel
is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See the logging section of the java library README for more details.
Type:Integer
- logHandler
-
System.out PrintStream
ALogHandler
interface can be specified to handle each line of log output. IflogHandler
is not specified,System.out
is used. Note that thelogHandler
is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently. See the logging section of the java library README for more details.
Type: PrintStream
To set the log level and custom logger sink when using the .NET library, configure the static IO.Ably.Logger
class or specify the ClientOptions
:
- LogLevel
-
Error
This is an enum controlling the verbosity of the output fromDebug
(maximum) toError
(errors only). A special value ofNone
will silence all logging. Note that theLogLevel
is a static variable in the library and will thus not act independently between library instances.
Type:Enum
- LoggerSink
-
IO.Ably.DefaultLoggerSink
The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure.
- LogLevel
-
LogError
This is an enum controlling the verbosity of the output fromLogDebug
(maximum) toLogError
(errors only). A special value ofLogNone
will silence all logging. Note that theLogLevel
is a static variable in the library and will thus not act independently between library instances.
Type:Enum
- logLevel
-
ARTLogLevelWarn An enum controlling the verbosity of the output from
ARTLogLevelVerbose
toARTLogLevelNone
. A special value of 99 will silence all logging.
Type:ARTLogLevel
- logHandler
- A
ARTLog
object can be specified to handle each line of log output. IflogHandler
is not specified, a defaultARTLog
instance is used.
Type:ARTLog *
- :log_level
-
:error
Log level for the standard Logger that outputs toSTDOUT
. Can be set to:fatal
,:error
,:warn
,:info
,:debug
or:none
. Alternatively aLogger
severity constant can be specified.
Type:Symbol
,Logger::SEVERITY
- :logger
-
STDOUT Logger
A RubyLogger
compatible object to handle each line of log output. Iflogger
is not specified,STDOUT
is used.
Type: Ruby @Logger
- logLevel
-
Log::WARNING
A number controlling the verbosity of the output from 1 (minimum, errors only) to 4 (most verbose);
Type:Integer
- logHandler
-
console.log
A function to handle each line of log output. If handler is not specified,console.log
is used. Note that the log level and log handler have global scope in the library and will therefore not act independently between library instances when multiple library instances exist concurrently.
Type:Function
- useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol
-
false If set to true, will enable the binary protocol (MessagePack) if it is supported. It’s disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON)true If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supportedNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the benefits of binary encoding
Type:Boolean
- logExceptionReportingUrl
- Defaults to a string value for an Ably error reporting Data Source Name.
Type:String
- queryTimeQueryTime:query_timequery_time
-
false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
Type:Boolean
- defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams
- When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably
TokenRequests
Type:TokenParams
ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions Arrayio.ably.lib.types.ChannelOptionsIO.Ably.ChannelOptions
Channel options are used for setting channel parameters and configuring encryption.
ChannelOptions
, a plain JavaScript object, may optionally be specified when instancing a Channel
, and this may be used to specify channel-specific options. The following attributes can be defined on the object:
ChannelOptions
, a Hash object, may optionally be specified when instancing a Channel
, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:
ChannelOptions
, an Associative Array, may optionally be specified when instancing a Channel
, and this may be used to specify channel-specific options. The following named keys and values can be added to the Associated Array:
ART
io.ably.lib.types.
ChannelOptions
may optionally be specified when instancing a Channel
, and this may be used to specify channel-specific options.
IO.Ably.ChannelOptions
may optionally be specified when instancing a Channel
, and this may be used to specify channel-specific options.
PropertiesMembersAttributes
- :cipherCipherParamscipher
- Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type:CipherParams
or an options objectaParam[]
listan options hashan Associative Array containing at a minimum akey
- paramsParams
- Optional parameters which specify behaviour of the channel.
Type:Map<String, String>
JSON Object
- cipherCipherParams
- Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type:CipherParams
or an options objectaParam[]
listan options hashan Associative Array containing at a minimum akey
Static methods
withCipherKey
static ChannelOptions.withCipherKey(Byte[] or String key)
A helper method to generate a ChannelOptions
for the simple case where you only specify a key.
Parameters
- key
- A binary
Byte[]
array or a base64-encodedString
.
Returns
On success, the method returns a complete ChannelOptions
object. Failure will raise an AblyException
.
CipherParamsARTCipherParamsCipherParams HashCipherParams Arrayio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams
A CipherParams
contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128.
Individual client libraries may support either instancing a CipherParams
directly, using Crypto.getDefaultParams()
Crypto.GetDefaultParams()
Crypto.get_default_params()
, or generating one automatically when initializing a channel, as in this example.
PropertiesMembersAttributes
- keyKey:key
- A binary (
byte[]
ArrayBuffer
orWordArray
Buffer
byte arrayNSData
) or base64-encodedNS
String
containing the secret key used for encryption and decryption
- algorithm:algorithmAlgorithm
-
AES The name of the algorithm in the default system provider, or the lower-cased version of it; eg “aes” or “AES”
Type:String
- key_length:key_lengthkeyLengthKeyLength
-
256 The key length in bits of the cipher, either 128 or 256
Type:Integer
- mode:modeMode
-
CBC The cipher mode
Type:String
CipherMode
- keySpec
- A
KeySpec
for the cipher key
Type:SecretKeySpec
IO.Ably.StatsRequestParams
StatsRequestParams
is a type that encapsulates the parameters for a stats query. For example usage see Realtime#stats
Realtime#Stats
.
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 - Unit
-
Minute
Minute
,Hour
,Day
Month
. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
Type:StatsIntervalGranularity
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>
TokenParams ObjectARTTokenParamsTokenParams HashTokenParams Arrayio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams
TokenParams
is a plain JavaScript object and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following attributes can be defined on the object:
TokenParams
is a Hash object and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following key symbol values can be added to the Hash:
TokenParams
is a Dict and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following keys-value pairs can be added to the Dict:
TokenParams
is an Associative Array and is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token. The following named keys and values can be added to the Associative Array:
TokenParams
is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token.
ARTTokenParams
is used in the parameters of token authentication requests, corresponding to the desired attributes of the Ably Token.
PropertiesMembersAttributesAttributes
- capabilityCapability:capability
-
JSON stringified capability of the Ably Token. If the Ably Token request is successful, the capability of the returned Ably Token will be the intersection of this capability with the capability of the issuing key. Find our more about how to use capabilities to manage access privileges for clients. Type:
String
Capability
- clientIdClientIdclient_id:client_id
- A client ID, used for identifying this client when publishing messages or for presence purposes. The
clientId
client_id
ClientId
can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that aclientId
client_id
ClientId
may also be implicit in a token used to instantiate the library; an error will be raised if aclientId
client_id
ClientId
specified here conflicts with theclientId
client_id
ClientId
implicit in the token. Find out more about client identities
Type:String
- nonceNonce:nonce
- An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected.
Type:String
- timestampTimestamp:timestamp
-
The timestamp (in milliseconds since the epoch)The timestamp of this request.
timestamp
, in conjunction with thenonce
, is used to prevent requests for Ably Token from being replayed.
Type:Integer
Long Integer
Time
NSDate
DateTimeOffset
DateTime
- ttlTtl:ttl
-
1 hour Requested time to live for the Ably Token being created in millisecondsin secondsas a
NSTimeInterval
as aTimeSpan
. When omitted, the Ably REST API default of 60 minutes is applied by Ably
Type:Integer
(milliseconds)Integer
(seconds)NSTimeInterval
Long Integer
TimeSpan