diff --git a/content/api/realtime-sdk.textile b/content/api/realtime-sdk.textile
index 49d6acf710..49ca6f0dd5 100644
--- a/content/api/realtime-sdk.textile
+++ b/content/api/realtime-sdk.textile
@@ -3,7 +3,6 @@ title: Constructor
meta_description: "Realtime Client Library SDK API reference section for the constructor object."
meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, constructor, instantiate"
section: api
-index: 1
languages:
- javascript
- nodejs
@@ -13,37 +12,12 @@ languages:
- objc
- csharp
- flutter
-jump_to:
- Constructor object:
- - constructor
- Attributes:
- - auth
- - channels
- - client_id#client-id
- - connection
- - rest_client#rest-client
- Methods:
- - connect
- - close
- - stats
- - time
- - request
- Related Types:
- - ClientOptions#client-options
- - stats#stats-type
- - HttpPaginatedResponse#http-paginated-response
redirect_from:
- /docs/api/versions/v1.1/realtime-sdk
- /docs/api/versions/v1.0/realtime-sdk
- /docs/api/versions/v0.8/realtime-sdk
---
-blang[javascript,nodejs].
-
-
-
h2(#constructor). Constructor
The Ably Realtime library constructor is overloaded allowing it to be instantiated using a "@ClientOptions@":#client-options object, or more simply using a string containing an "API key":/docs/auth/basic or "Token":/docs/auth/token, as shown below:
@@ -148,7 +122,7 @@ h6(#connect).
csharp: Connect
bq(definition).
- default: connect()
+ default: connect(): void
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable connect -> yields "@Connection@":/docs/api/realtime-sdk/connection
java: void connect()
csharp: void Connect()
@@ -169,7 +143,7 @@ h6(#close).
csharp: Close
bq(definition).
- default: close()
+ default: close(): void
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable close -> yields "@Connection@":/docs/api/realtime-sdk/connection
java: void close()
csharp: void Close()
@@ -190,13 +164,14 @@ h6(#stats).
csharp: Stats
bq(definition).
- default: stats(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats> results))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable stats(Hash options) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats>
- java: "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats> stats("Param":#param[] options)
- swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":/docs/api/realtime-sdk/types#stats>?, ARTErrorInfo?) -> Void) throws
- csharp: Task<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#stats>> StatsAsync(StatsRequestParams query)
+ default: stats(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type> results))
+ jsall: stats(Object params?): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable stats(Hash options) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>
+ java: "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type> stats("Param":#param[] options)
+ swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":#stats-type>?, ARTErrorInfo?) -> Void) throws
+ csharp: Task<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>> StatsAsync(StatsRequestParams query)
-This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result is returned, containing an array of "Stats":#stats for the first page of results. "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
+This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result is returned, containing an array of "Stats":#stats-type for the first page of results. "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
See "statistics":/docs/metadata-stats/stats for more information.
@@ -208,14 +183,20 @@ h6(#time).
bq(definition).
default: time(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, Number time))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable time -> yields Time
- java: long time()
- csharp: Task TimeAsync()
+ jsall: time(): Promise
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable time -> yields Time
+ java: long time()
+ csharp: Task TimeAsync()
objc,swift: time(callback: (NSDate?, NSError?) -> Void)
Obtains the time from the Ably service as a @Time@ objecta @DateTimeOffset@ objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably "TokenRequests":/docs/api/realtime-sdk/authentication#token-request with a more accurate timestamp should use the @queryTime@ "clientOptions":#client-options instead of this method).
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
+blang[objc,swift].
h4. Callback result
On success, @time@ is a number containing the number of milliseconds since the epoch.
@@ -238,7 +219,6 @@ blang[csharp].
Failure to retrieve the Ably server time will raise an "@AblyException@":#ably-exception.
-
blang[ruby].
h4. Returns
@@ -250,6 +230,45 @@ blang[ruby].
<%= partial partial_version('rest/_request') %>
+blang[javascript].
+ h6(#batchPublish). batchPublish
+
+ There are two overloaded versions of this method:
+
+ bq(definition#batchPublish).
+ default: batchPublish("BatchPublishSpec":#batch-publish-spec spec): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>>
+
+ Publishes a "@BatchPublishSpec@":#batch-publish-spec object to one or more channels, up to a maximum of 100 channels.
+
+ bq(definition#batchPublishArray).
+ default: batchPublish("BatchPublishSpec[]":#batch-publish-spec specs): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>[]>
+
+ Publishes one or more "@BatchPublishSpec@":#batch-publish-spec objects to one or more channels, up to a maximum of 100 channels.
+
+ h4. Parameters
+
+ - spec := an object describing the messages to be batch published and to which channels __Type: "@BatchPublishSpec@":#batch-publish-spec
+ - specs := an array of objects describing the messages to be batch published and to which channels __Type: "@BatchPublishSpec@[]":#batch-publish-spec
+
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object, or an array of "@BatchResult@":#batch-result objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as "@BatchPublishSuccessResult@":#batch-publish-success-result objects, whilst failures are "@BatchPublishFailureResult@":#batch-publish-failure-result objects. If an array of "@BatchResult@":#batch-result objects are returned, they are in the same order as the provided "@BatchPublishSpec@":#batch-publish-spec. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
+ h6(#batchPresence). batchPresence
+
+ bq(definition#batchPresence).
+ default: batchPresence(String[] channels): Promise<"BatchResult":#batch-result<"BatchPresenceSuccessResult":#batch-presence-success-result | "BatchPresenceFailureResult":#batch-presence-failure-result>[]>
+
+ Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the "@clientId@":#client-options of members and their current "@PresenceAction@":/docs/api/realtime-sdk/presence#presence-action.
+
+ h4. Parameters
+
+ - channels := an array of one or more channel names, up to a maximum of 100 channels __Type: @String[]@__
+
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as "@BatchPresenceSuccessResult@":#batch-presence-success-result objects, whilst failures are "@BatchPresenceFailureResult@":#batch-presence-failure-result objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
h2(#related-types). Related types
h3(#client-options).
@@ -274,6 +293,8 @@ h3(#stats-type).
h3(#stats-granularity).
objc,swift: ARTStatsGranularity
+ jsall: StatsIntervalGranularity
+ csharp: StatsIntervalGranularity
<%= partial partial_version('types/_stats_granularity') %>
@@ -287,3 +308,35 @@ h3(#param).
blang[java].
<%= partial partial_version('types/_param'), indent: 2, skip_first_indent: true %>
+
+blang[jsall].
+
+ h3(#batch-publish-spec).
+ jsall: BatchPublishSpec
+
+ <%= partial partial_version('types/_batch_publish_spec') %>
+
+ h3(#batch-result).
+ jsall: BatchResult
+
+ <%= partial partial_version('types/_batch_result') %>
+
+ h3(#batch-publish-success-result).
+ jsall: BatchPublishSuccessResult
+
+ <%= partial partial_version('types/_batch_publish_success_result') %>
+
+ h3(#batch-publish-failure-result).
+ jsall: BatchPublishFailureResult
+
+ <%= partial partial_version('types/_batch_publish_failure_result') %>
+
+ h3(#batch-presence-success-result).
+ jsall: BatchPresenceSuccessResult
+
+ <%= partial partial_version('types/_batch_presence_success_result') %>
+
+ h3(#batch-presence-failure-result).
+ jsall: BatchPresenceFailureResult
+
+ <%= partial partial_version('types/_batch_presence_failure_result') %>
diff --git a/content/api/realtime-sdk/authentication.textile b/content/api/realtime-sdk/authentication.textile
index f9b5be2473..7f7bdddac1 100644
--- a/content/api/realtime-sdk/authentication.textile
+++ b/content/api/realtime-sdk/authentication.textile
@@ -22,6 +22,7 @@ jump_to:
- authorize
- createTokenRequest#create-token-request
- requestToken#request-token
+ - revokeTokens#revoke-tokens
Types:
- Related Types#related-types
redirect_from:
@@ -30,12 +31,6 @@ redirect_from:
- /docs/api/versions/v0.8/realtime-sdk/authentication
---
-blang[javascript,nodejs].
-
-
-
This is the Authentication API Reference.
h2(#tokens). Tokens
@@ -80,6 +75,7 @@ h6(#authorize).
bq(definition).
default: authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "TokenDetails":#token-details tokenDetails))
+ jsall: authorize("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenDetails":#token-details>
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable authorize("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options) -> yields "TokenDetails":#token-details
java: "TokenDetails":#token-details authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
csharp: "Task:#token-details AuthorizeAsync("TokenParams:#token-params?, "AuthOptions":#auth-options?)
@@ -95,7 +91,6 @@ h4. Parameters
- auth_optionsauthOptions := an optional object containing the "authentication options":#auth-optionsan optional "@TokenParams@":#auth-options object containing the authentication optionsan optional set of key value pairs containing the "authentication options":#auth-options for the authorization request __Type: "@AuthOptions@":#auth-options__
--
callback
:= is a function of the form: @function(err, tokenDetails)@
-
&block
:= yields a "@TokenDetails@":#token-details object
-
callback
:= called with a "@ARTTokenDetails@":#token-details object or an error
@@ -109,13 +104,13 @@ blang[objc,swift].
The @authorize@ callback can therefore be used to only trigger an event once the new token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.
blang[jsall].
- h4. Callback result
+ h4. Returns
- On success, the callback will be called with the new "@TokenDetails@":#token-details only once the realtime connection has been successfully upgraded to use the new token.
+ Returns a promise.
- On failure to obtain a token or upgrade the token, the connection will move to the @SUSPENDED@ or @FAILED@ state, and the callback will be called with @err@ containing an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+ On success, the promise is fulfilled with the new "@TokenDetails@":#token-details once the realtime connection has been successfully upgraded to use the new token.
- The @authorize@ callback can be used to trigger an event once the new token has taken effect. This can be useful if, for example, you want to do attach to a new channel following a new channel capability being applied to the connection.
+ On failure to obtain a token or upgrade the token, the connection will move to the @SUSPENDED@ or @FAILED@ state, and the promise will be rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
blang[java].
h4. Returns
@@ -150,14 +145,12 @@ blang[ruby].
h4. Example
-bc[jsall]. client.auth.authorize({ clientId: 'bob' }, function(err, tokenDetails) {
- if(err) {
- console.log('An error occurred; err = ' + err.toString());
- } else {
- console.log('Success! Realtime connection upgraded with new token: ' +
- tokenDetails.token);
- }
-});
+bc[jsall]. try {
+ const tokenDetails = await client.auth.authorize({ clientId: 'bob' });
+ console.log('Success; token: ' + tokenDetails.token);
+} catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+}
bc[java]. try {
TokenParams tokenParams = new TokenParams();
@@ -205,6 +198,7 @@ h6(#create-token-request).
bq(definition).
default: createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "TokenRequest":#token-request tokenRequest))
+ jsall: createTokenRequest("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenRequest":#token-request>
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable create_token_request("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options) -> yields "TokenRequest":#token-request
java: "TokenRequest":#token-request createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
csharp: Task<"TokenRequest":#token-request> CreateTokenRequestAsync("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
@@ -222,16 +216,17 @@ h4. Parameters
- auth_optionsauthOptions := an optional object containing the "authentication options":#auth-optionsan optional "@TokenParams@":#token-params object containing the authentication optionsan optional set of key value pairs containing the "authentication options":#auth-optionsan optional "@ARTTokenParams@":#token-params containing the "authentication options":#auth-options __Type: "@AuthOptions@":#auth-options__
--
callback
:= is a function of the form: @function(err, tokenRequest)@
-
&block
:= yields a "@TokenRequest@":#token-request object
-
callback
:= called with a "@ARTTokenRequest@":#token-request object or an error
blang[jsall].
- h4. Callback result
+ h4. Returns
- On success, @tokenRequest@ contains a "@TokenRequest@":#token-request JSON object.
+ Returns a promise.
- On failure to issue a "@TokenRequest@":#token-request, @err@ contains an "@ErrorInfo@":#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+ On success, the promise is fulfilled with the new "@TokenRequest@":#token-request JSON object
+
+ On failure to issue a "@TokenRequest@":#token-request, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
blang[java].
h4. Returns
@@ -260,13 +255,12 @@ blang[ruby].
h4. Example
-bc[jsall]. client.auth.createTokenRequest({ clientId: 'bob' }, function(err, tokenRequest) {
- if(err) {
- console.log('An error occurred; err = ' + err.message);
- } else {
- console.log('Success; token request = ' + tokenRequest);
- }
-});
+bc[jsall]. try {
+ const tokenRequest = await client.auth.createTokenRequest({ clientId: 'bob' });
+ console.log('Success; token request = ' + tokenRequest);
+} catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+}
bc[java]. try {
TokenParams tokenParams = new TokenParams();
@@ -314,6 +308,7 @@ h6(#request-token).
bq(definition).
default: requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "TokenDetails":#token-details tokenDetails))
+ jsall: requestToken("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenDetails":#token-details>
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable request_token("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options) -> yields "TokenDetails":#token-details
java: "TokenDetails":#token-details requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
csharp: async Task<"TokenDetails":#token-details> RequestTokenAsync("TokenParams":#token-params? tokenParams, "AuthOptions":#auth-options? options)
@@ -331,11 +326,19 @@ h4. Parameters
- auth_optionsauthOptions := an optional object containing the "authentication options":#auth-optionsan optional "@TokenParams@":#auth-options object containing the authentication optionsan optional set of key value pairs containing the "authentication options":#auth-options for the requested "Ably Token":#token-details __Type: "@AuthOptions@":#auth-options__
--
callback
:= is a function of the form: @function(err, tokenDetails)@
-
&block
:= yields a "@TokenDetails@":#token-details object
-
callback
:= called with a "@ARTTokenDetails@":#token-details object or an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise.
+
+ On success, the promise is fulfilled with a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string.
+
+ On failure to obtain an "Ably Token":#token-details, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+
+blang[objc,swift].
h4. Callback result
On success, @tokenDetails@ contains a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string.
@@ -369,13 +372,12 @@ blang[ruby].
h4. Example
-bc[jsall]. client.auth.requestToken({ clientId: 'bob'}, function(err, tokenDetails){
- if(err) {
- console.log('An error occurred; err = ' + err.message);
- } else {
- console.log('Success; token = ' + tokenDetails.token);
- }
-});
+bc[jsall]. try {
+ const tokenDetails = await client.auth.requestToken({ clientId: 'bob'});
+ console.log('Success; token = ' + tokenDetails.token);
+} catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+}
bc[ruby]. client.auth.request_token(client_id: 'bob') do |token_details|
puts "Success; token = #{token_details.token}"
@@ -416,6 +418,41 @@ client.auth.requestToken(tokenParams, withOptions: : nil) { tokenDetails, error
print("Success; token = \(tokenDetails.token)")
}
+blang[jsall].
+
+ h6(#revoke-tokens).
+ jsall: revokeTokens
+
+ bq(definition).
+ jsall: revokeTokens("TokenRevocationTargetSpecifier[]":#token-revocation-target-specifier specifiers, "TokenRevocationOptions":#token-revocation-options options?): Promise<"BatchResult":#batch-result<"TokenRevocationSuccessResult":#token-revocation-success-result | "TokenRevocationFailureResult":#token-revocation-failure-result>>
+
+ Calls the "@revokeTokens@ REST API endpoint":/docs/api/rest-api#revoke-tokens to revoke tokens specified by the provided array of "TokenRevocationTargetSpecifier":#token-revocation-target-specifier.
+
+ Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the "token revocation docs":/docs/auth/revocation for more information.
+
+ h4. Parameters
+
+ - specifiers := an array of "TokenRevocationTargetSpecifier":#token-revocation-target-specifier objects __Type: "@TokenRevocationTargetSpecifier[]@":#token-revocation-target-specifier__
+
+ - options := an optional set of options which are used to modify the revocation request __Type: "@TokenRevocationOptions@":#token-revocation-options__
+
+ h4. Returns
+
+ Returns a promise.
+
+ On success, the promise is fulfilled with a "BatchResult":#batch-result containing information about the result of the token revocation request for each provided "TokenRevocationTargetSpecifier":#token-revocation-target-specifier.
+
+ On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+
+ h4. Example
+
+ bc[jsall]. try {
+ const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
+ console.log('Revocation successful; revoked tokens: ' + response.results.length);
+ } catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+ }
+
h2(#related-types). Related types
h3(#auth-options).
@@ -495,3 +532,33 @@ The following is an example of creating an Ably JWT:
```
*Note:* At present Ably does not support asymmetric signatures based on a keypair belonging to a third party. If this is something you'd be interested in, please "get in touch":https://ably.com/contact.
+
+h3(#batch-result).
+ jsall: BatchResult
+
+blang[jsall].
+ <%= partial partial_version('types/_batch_result') %>
+
+h3(#token-revocation-target-specifier).
+ jsall: TokenRevocationTargetSpecifier
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_target_specifier') %>
+
+h3(#token-revocation-options).
+ jsall: TokenRevocationOptions
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_options') %>
+
+h3(#token-revocation-success-result).
+ jsall: TokenRevocationSuccessResult
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_success_result') %>
+
+h3(#token-revocation-failure-result).
+ jsall: TokenRevocationFailureResult
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_failure_result') %>
diff --git a/content/api/realtime-sdk/channel-metadata.textile b/content/api/realtime-sdk/channel-metadata.textile
index e70ad91d98..a730e84107 100644
--- a/content/api/realtime-sdk/channel-metadata.textile
+++ b/content/api/realtime-sdk/channel-metadata.textile
@@ -3,23 +3,11 @@ title: Channel Metadata
meta_description: "Realtime Client Library SDK API reference section for channel metadata."
meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, metadata, channel metadata, occupancy"
section: api
-index: 25
-jump_to:
- Channel API Types:
- - ChannelDetails#channel-details
- - ChannelStatus#channel-status
- - Occupancy#occupancy
redirect_from:
- /docs/api/versions/v1.1/realtime-sdk/channel-metadata
- /docs/api/versions/v1.0/realtime-sdk/channel-metadata
---
-blang[javascript,nodejs].
-
-
-
h2(#types). Types
The payload of metadata events for channels is the "@ChannelDetails@":#channel-details type which contains the @channelId@ and other static information about the channel, plus a @status@ containing a "@ChannelStatus@":#channel-status instance which contains information about the current state of the channel.
diff --git a/content/api/realtime-sdk/channels.textile b/content/api/realtime-sdk/channels.textile
index 2174fb0de7..e60eb851da 100644
--- a/content/api/realtime-sdk/channels.textile
+++ b/content/api/realtime-sdk/channels.textile
@@ -3,7 +3,6 @@ title: Channels
meta_description: "Realtime Client Library SDK API reference section for the channels and channel objects."
meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, channel, channels, publish, subscribe"
section: api
-index: 15
languages:
- javascript
- nodejs
@@ -13,36 +12,12 @@ languages:
- objc
- csharp
- flutter
-jump_to:
- Channel API properties:
- - state
- - errorReason#error-reason
- - name
- - presence
- Channel API methods:
- - publish
- - subscribe
- - unsubscribe
- - history
- - attach
- - detach
- - on#on
- - once
- - off#off
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/realtime-sdk/channels
- /docs/api/versions/v1.0/realtime-sdk/channels
- /docs/api/versions/v0.8/realtime-sdk/channels
---
-blang[javascript,nodejs].
-
-
-
h2(#channels-object).
default: Channels
@@ -56,11 +31,23 @@ h6(#get).
bq(definition).
default: "Channel":#properties get(String channelName, "ChannelOptions":#channel-options channelOptions)
+ jsall: "Channel":#properties get(String name, "ChannelOptions":#channel-options channelOptions?)
csharp: "Channel":#properties Get(String channelName, "ChannelOptions":#channel-options channelOptions)
objc,swift: "ARTRealtimeChannel":#properties get(String channelName, "ARTChannelOptions":#channel-options channelOptions);
Creates a new "Channel":#properties object if none for the channel exists, or returns the existing channel object.
+blang[jsall].
+ h6(#get-derived).
+ jsall: getDerived
+
+ bq(definition).
+ jsall: "Channel":#properties get(String name, "DeriveOptions":#derive-options deriveOptions, "ChannelOptions":#channel-options channelOptions?)
+
+ Creates a new "Channel":#properties object if none for the channel exists, or returns the existing channel object. The Channel object is created or returned with the specified @DeriveOptions@ and optional @ChannelOptions@.
+
+ Derived channels enables you to subscribe to a filtered subset of messages on a channel. See "subscription filters":/channels#subscription-filters for more information.
+
h6(#release).
default: release
csharp: Release
@@ -124,33 +111,70 @@ h6(#objects).
Provides access to the "Objects":/docs/liveobjects object for this channel which can be used to read, modify and subscribe to LiveObjects on a channel.
+blang[jsall].
+
+ h6(#params).
+ jsall: params
+
+ The current "channel parameters":/docs/channels/options#params configured for this channel.
+
+ h6(#modes).
+ jsall: modes
+
+ The current "channel modes":/docs/channels/options#modes configured for this channel.
+
h3. Methods
h6(#publish).
default: publish
csharp: Publish
-There are two overloaded versions of this method:
+blang[default].
+ There are two overloaded versions of this method:
+
+blang[jsall].
+ There are three overloaded versions of this method:
bq(definition#publish-data).
default: publish(String name, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: publish(String name, Object data): Promise
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable publish(String name, Object data) -> yields
java: void publish(String name, Object data, "CompletionListener":#completion-listener listener)
csharp: void Publish(string name, object data, Action callback = null, string clientId = null)
objc,swift: publish(name: String?, data: AnyObject?, callback: (("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?) -> Void)?)
flutter: Future publish(name: String name, data: Object data, message: "Message":#message message)
-Publish a single message on this channel based on a given event name and payload. A callbacklistener may optionally be passed in to this call to be notified of success or failure of the operation. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels/states#attach, so long as "transient publishing":/docs/pub-sub/advanced#transient-publish is available in the library. Otherwise, the client will implicitly attach.
+blang[default].
+
+ Publish a single message on this channel based on a given event name and payload. A callbacklistener may optionally be passed in to this call to be notified of success or failure of the operation. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels/states#attach, so long as "transient publishing":/docs/pub-sub/advanced#transient-publish is available in the library. Otherwise, the client will implicitly attach.
+
+blang[jsall].
+
+ Publish a single message on this channel based on a given event name and payload. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels/states#attach, so long as "transient publishing":/docs/pub-sub/advanced#transient-publish is available in the library. Otherwise, the client will implicitly attach.
+
+blang[jsall].
+
+ bq(definition#publish-msg).
+ jsall: publish(Object message): Promise
+
+ Publish a single message on this channel. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels/states#attach, so long as "transient publishing":/docs/pub-sub/advanced#transient-publish is available in the library. Otherwise, the client will implicitly attach.
bq(definition#publish-msg-array).
default: publish(Object[] messages, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: publish(Object[] messages): Promise
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable publish(Message[] messages) -> yields
java: void publish(Message[] messages, "CompletionListener":#completion-listener listener)
csharp: void Publish(IEnumerable<"Message":#message> messages, Action callback = null)
objc,swift: publish(messages: [ "ARTMessage":#message ], callback: (("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?) -> Void)?)
flutter: Future publish(messages: List<"Message":#message> messages)
-Publish several messages on this channel. A callbacklistenerblock may optionally be passed in to this call to be notified of success or failure of the operation. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels#transient-publish. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @publish@ will implicitly attach the channel.
+blang[default].
+
+ Publish several messages on this channel. A callbacklistenerblock may optionally be passed in to this call to be notified of success or failure of the operation. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels#transient-publish. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @publish@ will implicitly attach the channel.
+
+blang[jsall].
+
+ Publish several messages on this channel. When publish is called with this client library, it "won't attempt to implicitly attach to the channel":/docs/channels#transient-publish. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @publish@ will implicitly attach the channel.
The entire @messages@ array is published atomically. This means that:
@@ -174,40 +198,44 @@ h4. Parameters
- messages := An array of message objects to publish __Type: "@Message []@":#message__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
callback
:= is an action of the form @Action@ which is called upon completion
-
&block
:= yields upon successfully publishing the message
-
callback
:= called upon publishing the message, or with an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
- On successful publish of the message, @err@ is null. On failure to publish the message, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
+ On successful publish of the message, @err@ is null. On failure to publish the message, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object describing the failure reason.
blang[csharp].
h4. Callback result
- On successful publish of the message, @error@ is null. On failure to publish the message, @error@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
+ On successful publish of the message, @error@ is null. On failure to publish the message, @error@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object describing the failure reason.
blang[java].
h4. Listener result
- On successful publish of the message, the @onSuccess@ method of the "CompletionListener":#completion-listener is called. On failure to publish the message, the @onError@ method is called with an "@ErrorInfo@":#error-info argument describing the failure reason.
+ On successful publish of the message, the @onSuccess@ method of the "CompletionListener":#completion-listener is called. On failure to publish the message, the @onError@ method is called with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info argument describing the failure reason.
blang[ruby].
h4. Returns
A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the method.
- On successful publish of the message, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are executed. On failure to publish the message, the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable are called with an "@ErrorInfo@":#error-info argument describing the failure reason.
+ On successful publish of the message, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are executed. On failure to publish the message, the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable are called with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info argument describing the failure reason.
blang[flutter].
h4. Returns
@Future@
- On successful publish of the message, no exception will be thrown. On failure to publish the message, an @AblyException@ will be thrown with an `"@errorInfo@":#error-info` property describing the failure reason.
+ On successful publish of the message, no exception will be thrown. On failure to publish the message, an @AblyException@ will be thrown with an `"@errorInfo@":/docs/api/realtime-sdk/types#error-info` property describing the failure reason.
h6(#subscribe).
default: subscribe
@@ -217,6 +245,7 @@ There are overloaded versions of this method:
bq(definition#subscribe-listener).
default: subscribe(listener("Message":#message))
+ jsall: subscribe(listener): Promise
java: void subscribe("MessageListener":#message-listener listener)
csharp: void Subscribe(Action<"Message":#message> handler)
ruby: subscribe → yields "Message":#message
@@ -227,19 +256,21 @@ Subscribe to messages on this channel. The caller supplies
bq(definition#subscribe-event).
default: subscribe(String name, listener("Message":#message))
+ jsall: subscribe(String event, listener?): Promise
java: void subscribe(String name, "MessageListener":#message-listener listener)
csharp: void Subscribe(string name, Action<"Message":#message> handler)
ruby: subscribe(String name) → yields "Message":#message
objc,swift: subscribe(name: String, callback: ("ARTMessage":#message) -> Void) -> ARTEventListener?
flutter: StreamSubscription<"ably.Message":#message> subscribe(name: String).listen(("ably.Message":#message) -> void)
-Subscribe to messages with a given event @name@ on this channel. The caller supplies a listener functiona lambda expressionan implementation of the "MessageListener":#message-listener interfacea block, which is called each time one or more matching messages arrives on the channel.
+Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the "MessageListener":#message-listener interfacea block, which is called each time one or more matching messages arrives on the channel.
bq(definition#subscribe-event-array).
default: subscribe(String[] names, listener("Message":#message))
+ jsall: subscribe(String[] events, listener?): Promise
java: void subscribe(String[] names, "MessageListener":#message-listener listener)
ruby: subscribe(String *names) → yields "Message":#message
flutter: StreamSubscription<"ably.Message":#message> subscribe(names: List).listen(("ably.Message":#message) -> void)
@@ -247,26 +278,44 @@ bq(definition#subscribe-event-array).
Subscribe a single listener to messages on this channel for multiple event @name@ values.
+
+
+
+bq(definition#subscribe-filtered).
+ jsall: subscribe(filter, listener?): Promise
+
+Registers a listener for messages on this channel that match the supplied filter. The filter is used to provide server-side filtering of messages as part of "filtered subscriptions":/docs/pub-sub/advanced#subscription-filters.
+
+
h4. Parameters
-- name := The event name to subscribe to __Type: @String@__
+- nameevent := The event name to subscribe to __Type: @String@__
-
-
+
+
- names := An argument array of event names to subscribe to __Type: @String[]@ @*argument@__
+-
events
:= An array of event names to subscribe to __Type: @String[]@__
+
-
listener
:= is a function of the form @function(message)@ to be called for each message
-
"MessageListener":#message-listener listener
:= Message listener to be notified for matching messages
-
&block
:= yields each matching message when received on the channel
-
callback
:= called with each matching "@message@":#message when received on the channel
-
handler
:= called with each matching "@message@":#message when received on the channel
+-
filter
:= a filter object that is used to provide server-side filtering of messages as part of "filtered subscriptions":/docs/pub-sub/advanced#subscription-filters __Type: @Object@__
+
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On successful channel attachment, the promise is fulfilled with a "ChannelStateChange":#channel-state-change object. If the channel was already attached, then the promised will resolve with @null@. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
h4. Considerations
* If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @subscribe@ will implicitly attach the channel. However, regardless of the implicit attach outcome, the listenerblockhandler will still be registered
-* Calling subscribe with an event name is a convenient way to subscribe only to messages matching that event name. But this is purely a clientside filter, for convenience. It has no effect on what messages are actually sent by the server to the client. All clients attached to a given channel receive every message sent on that channel (that their capabilities allow them to receive); the channel is the unit of distribution.
+* Calling subscribe with an event name is a convenient way to subscribe only to messages matching that event name. But this is purely a client-side filter, for convenience. It has no effect on what messages are actually sent by the server to the client. All clients attached to a given channel receive every message sent on that channel (that their capabilities allow them to receive); the channel is the unit of distribution. To filter messages server-side, you need to use "filtered subscriptions":/docs/pub-sub/advanced#subscription-filters and provide a @filter@ when calling @subscribe()@.
* If @subscribe@ is called more than once with the same listenerblockhandler, then duplicates will be registered. For example, if you @subscribe@ twice with the same listenerblockhandler and a message is later received, the same listenerblockhandler will be invoked twice
* The registered listenerblockhandler remains active on the channel regardless of the current channel state. For example, if you call @subscribe@ when a channel is @attached@ and it later becomes @detached@ or even @failed@, when the channel is reattached and a message is received, the listenersblockshandlers originally registered will still be invoked. Listeners are only removed when calling "@unsubscribe@":#unsubscribe@streamSubscription.close@ or when a channel is @released@ using the @Realtime.channels.release(name)@@Realtime.Channels.Release(name)@ method
* If an exception is thrown in the subscribe listener and bubbles up to the event emitter, it will be caught and logged at @error@ level, so as not to affect other listeners for the same event
@@ -278,10 +327,11 @@ h6(#unsubscribe).
-There are sixthree overloaded versions of this method:
+There are seventhree overloaded versions of this method:
bq(definition#unsubscribe-event).
default: unsubscribe(String name, listener)
+ jsall: unsubscribe(String event, listener)
java: void unsubscribe(String name, "MessageListener":#message-listener listener)
csharp: bool Unsubscribe(string eventName, Action<"Message":#message> handler)
ruby: unsubscribe(String name, &listener_proc)
@@ -302,18 +352,22 @@ Unsubscribe the given listener (for any/all event names). This removes an earlie
-bq(definition). unsubscribe(String[] names, listener)
+bq(definition). unsubscribe(String[] events, listener)
Unsubscribe the given listener from all event names in the array.
-bq(definition). unsubscribe(String name)
+bq(definition). unsubscribe(String event)
Unsubscribe all listeners for a given event name.
-bq(definition). unsubscribe(String[] names)
+bq(definition). unsubscribe(String[] events)
Unsubscribe all listeners for all event names in the array.
+bq(definition). unsubscribe(filter, listener?)
+
+Unsubscribe all listeners for a given filter.
+
@streamSubscription@ obtained from a subscription can be used to cancel a listener by calling @streamSubscription.cancel@.
@@ -331,8 +385,8 @@ Unsubscribes all listeners to messages on this channel. This removes all earlier
h4. Parameters
-- name := The event name to unsubscribe from __Type: @String@__
--
names
:= An array of event names to unsubscribe from __Type: @String[]@__
+- nameevent := The event name to unsubscribe from __Type: @String@__
+-
events
:= An array of event names to unsubscribe from __Type: @String[]@__
-
listener
:= is the callback listener function that was previously subscribed
-
:= previously registered listener block
@@ -344,30 +398,35 @@ h6(#history).
csharp: History
bq(definition).
- default: history(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash options) -> yields "PaginatedResult":#paginated-result<"Message":#message>
- java: "PaginatedResult":#paginated-result<"Message":#message> history("Param []":#param options)
- csharp: Task<"PaginatedResult":#paginated-result> HistoryAsync("PaginatedRequestParams":#paginated-request-params dataQuery, bool untilAttach = false)
+ default: history(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"Message":#message>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash options) -> yields "PaginatedResult":#paginated-result<"Message":#message>
+ java: "PaginatedResult":#paginated-result<"Message":#message> history("Param []":#param options)
+ csharp: Task<"PaginatedResult":#paginated-result> HistoryAsync("PaginatedRequestParams":#paginated-request-params dataQuery, bool untilAttach = false)
objc,swift: history(query: ARTRealtimeHistoryQuery?, callback: ("ARTPaginatedResult":#paginated-result<"ARTMessage":#message>?, ARTErrorInfo?) -> Void) throws
Gets a "paginated":#paginated-result set of historical messages for this channel. If the "channel is configured to persist messages to disk":https://faqs.ably.com/how-long-are-messages-stored-for, then message history will "typically be available for 24 - 72 hours":https://faqs.ably.com/how-long-are-messages-stored-for. If not, messages are only retained in memory by the Ably service for two minutes.
h4. Parameters
-- optionsquerydataQuery := an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified in the "message history API documentation":/docs/api/realtime-sdk/history#channel-history __Type: @Object@@ARTRealtimeHistoryQuery@@PaginatedRequestParams@@Hash@"@Param []@":#param__
+- optionsparamsquerydataQuery := an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified in the "message history API documentation":/docs/api/realtime-sdk/history#channel-history __Type: @Object@@ARTRealtimeHistoryQuery@@PaginatedRequestParams@@Hash@"@Param []@":#param__
--
callback
:= is a function of the form: @function(err, resultPage)@
-
&block
:= yields a @PaginatedResult@ object
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTMessage":#message> object or an error
Further details of the supported @options@ params, see "message history API documentation":/docs/api/realtime-sdk/history#channel-history.
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "PaginatedResult":#paginated-result object containing an array of messages. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
- On failure to retrieve message history, @err@ contains an "@ErrorInfo@":#error-info object with the failure reason.
+ On failure to retrieve message history, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason.
blang[java].
h4. Returns
@@ -392,7 +451,24 @@ blang[ruby].
On success, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method yield a "PaginatedResult":#paginated-result that encapsulates an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
- Failure to retrieve the message history will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":#error-info object with the failure reason.
+ Failure to retrieve the message history will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason.
+
+blang[jsall].
+ h6(#setOptions).
+ jsall: setOptions
+
+ bq(definition).
+ jsall: setOptions(options): Promise
+
+ Set the "ChannelOptions":#channel-options for the channel.
+
+ h4. Parameters
+
+ - options := The options to set for the channel __Type: @ChannelOptions@__
+
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
h6(#attach).
default: attach
@@ -400,6 +476,7 @@ h6(#attach).
bq(definition).
default: attach(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: attach(): Promise
java: void attach()
csharp: void Attach(Action callback = null)
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable attach -> yields
@@ -410,19 +487,24 @@ Attach to this channel ensuring the channel is created in the Ably system and al
As a convenience, @attach()@@Attach()@@attach@ will be called implicitly if "@subscribe()@@Subscribe()@@subscribe@":#subscribe for the @Channel@ is called, or "@enter()@@Enter()@@enter@":/docs/api/realtime-sdk/presence#enter or "@subscribe()@@Subscribe()@@subscribe@":/docs/api/realtime-sdk/presence#subscribe is called on the "@Presence@":/docs/presence-occupancy/presence for this @Channel@.
-h4. Parameters
+blang[ruby,csharp,swift,objc].
+ h4. Parameters
+
+ -
&block
:= yields once the channel becomes attached
+ -
callback
:= is a lambda expression of the form @Action@ and is called once the channel attach succeeds or fails
+ -
callback
:= called once the channel becomes attached or if an error occurs
+
+blang[jsall].
+ h4. Returns
--
callback
:= is a function of the form @function(err)@ and is called once the channel attach succeeds or fails
--
&block
:= yields once the channel becomes attached
--
callback
:= is a lambda expression of the form @Action@ and is called once the channel attach succeeds or fails
--
callback
:= called once the channel becomes attached or if an error occurs
+ Returns a promise. On successful attachment, the promise is fulfilled with a "ChannelStateChange":#channel-state-change object. If the channel was already attached, then the promised is fulfilled with @null@. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
blang[ruby].
h4. Returns
A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the attach method.
- On successful attachment, the success callbacks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable are called and any block provided to the method is yielded. Failure to attach will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":#error-info object with the failure reason.
+ On successful attachment, the success callbacks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable are called and any block provided to the method is yielded. Failure to attach will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason.
blang[flutter].
h4. Returns
@@ -437,6 +519,7 @@ h6(#detach).
bq(definition).
default: detach(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: detach(): Promise
java: void detach()
csharp: void Detach(Action callback = null)
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable detach -> yields
@@ -447,19 +530,24 @@ Detach from this channel. Any resulting channel state change will be emitted to
Please note: Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes.
-h4. Parameters
+blang[csharp,ruby,swift,objc].
+ h4. Parameters
+
+ -
callback
:= is a lambda expression in the form @Action@ and is called once the channel detach succeeds or fails
+ -
&block
:= yields once the channel becomes detached
+ -
callback
:= called once the channel becomes detached or if an error occurs
+
+blang[jsall].
+ h4. Returns
--
callback
:= is a function of the form @function(err)@ and is called once the channel detach succeeds or fails
--
callback
:= is a lambda expression in the form @Action@ and is called once the channel detach succeeds or fails
--
&block
:= yields once the channel becomes detached
--
callback
:= called once the channel becomes detached or if an error occurs
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
blang[ruby].
h4. Returns
A "@Deferrable@":/docs/api/realtime-sdk/types#deferrable object is returned from the detach method.
- On successful detachment, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are executed. Failure to detach will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":#error-info object with the failure reason.
+ On successful detachment, the registered success blocks for the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable and any block provided to the method are executed. Failure to detach will trigger the @errback@ callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason.
blang[flutter].
h4. Returns
@@ -531,7 +619,7 @@ h4. Parameters
-
listener
:= listener to be notified for matching event changes __Type: "@ChannelStateListener@":#channel-state-listener__
-
action
:= lambda expression to be notified for matching event changes __Type: "@ChannelStateChange@":#channel-state-listener__
-
&block
:= listener block that is yielded to for matching event changes
--
call
:= called possibly with an "@ErrorInfo@":#error-info
+-
call
:= called possibly with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info
h6(#once).
default: once
@@ -573,7 +661,7 @@ h4. Parameters
-
listener
:= listener to be notified for a single occurrence of a matching event change __Type: "@ChannelStateListener@":#channel-state-listener__
-
&block
:= listener block that is yielded to for a single occurrence of a matching event change
-
listener
:= listener lambda expression that is notified only once for a matching event change
--
call
:= called possibly with an "@ErrorInfo@":#error-info
+-
call
:= called possibly with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info
h6(#off).
default: off
@@ -633,6 +721,24 @@ h4. Parameters
-
listener
:= previous return value from a @on@ or @once@ call
-
streamSubscription
:= obtained from calling @on@ can be used to cancel a listener by calling @streamSubscription.cancel@
+blang[jsall].
+
+ h6(#whenState).
+ jsall: whenState
+
+ bq(definition).
+ jsall: whenState(targetState): Promise
+
+ Checks if a channel is in a given state and returns @null@ if it is, else calls "@once()@":#once for the given state.
+
+ h4. Parameters
+
+ - targetState := The "@ChannelState@":#channel-state to wait for __Type: @ChannelState@__
+
+ h4. Returns
+
+ Returns a promise. If the channel is already in the given state, the promise will immediately resolve to @null@. If not, it will call "@once()@":#once to return a promise which resolves the next time the channel transitions to the given state.
+
h2(#related-types). Related types
h3(#channel-state).
@@ -685,6 +791,15 @@ h3(#channel-options).
<%= partial partial_version('types/_channel_options') %>
+h3(#derive-options).
+ jsall: DeriveOptions
+
+Properties passed to "@getDerived()@":#get-derived to filter the messages returned in a subscription to it.
+
+h4(). Parameters
+
+- filter := The filter expression to use when creating or returning the derived channel. This is a "JMESPath":https://jmespath.org/ query __Type: @String@__
+
h3(#channel-state-listener).
java: io.ably.lib.realtime.ChannelStateListener
diff --git a/content/api/realtime-sdk/connection.textile b/content/api/realtime-sdk/connection.textile
index 29030c0097..94497bff6f 100644
--- a/content/api/realtime-sdk/connection.textile
+++ b/content/api/realtime-sdk/connection.textile
@@ -3,7 +3,6 @@ title: Connection
meta_description: "Realtime Client Library SDK API reference section for the connection object."
meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, connect, connection"
section: api
-index: 5
languages:
- javascript
- nodejs
@@ -13,35 +12,12 @@ languages:
- objc
- csharp
- flutter
-jump_to:
- Connection object:
- - id
- - state
- - error#error-reason
- - key
- - recovery key
- - serial
- Connection API methods:
- - connect
- - close
- - on#on
- - once
- - off#off
- - ping
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/realtime-sdk/connection
- /docs/api/versions/v1.0/realtime-sdk/connection
- /docs/api/versions/v0.8/realtime-sdk/connection
---
-blang[javascript,nodejs].
-
-
-
h2(#properties).
default: Connection Properties
swift,objc: ARTConnection Properties
@@ -79,18 +55,21 @@ A unique private connection key @String@ used to recover or resume a connection,
This private connection key can also be used by other REST clients to publish on behalf of this client. See the "publishing over REST on behalf of a realtime client documentation":/docs/pub-sub/advanced#publish-on-behalf for more info.
-h6(#recovery-key).
- default: recoveryKey
- ruby: recovery_key
- csharp: RecoveryKey
+blang[default].
+ h6(#recovery-key).
+ default: recoveryKey
+ ruby: recovery_key
+ csharp: RecoveryKey
+
+ The recovery key @String@ can be used by another client to recover this connection's state in the @recover@@Recover@ "client options":/docs/api/realtime-sdk#client-options propertymemberattribute. See "connection state recover options":/docs/connect/states#connection-state-recover-options for more information.
-The recovery key @String@ can be used by another client to recover this connection's state in the @recover@@Recover@ "client options":/docs/api/realtime-sdk#client-options propertymemberattribute. See "connection state recover options":/docs/connect/states#connection-state-recover-options for more information.
+ h6(#serial).
+ default: serial
+ csharp: Serial
-h6(#serial).
- default: serial
- csharp: Serial
+ The serial number @Integer@ of the last message to be received on this connection, used automatically by the library when recovering or resuming a connection. When recovering a connection explicitly, the @recoveryKey@@recovery_key@@RecoveryKey@ is used in the @recover@@Recover@ "client options":/docs/api/realtime-sdk#client-options as it contains both the @key@ and the last message @serial@.
-The serial number @Integer@ of the last message to be received on this connection, used automatically by the library when recovering or resuming a connection. When recovering a connection explicitly, the @recoveryKey@@recovery_key@@RecoveryKey@ is used in the @recover@@Recover@ "client options":/docs/api/realtime-sdk#client-options as it contains both the @key@ and the last message @serial@.
+blang[jsall].
h2(#methods).
default: Connection Methods
@@ -104,7 +83,7 @@ h6(#connect).
csharp: Connect
bq(definition).
- default: connect()
+ default: connect(): void
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable connect -> yields "@Connection@":/docs/api/realtime-sdk/connection
java: void connect()
csharp: void Connect()
@@ -133,7 +112,7 @@ h6(#close).
csharp: Close
bq(definition).
- default: close()
+ default: close(): void
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable close -> yields "@Connection@":/docs/api/realtime-sdk/connection
java: void close()
csharp: void Close()
@@ -324,6 +303,7 @@ h6(#ping).
bq(definition).
default: ping(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, Number responseInMilliseconds))
+ jsall: ping(): Promise
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable ping -> yields @Float seconds@
java: void ping("CompletionListener":#completion-listener listener)
objc,swift: ping(callback: (ARTErrorInfo?) -> Void)
@@ -331,6 +311,11 @@ bq(definition).
When connected, sends a heartbeat ping to the Ably server and executes the callback with any error and the response time in millisecondsexecutes the callbackcalls the listeneryields the elapsed time in seconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server.
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves with a number representing the time in seconds for the heartbeat ping request to be echoed. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
blang[ruby].
h4. Returns
@@ -340,6 +325,41 @@ blang[ruby].
Failure to receive a heartbeat ping will trigger the errback callbacks of the "@Deferrable@":/docs/api/realtime-sdk/types#deferrable with an "@ErrorInfo@":#error-info object containing an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+blang[jsall].
+ h6(#listeners).
+ jsall: listeners
+
+ bq(definition).
+ jsall: listeners(eventName?): null | connectionEventCallback[]
+
+ Returns the listeners for the specified "@ConnectionEvent@":#connection-event.
+
+blang[jsall].
+ h6(#whenState).
+ jsall: whenState
+
+ bq(definition).
+ jsall: whenState(targetState): Promise
+
+ If the connection is already in a given state, returns a promise which immediately resolves to @null@. Otherwise calls "@once@":#once to return a promise which resolves the next time the connection transitions to the given state.
+
+ h4. Parameters
+
+ - targetState := The "@ConnectionState@":#connection-state to wait for __Type: @ConnectionState@__
+
+ h4. Returns
+
+ Returns a promise. If the connection is already in the given state, the promise will immediately resolve to @null@. If not, it will call "@once()@":#once to return a promise which resolves the next time the connection transitions to the given state.
+
+blang[jsall].
+ h6(#createRecoveryKey).
+ jsall: createRecoveryKey
+
+ bq(definition).
+ jsall: createRecoveryKey(): null | string
+
+ Generates a string that can be used by another client to recover the current connection's state using the @recover@ property of the "@ClientOptions@":/docs/api/realtime-sdk/types#client-options object. See "connection state recover options":/connect/states#connection-state-recover-options for more information.
+
h2(#related-types). Related types
h3(#completion-listener).
diff --git a/content/api/realtime-sdk/encryption.textile b/content/api/realtime-sdk/encryption.textile
index f63ef9fd9a..5a6c847627 100644
--- a/content/api/realtime-sdk/encryption.textile
+++ b/content/api/realtime-sdk/encryption.textile
@@ -25,12 +25,6 @@ redirect_from:
- /docs/api/versions/v0.8/realtime-sdk/encryption
---
-blang[javascript,nodejs].
-
-
-
The @Ably.Realtime.@@Ably::Util::@@io.ably.lib.util.@@ART@@Crypto@ object exposes the following public methods:
h2(#methods). Methods
@@ -41,7 +35,7 @@ h6(#get-default-params).
csharp: GetDefaultParams
bq(definition).
- jsall: "CipherParams":#cipher-params Crypto.getDefaultParams(Object params)
+ jsall: Crypto.getDefaultParams(Object params): "CipherParams":#cipher-params
ruby: "CipherParams":#cipher-params Crypto.get_default_params(Hash params)
java: "CipherParams":#cipher-params Crypto.getDefaultParams(Param[] params)
swift,objc: getDefaultParams(values: [NSObject : AnyObject]) -> "ARTCipherParams":#cipher-params
@@ -53,7 +47,7 @@ You will rarely need to call this yourself, since the client library will handle
h4. Parameters
-- paramsarguments := The cipher paramsarguments that you want to specify. It must at a minimum include a @key@, which should be either a binary (@byte[]@@ArrayBuffer@ or @WordArray@@Buffer@byte array@NSData@) or a base64-encoded @NS@@String@.
+- paramsarguments := The cipher paramsarguments that you want to specify. It must at a minimum include a @key@, which should be either a binary (@byte[]@@ArrayBuffer@ or @Uint8Array@@Buffer@byte array@NSData@) or a base64-encoded @NS@@String@.
h4. Returns
@@ -62,9 +56,9 @@ On success, the method returns a complete "@CipherParams@":#cipher-params object
h4. Example
```[jsall]
- var cipherParams = Ably.Realtime.Crypto.getDefaultParams({key: });
- var channelOpts = { cipher: cipherParams };
- var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts);
+ const cipherParams = Ably.Realtime.Crypto.getDefaultParams({ key: });
+ const channelOpts = { cipher: cipherParams };
+ const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts);
```
```[ruby]
@@ -106,25 +100,26 @@ h6(#generate-random-key).
csharp: GenerateRandomKey
bq(definition).
- default: Crypto.generateRandomKey(Int keyLength?, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, @Buffer@ key))
- ruby: byte array Crypto.generate_random_key(Int key_length?)
- java: @byte[]@ Crypto.generateRandomKey(Int keyLength?)
+ default: Crypto.generateRandomKey(Int keyLength?, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, @Buffer@ key))
+ javascript: Crypto.generateRandomKey(Number keyLength?): Promise
+ nodejs: Crypto.generateRandomKey(Number keyLength?): Promise
+ ruby: byte array Crypto.generate_random_key(Int key_length?)
+ java: @byte[]@ Crypto.generateRandomKey(Int keyLength?)
objc,swift: generateRandomKey(length?: UInt) -> NSData
- csharp: static byte[] GenerateRandomKey(CipherMode? mode = null, int? keyLength = null)
+ csharp: static byte[] GenerateRandomKey(CipherMode? mode = null, int? keyLength = null)
This call obtains a randomly-generated binary key of the specified key length.
h4. Parameters
-- keyLengthkey_length := Optional @Int@ with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256.
+- keyLengthkey_length := Optional @Int@number with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256.
-
mode
:= Optional AES @CipherMode@ which is used when the key is generated
--
callback
:= is a function of the form @function(err, key)@ which is called upon completion
blang[jsall].
- h4. Callback result
+ h4. Returns
- On successfully generating a key, the callback is called with that key as a @WordArray@@Buffer@, and @err@ is @null@. On failure to create a key, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
+ Returns a promise. On success, the promise is fulfilled with the generated key as an @ArrayBuffer@a @Buffer@. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
blang[java,ruby,objc,swift,csharp].
h4. Returns
@@ -134,13 +129,8 @@ blang[java,ruby,objc,swift,csharp].
h4. Example
```[jsall]
- Ably.Realtime.Crypto.generateRandomKey(256, function(err, key) {
- if(err) {
- console.log("Key generation failed: " + err.toString());
- } else {
- var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {cipher: {key: key}});
- }
- });
+ const key = await Ably.Realtime.Crypto.generateRandomKey(256);
+ const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', { cipher: { key: key } });
```
```[ruby]
diff --git a/content/api/realtime-sdk/history.textile b/content/api/realtime-sdk/history.textile
index da31657d4e..3995a88b7b 100644
--- a/content/api/realtime-sdk/history.textile
+++ b/content/api/realtime-sdk/history.textile
@@ -24,48 +24,47 @@ redirect_from:
- /docs/api/versions/v0.8/realtime-sdk/history
---
-blang[javascript,nodejs].
-
-
-
h2. Channel object
The "Realtime @Channel@ object":/docs/channels exposes the following public method to obtain "@Message@":#message history.
-h3. Methods
+h3(#channel-methods). Methods
h6(#channel-history).
default: history
csharp: History
bq(definition).
- default: history(Object option, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash option) -> yields "PaginatedResult":#paginated-result<"Message":#message>
- java: "PaginatedResult":#paginated-result<"Message":#message> history("Param":#param[] option)
+ default: history(Object option, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"Message":#message>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash option) -> yields "PaginatedResult":#paginated-result<"Message":#message>
+ java: "PaginatedResult":#paginated-result<"Message":#message> history("Param":#param[] option)
objc,swift: history(query: ARTRealtimeHistoryQuery?, callback: ("ARTPaginatedResult":#paginated-result<"ARTMessage":#message>?, ARTErrorInfo?) -> Void) throws
- csharp: Task> HistoryAsync("PaginatedRequestParams":#paginated-request-params dataQuery, bool untilAttach = false);
+ csharp: Task> HistoryAsync("PaginatedRequestParams":#paginated-request-params dataQuery, bool untilAttach = false);
Gets a "paginated":#paginated-result set of historical messages for this channel.
h4. Parameters
-- optionquery"Param":#param[] option"PaginatedRequestParams":#paginated-request-params query := an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified below.
+- optionparamsquery"Param":#param[] option"PaginatedRequestParams":#paginated-request-params 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@ object
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTMessage":#message> object or an error
-h4. @options@ parameters@ARTRealtimeHistoryQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
+h4. @options@ parameters@params@ parameters@ARTRealtimeHistoryQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
-- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
-- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
+- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
+- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@ __Type: @String@@Symbol@@Direction@ enum__
-- limit:limitLimit := _100_ maximum number of messages to retrieve up to 1,000 __Type: @Integer@__
+- limit:limitLimit := _100_ maximum number of messages to retrieve up to 1,000 __Type: @Integer@@Number@__
- untilAttach:until_attach := _false_ when true, ensures message history is up until the point of the channel being attached. See "continuous history":/docs/storage-history/history#continuous-history for more info. Requires the @direction@ to be @backwards@ (the default). If the @Channel@ is not attached, or if @direction@ is set to @forwards@, this option will result in an error __Type: @Boolean@__
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":#paginated-result encapsulating an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
@@ -101,37 +100,43 @@ h2. Presence object
"Realtime @Presence@ object":/docs/presence-occupancy/presence exposes the following public method to obtain presence event history such as enter, update and leave events. These events are represented as "@PresenceMessage@":#presence-message objects.
-h3. Methods
+h3(#presence-methods). Methods
h6(#presence-history).
default: history
csharp: History
bq(definition).
- default: history(Object option, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash option) -> yields "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>
- java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history("Param":#param[] option)
+ default: history(Object option, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash option) -> yields "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>
+ java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history("Param":#param[] option)
objc,swift: history(query: ARTRealtimeHistoryQuery?, callback: ("ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message>?, ARTErrorInfo?) -> Void) throws
- csharp: Task<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>> HistoryAsync("PaginatedRequestParams":#paginated-request-params query, bool untilAttach = false [deprecated])
+ csharp: Task<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>> HistoryAsync("PaginatedRequestParams":#paginated-request-params query, bool untilAttach = false [deprecated])
Gets a "paginated":#paginated-result set of historical presence events for this channel.
h4. Parameters
-- optionquery"Param":#param[] option"PaginatedRequestParams":#paginated-request-params query := an optional object containing the query parametersan optional set of key value pairs containing the query parameters, as specified below.
+- optionparamsquery"Param":#param[] option"PaginatedRequestParams":#paginated-request-params 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@ object
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message> object or an error
-h4. @options@ parameters@ARTRealtimeHistoryQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
+h4. @options@ parameters@params@ parameters@ARTRealtimeHistoryQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
-- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
-- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
+- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
+- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@ __Type: @String@@Symbol@@Direction@ enum__
-- limit:limitLimit := _100_ maximum number of presence events to retrieve up to 1,000 __Type: @Integer@__
+- limit:limitLimit := _100_ maximum number of presence events to retrieve up to 1,000 __Type: @Integer@@Number@__
+- untilAttach:until_attach := _false_ when true, ensures presence message history is up until the point of the channel being attached. See "continuous history":/docs/storage-history/history#continuous-history for more info. Requires the @direction@ to be @backwards@ (the default). If the @Channel@ is not attached, or if @direction@ is set to @forwards@, this option will result in an error __Type: @Boolean@__
+
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
-blang[jsall,objc,swift].
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
diff --git a/content/api/realtime-sdk/messages.textile b/content/api/realtime-sdk/messages.textile
index 267d618beb..e9a092bc1c 100644
--- a/content/api/realtime-sdk/messages.textile
+++ b/content/api/realtime-sdk/messages.textile
@@ -3,7 +3,6 @@ title: Messages
meta_description: "Realtime Client Library SDK API reference section for the message object."
meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, message, messages"
section: api
-index: 10
languages:
- javascript
- nodejs
@@ -13,30 +12,12 @@ languages:
- objc
- csharp
- flutter
-jump_to:
- Message properties:
- - name#name
- - data#data
- - id#id
- - clientId#client-id
- - connectionId#connection-id
- - timestamp#timestamp
- - encoding#encoding
- Message methods:
- - fromEncoded#message-from-encoded
- - fromEncodedArray#message-from-encoded-array
redirect_from:
- /docs/api/versions/v1.1/realtime-sdk/messages
- /docs/api/versions/v1.0/realtime-sdk/messages
- /docs/api/versions/v0.8/realtime-sdk/messages
---
-blang[javascript,nodejs].
-
-
-
h2(#properties).
default: Properties
java: Members
diff --git a/content/api/realtime-sdk/presence.textile b/content/api/realtime-sdk/presence.textile
index ebeba1ec25..8f1e342913 100644
--- a/content/api/realtime-sdk/presence.textile
+++ b/content/api/realtime-sdk/presence.textile
@@ -34,12 +34,6 @@ redirect_from:
- /docs/api/versions/v0.8/realtime-sdk/presence
---
-blang[javascript,nodejs].
-
-
-
h2(#properties).
default: Presence Properties
objc,swift: ARTPresence Properties
@@ -65,26 +59,35 @@ h6(#enter).
In order to enter and be present on a channel, the client must "be identified by having a client ID":https://faqs.ably.com/authenticated-and-identified-clients, "have permission to be present":https://faqs.ably.com/using-capabilities-to-manage-client-access-privileges-on-channels, and be attached to the channel. For simplicity, the library will implicitly attach to a channel when entering. Entering when already entered is treated as an "update":#update.
-There are two overloaded versions of this method. With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to enter.
-
+blang[default].
+
+ There are two overloaded versions of this method. With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to enter.
+
+
+ bq(definition#enter-none).
+ default: enter(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter() -> yields
+ java: void enter("CompletionListener":#completion-listener listener)
+ objc,swift: enter(data: nil, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task EnterAsync()
+
+ Enter a presence channel without any data. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
+
+ bq(definition#enter-data).
+ default: enter(Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter(Object data) -> yields
+ java: void enter(Object data, "CompletionListener":#completion-listener listener)
+ objc,swift: enter(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task EnterAsync(object clientData)
-bq(definition#enter-none).
- default: enter(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter() -> yields
- java: void enter("CompletionListener":#completion-listener listener)
- objc,swift: enter(data: nil, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task EnterAsync()
+ Enter a presence channel and provide data that is associated with the current present member. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
-Enter a presence channel without any data. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
+blang[jsall].
-bq(definition#enter-data).
- default: enter(Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter(Object data) -> yields
- java: void enter(Object data, "CompletionListener":#completion-listener listener)
- objc,swift: enter(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task EnterAsync(object clientData)
+ bq(definition#enter-data).
+ jsall: enter(Object data?): Promise
-Enter a presence channel and provide data that is associated with the current present member. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
+ Enter a presence channel with optional data that is associated with the current present member. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
h4. Parameters
@@ -94,12 +97,16 @@ h4. Parameters
-
data
:= data payload for the current present member. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using @to_json@, binary data as @ASCII-8BIT@ byte arrays, and null. __Type: @Object@__
-
data
:= data payload for the message. The supported payload types are @NS@@String@, @NS@@Dictionary@ or @NS@@Array@ objects that can be serialized to JSON, binary data as @NSData@, and @nil@. __Type: @Object@__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
&block
:= yields upon successfully entering the channel
-
callback
:= called upon successfully entering the channel, or with an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On successfully entering the channel, @err@ is null. On failure to enter, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
@@ -127,27 +134,36 @@ h6(#leave).
In order to leave the presence set of a channel, the client must have already "entered and been present":#enter.
-There are two overloaded versions of this method.
- With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to leave.
-
+blang[default].
+
+ There are two overloaded versions of this method.
+ With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to leave.
+
+
+ bq(definition#leave-none).
+ default: leave(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave() -> yields
+ java: void leave("CompletionListener":#completion-listener listener)
+ swift,objc: leave(data: nil, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task LeaveAsync()
+
+ Leave a presence channel without emitting any data.
-bq(definition#leave-none).
- default: leave(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave() -> yields
- java: void leave("CompletionListener":#completion-listener listener)
- swift,objc: leave(data: nil, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task LeaveAsync()
+ bq(definition#leave-data).
+ default: leave(Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave(Object data) -> yields
+ java: void leave(Object data, "CompletionListener":#completion-listener listener)
+ swift,objc: leave(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task LeaveAsync(object clientData)
-Leave a presence channel without emitting any data.
+ Leave a presence channel and emit data that is associated with the current leaving member.
-bq(definition#leave-data).
- default: leave(Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave(Object data) -> yields
- java: void leave(Object data, "CompletionListener":#completion-listener listener)
- swift,objc: leave(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task LeaveAsync(object clientData)
+blang[jsall].
-Leave a presence channel and emit data that is associated with the current leaving member.
+ bq(definition#leave-data).
+ jsall: leave(Object data?): Promise
+
+ Leave a presence channel and emit an optional data that is associated with the current leaving member.
h4. Parameters
@@ -157,12 +173,16 @@ h4. Parameters
-
data
:= data payload for the current present member. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using @to_json@, binary data as @ASCII-8BIT@ byte arrays, and null. __Type: @Object@__
-
data
:= data payload for the message. The supported payload types are @NS@@String@, @NS@@Dictionary@ or @NS@@Array@ objects that can be serialized to JSON, binary data as @NSData@, and @nil@. __Type: @Object@__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
&block
:= yields upon successfully leaving the channel
-
callback
:= called upon leaving the channel, or with an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On successfully leaving the channel, @err@ is null. On failure to leave, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
@@ -190,12 +210,13 @@ h6(#update).
Clients can update their member data on the channel which will trigger a broadcast of this update to all presence subscribers. The "pre-requisites for @update@@Update@":#update are the same as for "@enter@@Enter@":#enter. If an attempt to @update@@Update@ is made before the client has entered the channel, the update is treated as an @enter@@Enter@.
-
+
A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data.
bq(definition#update-data).
default: update(Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: update(Object data?): Promise
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable update(Object data) -> yields
java: void update(Object data, "CompletionListener":#completion-listener listener)
swift,objc: update(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
@@ -211,12 +232,16 @@ h4. Parameters
-
data
:= data payload for the current present member. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using @to_json@, binary data as @ASCII-8BIT@ byte arrays, and null. __Type: @Object@__
-
data
:= data payload for the message. The supported payload types are @NS@@String@, @NS@@Dictionary@ or @NS@@Array@ objects that can be serialized to JSON, binary data as @NSData@, and @nil@. __Type: @Object@__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
&block
:= yields upon successfully updating the member data
-
callback
:= called upon updating the channel, or with an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On successfully updating the data, @err@ is null. On failure to update, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
@@ -250,8 +275,9 @@ When a channel is @initialized@ (i.e. no attempt to attach has yet been made for
bq(definition).
default: get(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PresenceMessage[]":#presence-message members))
+ jsall: get(Object params?): Promise<"PresenceMessage[]":#presence-message>
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable get(Hash options) -> yields "PresenceMessage[]":#presence-message
- java: "PresenceMessage[]":#presence-message get("Param":#param[] options)
+ java: "PresenceMessage[]":#presence-message get("Param[]":#param options)
swift,objc: get(query: ARTRealtimePresenceQuery, callback: (["ARTPresenceMessage":#presence-message], ARTErrorInfo?) -> Void)
csharp: Task> GetAsync(GetOptions { bool waitForSync = true, string clientId = "", string connectionId = "" })
@@ -260,19 +286,23 @@ Gets an array of members present on the channel as "PresenceMessage":#presence-m
blang[jsall,ruby,java,swift,objc].
h4. Parameters
- - optionsquery"Param":#param[] optionsoptions := an optional object containing query parametersan optional set of symbol key and value pairs containing the query parametersan optional set of parameters as specified below.
+ - optionsparamsquery"Param[]":#param optionsoptions := an optional object containing query parametersan optional set of symbol key and value pairs containing the query parametersan optional set of parameters as specified below.
- -
callback
:= is a function of the form: @function(err, "PresenceMessage[]":#presence-message members)@
-
&block
:= yields a "@PresenceMessage[]@":#presence-message array
-
callback
:= called with a "@[ARTPresenceMessage]@":#presence-message, or with an error
-h4. @options@ parameters@ARTRealtimePresenceQuery@ properties@GetOptions@ properties
+h4. @options@ parameters@params@ parameters@ARTRealtimePresenceQuery@ properties@GetOptions@ properties
- clientId:client_id := when provided, will filter array of members returned that match the provided "@clientId@":/docs/api/realtime-sdk#client-id"@client_id@":/docs/api/realtime-sdk#client-id"@ClientId@":/docs/api/realtime-sdk#client-id string
-- connectionId:connection_id := when provided, will filter array of members returned that match the provided @connectionId@@ConnectionId@@connection_id@":/docs/api/realtime-sdk/connection#id string
+- connectionId:connection_id := when provided, will filter array of members returned that match the provided "@connectionId@":/docs/api/realtime-sdk/connection#id"@ConnectionId@":/docs/api/realtime-sdk/connection#id"@connection_id@":/docs/api/realtime-sdk/connection#id string
- waitForSync:wait_for_sync := _true_ A boolean value that by default waits for the initial presence synchronization following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronization
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with an array of "@PresenceMessage@":#presence-message objects corresponding to the current set of present members on the channel. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @members@ contains an array of "@PresenceMessage@":#presence-message objects corresponding to the current set of present members on the channel.
@@ -308,25 +338,29 @@ h6(#history).
bq(definition).
default: history(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>>
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable history(Hash options) -> yields "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>
- java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history("Param":#param[] options)
+ java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history("Param[]":#param options)
objc,swift: history(query: ARTRealtimeHistoryQuery?, callback: ("ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message>?, ARTErrorInfo?) -> Void) throws
csharp: Task> HistoryAsync("PaginatedRequestParams":#paginated-request-params query, bool untilAttach = false [deprecated])
-
Gets a "paginated":#paginated-result set of historical presence message events for this channel. If the "channel is configured to persist messages to disk":https://faqs.ably.com/how-long-are-messages-stored-for, then the presence message event history will "typically be available for 24 - 72 hours":https://faqs.ably.com/how-long-are-messages-stored-for. If not, presence message events are only retained in memory by the Ably service for two minutes.
h4. Parameters
-- optionsquery"Param":#param[] options"PaginatedRequestParams":#paginated-request-params query := an optional object containing query parametersan optional set of key value pairs containing query parameters, as specified in the "presence history API documentation":/docs/storage-history/history#presence-history.
+- optionsparamsquery"Param[]":#param options"PaginatedRequestParams":#paginated-request-params query := an optional object containing query parametersan optional set of key value pairs containing query parameters, as specified in the "presence history API documentation":/docs/storage-history/history#presence-history.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
&block
:= yields a @PaginatedResult@ object
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message> object or an error
Further details of the supported @options@ params, see "presence history API documentation":/docs/storage-history/history#presence-history.
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":#paginated-result object containing an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
@@ -366,6 +400,7 @@ There are overloaded versions of this method:
bq(definition#subscribe-listener).
default: subscribe(listener("PresenceMessage":#presence-message))
+ jsall: subscribe(listener("PresenceMessage":#presence-message)): Promise
java: void subscribe("PresenceListener":#presence-listener listener)
ruby: subscribe → yields "PresenceMessage":#presence-message
objc,swift: subscribe(callback: ("ARTPresenceMessage":#presence-message) -> Void) -> ARTEventListener
@@ -375,6 +410,7 @@ Subscribe to presence message events on this channel. The caller supplies
java: void subscribe("PresenceMessage.Action":#presence-action action, "PresenceListener":#presence-listener listener)
ruby: subscribe("PresenceMessage::ACTION":#presence-action action) → yields "PresenceMessage":#presence-message
objc,swift: subscribe(action: ARTPresenceAction, callback: ("ARTPresenceMessage":#presence-message) -> Void) -> ARTEventListener
@@ -389,7 +425,7 @@ bq(definition#subscribe-event-array).
java: void subscribe("PresenceMessage.Action[]":#presence-action actions, "PresenceListener":#presence-listener listener)
ruby: subscribe("PresenceMessage::ACTION":#presence-action *actions) → yields "PresenceMessage":#presence-message
-Subscribe a single listener to messages on this channel for multiple @name@ values.
+Subscribe a single listener to messages on this channel for multiple "@action@":#presence-action values.
h4. Parameters
@@ -401,12 +437,17 @@ h4. Parameters
- actions := An argument array of "@action@ events":#presence-action to subscribe to __Type: @String[]@@*argument__
--
listener
:= is a function of the form @function(message)@ to be called for each matching presence message event
+-
listener
:= is a function of the form @function(presenceMessage)@ to be called for each matching presence message event
-
listener
:= Message listener to be notified for matching presence message event __Type: "@PresenceListener":#presence-listener__
-
&block
:= yields matching presence message event when received on the channel
-
callback
:= called with each matching "@presence message@":#presence-message when received on the channel
-
handler
:= called with each matching "@presence message@":#presence-message when received on the channel
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On successful channel attachment, the promise is resolved. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
h4. Considerations
* If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @subscribe@ will implicitly attach the channel. However, regardless of the implicit attach outcome, the listenerblockhandler will still be registered
@@ -477,28 +518,37 @@ h6(#enter-client).
Enter this presence channel for the given @clientId@@client_id@@ClientId@. This method is provided to support typically server instances that act on behalf of multiple client IDs. See "Managing multiple client IDs":/docs/presence-occupancy/presence#presence-multiple-client-id for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an "API key":/docs/auth#api-keys, or with a "token bound to a wildcard client ID":https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id.
-There are two overloaded versions of this method.
-
- With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to enter.
-
+blang[default].
-bq(definition#enter-client-none).
- default: enterClient(String clientId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter_client(String client_id) -> yields
- java: void enterClient(String clientId, "CompletionListener":#completion-listener listener)
- objc,swift: enterClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task EnterClientAsync(string clientId)
+ There are two overloaded versions of this method.
+
+ With both versions, a callbackblockcompletion listener can optionally be passed in to be notified of success or failure to enter.
+
-Enter a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ without any data. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
+ bq(definition#enter-client-none).
+ default: enterClient(String clientId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter_client(String client_id) -> yields
+ java: void enterClient(String clientId, "CompletionListener":#completion-listener listener)
+ objc,swift: enterClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task EnterClientAsync(string clientId)
-bq(definition#enter-client-data).
- default: enterClient(String clientId, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter_client(String client_id, Object data) -> yields
- java: void enterClient(String clientId, Object data, "CompletionListener":#completion-listener listener)
- objc,swift: enterClient(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task EnterClientAsync(string clientId, object clientData)
+ Enter a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ without any data. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
-Enter a presence channel and provide data that is associated with the current present member. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
+ bq(definition#enter-client-data).
+ default: enterClient(String clientId, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable enter_client(String client_id, Object data) -> yields
+ java: void enterClient(String clientId, Object data, "CompletionListener":#completion-listener listener)
+ objc,swift: enterClient(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task EnterClientAsync(string clientId, object clientData)
+
+ Enter a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ and provide data that is associated with the current present member. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
+
+blang[jsall].
+
+ bq(definition#enter-client-data).
+ jsall: enterClient(String clientId, Object data?): Promise
+
+ Enter a presence channel on behalf of the provided @clientId@ and provide an optional data that is associated with the current present member. If the channel is @initialized@ (i.e. no attempt to attach has yet been made for this channel), then calling @enter@ will implicitly attach the channel.
h4. Parameters
@@ -508,12 +558,16 @@ h4. Parameters
-
data
:= data payload for the member. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using @to_json@, binary data as @ASCII-8BIT@ byte arrays, and null. __Type: @Object@__
-
data
:= data payload for the message. The supported payload types are @NS@@String@, @NS@@Dictionary@ or @NS@@Array@ objects that can be serialized to JSON, binary data as @NSData@, and @nil@. __Type: @Object@__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
&block
:= yields upon successfully entering the channel
-
callback
:= called upon successfully entering the channel, or with an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On successfully entering the channel, @err@ is null. On failure to enter, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
@@ -542,28 +596,37 @@ h6(#leave-client).
Leave this presence channel for the given @clientId@@client_id@@ClientId@. This method is provided to support typically server instances that act on behalf of multiple client IDs. See "Managing multiple client IDs":/docs/presence-occupancy/presence#presence-multiple-client-id for more info. In order to leave the presence set of a channel, the client must have already "entered and been present":#enter-client.
-There are two overloaded versions of this method.
-
- With both versions, a callbackblockcompletion listenerhandler can optionally be passed in to be notified of success or failure to leave.
-
+blang[default].
+
+ There are two overloaded versions of this method.
+
+ With both versions, a callbackblockcompletion listenerhandler can optionally be passed in to be notified of success or failure to leave.
+
+
+ bq(definition#leave-client-none).
+ default: leaveClient(String clientId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave_client(String client_id) -> yields
+ java: void leaveClient(String clientId, "CompletionListener":#completion-listener listener)
+ swift,objc: leaveClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task LeaveClientAsync(string clientId, object data)
+
+ Leave a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ without emitting any data.
+
+ bq(definition#leave-client-data).
+ default: leaveClient(String clientId, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave_client(String client_id, Object data) -> yields
+ java: void leaveClient(String clientId, Object data, "CompletionListener":#completion-listener listener)
+ swift,objc: leave(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
+ csharp: Task LeaveClientAsync(string clientId)
-bq(definition#leave-client-none).
- default: leaveClient(String clientId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave_client(String client_id) -> yields
- java: void leaveClient(String clientId, "CompletionListener":#completion-listener listener)
- swift,objc: leaveClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task LeaveClientAsync(string clientId, object data)
+ Leave a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ and emit data that is associated with the current leaving member.
-Leave a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ without emitting any data.
+blang[jsall].
-bq(definition#leave-client-data).
- default: leaveClient(String clientId, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable leave_client(String client_id, Object data) -> yields
- java: void leaveClient(String clientId, Object data, "CompletionListener":#completion-listener listener)
- swift,objc: leave(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
- csharp: Task LeaveClientAsync(string clientId)
+ bq(definition#leave-client-data).
+ jsall: leaveClient(String clientId, Object data?): Promise
-Leave a presence channel on behalf of the provided @clientId@@client_id@@ClientId@ and emit data that is associated with the current leaving member.
+ Leave a presence channel on behalf of the provided @clientId@ and emit an optional data that is associated with the current leaving member.
h4. Parameters
@@ -573,12 +636,16 @@ h4. Parameters
-
data
:= data payload for the member. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using @to_json@, binary data as @ASCII-8BIT@ byte arrays, and null. __Type: @Object@__
-
data
:= data payload for the message. The supported payload types are @NS@@String@, @NS@@Dictionary@ or @NS@@Array@ objects that can be serialized to JSON, binary data as @NSData@, and @nil@. __Type: @Object@__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
&block
:= yields upon successfully entering the channel
-
callback
:= called upon successfully entering the channel, or with an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On successfully leaving the channel, @err@ is null. On failure to leave, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
@@ -613,6 +680,7 @@ Clients can update the member data on behalf of the given @
bq(definition#update-client-data).
default: updateClient(String clientId, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: updateClient(String clientId, Object data?): Promise
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable update_client(String client_id, Object data) -> yields
java: void updateClient(String clientId, Object data, "CompletionListener":#completion-listener listener)
swift,objc: update(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)
@@ -628,12 +696,16 @@ h4. Parameters
-
data
:= data payload for the member. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using @to_json@, binary data as @ASCII-8BIT@ byte arrays, and null. __Type: @Object@__
-
data
:= data payload for the message. The supported payload types are @NS@@String@, @NS@@Dictionary@ or @NS@@Array@ objects that can be serialized to JSON, binary data as @NSData@, and @nil@. __Type: @Object@__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
&block
:= yields upon successfully entering the channel
-
callback
:= called upon successfully entering the channel, or with an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On successfully updating the data, @err@ is null. On failure to update, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
diff --git a/content/api/realtime-sdk/push-admin.textile b/content/api/realtime-sdk/push-admin.textile
index e422c43277..c1cdb6584c 100644
--- a/content/api/realtime-sdk/push-admin.textile
+++ b/content/api/realtime-sdk/push-admin.textile
@@ -25,33 +25,36 @@ redirect_from:
- /docs/api/versions/v1.1/realtime-sdk/push-admin
---
-blang[javascript,nodejs].
-
-
-
<%= partial partial_version('types/_push_admin') %>
h2(#related-types). Related types
h3(#device-details).
- default: DeviceDetails
- ruby: Ably::Models::DeviceDetails
+ default: DeviceDetails
+ ruby: Ably::Models::DeviceDetails
+ swift,objc: ARTDeviceDetails
<%= partial partial_version('types/_device_details') %>
+h3(#push-channel).
+ default: PushChannel
+ ruby: Ably::Models::PushChannel
+
+<%= partial partial_version('types/_push_channel') %>
+
h3(#push-channel-subscription).
- default: PushChannelSubscription
- ruby: Ably::Models::PushChannelSubscription
+ default: PushChannelSubscription
+ ruby: Ably::Models::PushChannelSubscription
+ java,android: ChannelSubscription
+ swift,objc: ARTPushChannelSubscription
<%= partial partial_version('types/_push_channel_subscription') %>
h3(#paginated-result).
- default: PaginatedResult
- swift,objc: ARTPaginatedResult
- ruby: Ably::Models::PaginatedResult
- java: io.ably.lib.types.PaginatedResult
- csharp: IO.Ably.PaginatedResult
+ default: PaginatedResult
+ swift,objc: ARTPaginatedResult
+ ruby: Ably::Models::PaginatedResult
+ java,android: io.ably.lib.types.PaginatedResult
+ csharp: IO.Ably.PaginatedResult
<%= partial partial_version('types/_paginated_result') %>
diff --git a/content/api/realtime-sdk/push.textile b/content/api/realtime-sdk/push.textile
index 9b801b9f38..e9b5ed0739 100644
--- a/content/api/realtime-sdk/push.textile
+++ b/content/api/realtime-sdk/push.textile
@@ -5,6 +5,8 @@ meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, push, push not
section: api
index: 40
languages:
+ - javascript
+ - nodejs
- android
- swift
- objc
diff --git a/content/api/realtime-sdk/statistics.textile b/content/api/realtime-sdk/statistics.textile
index 0a5bed2fdb..1ef356f00a 100644
--- a/content/api/realtime-sdk/statistics.textile
+++ b/content/api/realtime-sdk/statistics.textile
@@ -3,7 +3,6 @@ title: Statistics
meta_description: "Realtime Client Library SDK API reference section for the stats object."
meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, stats, statistics"
section: api
-index: 50
languages:
- javascript
- nodejs
@@ -12,33 +11,22 @@ languages:
- swift
- objc
- csharp
-jump_to:
- API reference:
- - stats#stats
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/realtime-sdk/statistics
- /docs/api/versions/v1.0/realtime-sdk/statistics
- /docs/api/versions/v0.8/realtime-sdk/statistics
---
-blang[javascript,nodejs].
-
-
-
h6(#stats). stats
bq(definition).
- jsall: stats(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#stats> results))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable stats(Hash options) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#stats>
- java: "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#stats-type> stats("Param":#param[] options)
- swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":/docs/api/realtime-sdk/types#stats>?, ARTErrorInfo?) -> Void) throws
- csharp: Task<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#status>> StatsAsync("StatsRequestParams":#statsdatarequest query)
+ jsall: stats(Object params?): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable stats(Hash options) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>
+ java: "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type> stats("Param":#param[] options)
+ swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":#stats-type>?, ARTErrorInfo?) -> Void) throws
+ csharp: Task<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#status>> StatsAsync("StatsRequestParams":#stats-request-params query)
-This call queries the "REST @/stats@ API":/docs/api/rest-sdk#stats-type and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result is returned, containing an array of "Stats":/docs/api/realtime-sdk/types#stats-type for the first page of results. "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
+This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result is returned, containing an array of "Stats":#stats-type for the first page of results. "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
<%= partial partial_version('realtime/_stats') %>
@@ -61,7 +49,8 @@ blang[csharp].
h3(#stats-granularity).
objc,swift: ARTStatsGranularity
- csharp: StatsIntervalGranularity
+ jsall: StatsIntervalGranularity
+ csharp: StatsIntervalGranularity
<%= partial partial_version('types/_stats_granularity') %>
diff --git a/content/api/realtime-sdk/types.textile b/content/api/realtime-sdk/types.textile
index ae03b90077..71e3bcde68 100644
--- a/content/api/realtime-sdk/types.textile
+++ b/content/api/realtime-sdk/types.textile
@@ -24,12 +24,6 @@ redirect_from:
- /docs/realtime/versions/v0.8/types
---
-blang[javascript,nodejs].
-
-
-
The Ably 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.
@@ -54,13 +48,20 @@ blang[ruby].
<%= partial partial_version('types/_channel_details') %>
-h3(#device-details).
- jsall: DeviceDetails
- ruby: Ably::Models::DeviceDetails
-
blang[jsall,ruby,flutter].
+
+ h3(#device-details).
+ jsall: DeviceDetails
+ ruby: Ably::Models::DeviceDetails
+
<%= partial partial_version('types/_device_details'), indent: 2, skip_first_indent: true %>
+ h3(#local-device).
+ jsall: LocalDevice
+ ruby: Ably::Models::LocalDevice
+
+ <%= partial partial_version('types/_local_device') %>
+
h3(#error-info).
default: ErrorInfo
objc,swift: ARTErrorInfo
@@ -80,6 +81,17 @@ h3(#message).
<%= partial partial_version('types/_message') %>
+blang[jsall].
+ h3(#message-action).
+ default: Message action
+
+ <%= partial partial_version('types/_message_action') %>
+
+ h3(#message-operation).
+ default: Operation
+
+ <%= partial partial_version('types/_operation') %>
+
h3(#presence-message).
default: PresenceMessage
objc,swift: ARTPresenceMessage
@@ -155,9 +167,53 @@ h3(#stats).
h3(#stats-granularity).
objc,swift: ARTStatsGranularity
+ jsall: StatsIntervalGranularity
+ csharp: StatsIntervalGranularity
<%= partial partial_version('types/_stats_granularity') %>
+blang[jsall].
+
+ h3(#batch-publish-spec).
+ jsall: BatchPublishSpec
+
+ <%= partial partial_version('types/_batch_publish_spec') %>
+
+ h3(#batch-result).
+ jsall: BatchResult
+
+ <%= partial partial_version('types/_batch_result') %>
+
+ h3(#batch-publish-success-result).
+ jsall: BatchPublishSuccessResult
+
+ <%= partial partial_version('types/_batch_publish_success_result') %>
+
+ h3(#batch-publish-failure-result).
+ jsall: BatchPublishFailureResult
+
+ <%= partial partial_version('types/_batch_publish_failure_result') %>
+
+ h3(#batch-presence-success-result).
+ jsall: BatchPresenceSuccessResult
+
+ <%= partial partial_version('types/_batch_presence_success_result') %>
+
+ h3(#batch-presence-failure-result).
+ jsall: BatchPresenceFailureResult
+
+ <%= partial partial_version('types/_batch_presence_failure_result') %>
+
+ h3(#token-revocation-success-result).
+ jsall: TokenRevocationSuccessResult
+
+ <%= partial partial_version('types/_token_revocation_success_result') %>
+
+ h3(#token-revocation-failure-result).
+ jsall: TokenRevocationFailureResult
+
+ <%= partial partial_version('types/_token_revocation_failure_result') %>
+
h2. Other types
h3(#auth-options).
@@ -314,3 +370,15 @@ h3(#token-params).
csharp: IO.Ably.TokenParams
<%= partial partial_version('types/_token_params') %>
+
+blang[jsall].
+
+ h3(#token-revocation-target-specifier).
+ jsall: TokenRevocationTargetSpecifier
+
+ <%= partial partial_version('types/_token_revocation_target_specifier') %>
+
+ h3(#token-revocation-options).
+ jsall: TokenRevocationOptions
+
+ <%= partial partial_version('types/_token_revocation_options') %>
diff --git a/content/api/rest-sdk.textile b/content/api/rest-sdk.textile
index e660ee0605..a7ff5005d1 100644
--- a/content/api/rest-sdk.textile
+++ b/content/api/rest-sdk.textile
@@ -3,7 +3,6 @@ title: Constructor
meta_description: "Client Library SDK REST API Reference constructor documentation."
meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, constructor"
section: api
-index: 10
languages:
- javascript
- nodejs
@@ -16,31 +15,12 @@ languages:
- csharp
- go
- flutter
-jump_to:
- Constructor object:
- - constructor
- Attributes:
- - auth
- - push
- - channels
- Methods:
- - stats
- - time
- - request
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/rest-sdk
- /docs/api/versions/v1.0/rest-sdk
- /docs/api/versions/v0.8/rest-sdk
---
-blang[javascript,nodejs].
-
-
-
h2(#constructor). Constructor
The Ably REST library constructor is overloaded allowing it to be instantiated using a "@ClientOptions@":#client-options object, or more simply using a string containing an "API key":/docs/auth/basic or "Token":/docs/auth/token.
@@ -143,16 +123,17 @@ h6(#stats).
csharp,go: Stats
bq(definition).
- default: stats(Object options, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats> results))
- ruby: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats> stats(Hash options)
- python: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats> stats(kwargs_options)
- php: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats> stats(Array options)
- java: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats> stats("Param":#param[] options)
- csharp: Task<"PaginatedResult":#paginated-result<"Stats":#stats>> StatsAsync("StatsRequestParams":/docs/api/rest-sdk/types#data-request query)
- swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":#/docs/realtime/types#paginated-result<"ARTStats":/docs/api/realtime-sdk/types#stats>?, ARTErrorInfo?) -> Void) throws
+ default: stats(Object options, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> results))
+ jsall: stats(Object params?): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":docs/api/rest-sdk/types#stats-type>>
+ ruby: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(Hash options)
+ python: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(kwargs_options)
+ php: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(Array options)
+ java: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats("Param":#param[] options)
+ csharp: Task<"PaginatedResult":#paginated-result<"Stats":#stats-type>> StatsAsync("StatsRequestParams":/docs/api/rest-sdk/types#data-request query)
+ swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":#stats-type>?, ARTErrorInfo?) -> Void) throws
go: (c *RestClient) Stats(params *PaginateParams) (*PaginatedResult, error)
-This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/rest-sdk/types#paginated-result is returned, containing an array of "Stats":#stats for the first page of results. "PaginatedResult":/docs/api/rest-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
+This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/rest-sdk/types#paginated-result is returned, containing an array of "Stats":#stats-type for the first page of results. "PaginatedResult":/docs/api/rest-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
See "statistics":/docs/metadata-stats/stats for more information.
@@ -164,6 +145,7 @@ h6(#time).
bq(definition).
default: time(callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, Number time))
+ jsall: time(): Promise
ruby: Time time
python: Int time()
php: Integer time()
@@ -174,7 +156,12 @@ bq(definition).
Obtains the time from the Ably service as a @Time@ objecta @DateTimeOffset@ objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably "TokenRequests":/docs/api/rest-sdk/authentication#token-request with a more accurate timestamp should use the @queryTime@ "clientOptions":#client-options instead of this method).
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object.
+
+blang[objc,swift].
h4. Callback result
On success, @time@ is a number containing the number of milliseconds since the epoch.
@@ -197,6 +184,45 @@ blang[go].
<%= partial partial_version('rest/_request') %>
+blang[javascript].
+ h6(#batchPublish). batchPublish
+
+ There are two overloaded versions of this method:
+
+ bq(definition#batchPublish).
+ default: batchPublish("BatchPublishSpec":#batch-publish-spec spec): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>>
+
+ Publishes a "@BatchPublishSpec@":#batch-publish-spec object to one or more channels, up to a maximum of 100 channels.
+
+ bq(definition#batchPublishArray).
+ default: batchPublish("BatchPublishSpec[]":#batch-publish-spec specs): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>[]>
+
+ Publishes one or more "@BatchPublishSpec@":#batch-publish-spec objects to one or more channels, up to a maximum of 100 channels.
+
+ h4. Parameters
+
+ - spec := an object describing the messages to be batch published and to which channels __Type: "@BatchPublishSpec@":#batch-publish-spec
+ - specs := an array of objects describing the messages to be batch published and to which channels __Type: "@BatchPublishSpec@[]":#batch-publish-spec
+
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object, or an array of "@BatchResult@":#batch-result objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as "@BatchPublishSuccessResult@":#batch-publish-success-result objects, whilst failures are "@BatchPublishFailureResult@":#batch-publish-failure-result objects. If an array of "@BatchResult@":#batch-result objects are returned, they are in the same order as the provided "@BatchPublishSpec@":#batch-publish-spec. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object.
+
+ h6(#batchPresence). batchPresence
+
+ bq(definition#batchPresence).
+ default: batchPresence(String[] channels): Promise<"BatchResult":#batch-result<"BatchPresenceSuccessResult":#batch-presence-success-result | "BatchPresenceFailureResult":#batch-presence-failure-result>[]>
+
+ Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the "@clientId@":#client-options of members and their current "@PresenceAction@":/docs/api/rest-sdk/presence#presence-action.
+
+ h4. Parameters
+
+ - channels := an array of one or more channel names, up to a maximum of 100 channels __Type: @String[]@__
+
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as "@BatchPresenceSuccessResult@":#batch-presence-success-result objects, whilst failures are "@BatchPresenceFailureResult@":#batch-presence-failure-result objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object.
+
h2(#related-types). Related types
h3(#client-options).
@@ -222,7 +248,8 @@ h3(#stats-type).
h3(#stats-granularity).
objc,swift: ARTStatsGranularity
- csharp: StatsGranularity
+ jsall: StatsIntervalGranularity
+ csharp: StatsIntervalGranularity
<%= partial partial_version('types/_stats_granularity') %>
@@ -236,3 +263,35 @@ h3(#param).
blang[java].
<%= partial partial_version('types/_param'), indent: 2, skip_first_indent: true %>
+
+blang[jsall].
+
+ h3(#batch-publish-spec).
+ jsall: BatchPublishSpec
+
+ <%= partial partial_version('types/_batch_publish_spec') %>
+
+ h3(#batch-result).
+ jsall: BatchResult
+
+ <%= partial partial_version('types/_batch_result') %>
+
+ h3(#batch-publish-success-result).
+ jsall: BatchPublishSuccessResult
+
+ <%= partial partial_version('types/_batch_publish_success_result') %>
+
+ h3(#batch-publish-failure-result).
+ jsall: BatchPublishFailureResult
+
+ <%= partial partial_version('types/_batch_publish_failure_result') %>
+
+ h3(#batch-presence-success-result).
+ jsall: BatchPresenceSuccessResult
+
+ <%= partial partial_version('types/_batch_presence_success_result') %>
+
+ h3(#batch-presence-failure-result).
+ jsall: BatchPresenceFailureResult
+
+ <%= partial partial_version('types/_batch_presence_failure_result') %>
diff --git a/content/api/rest-sdk/authentication.textile b/content/api/rest-sdk/authentication.textile
index 68613e0a59..daaf0f7c0b 100644
--- a/content/api/rest-sdk/authentication.textile
+++ b/content/api/rest-sdk/authentication.textile
@@ -25,6 +25,7 @@ jump_to:
- authorize
- createTokenRequest#create-token-request
- requestToken#request-token
+ - revokeTokens#revoke-tokens
Types:
- Related Types#related-types
redirect_from:
@@ -33,12 +34,6 @@ redirect_from:
- /docs/api/versions/v0.8/rest-sdk/authentication
---
-blang[javascript,nodejs].
-
-
-
This is the Authentication API Reference.
h2(#tokens). Tokens
@@ -87,6 +82,7 @@ h6(#authorize).
bq(definition).
default: authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "TokenDetails":#token-details tokenDetails))
+ jsall: authorize("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenDetails":#token-details>
ruby: "TokenDetails":#token-details authorize("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options)
python: "TokenDetails":#token-details authorize(token_params="TokenParams":#token-params, auth_options="AuthOptions":#auth-options)
php: "TokenDetails":#token-details authorize("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
@@ -105,10 +101,18 @@ h4. Parameters
- auth_optionsAuthOptionsauthOptions := an optional object containing the "authentication options":#auth-optionsan optional "@AuthOptions@":#auth-options object containing the authentication optionsan optional Dict containing the "authentication options":#auth-optionsan optional set of key value pairs containing the "authentication options":#auth-optionsan optional set of key value pairs in an associative array containing the "authentication options":#auth-options for the authorization request __Type: "@AuthOptions@":#auth-options__
--
callback
:= is a function of the form: @function(err, tokenDetails)@
-
callback
:= called with a "@ARTTokenDetails@":#token-details object or an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise.
+
+ On success, the promise is fulfilled with the a "@TokenDetails@":#token-details object containing the details of the new or existing "Ably Token":#token-details along with the @token@ string.
+
+ On failure to obtain an token, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+
+blang[objc,swift].
h4. Callback result
On success, @tokenDetails@ contains a "@TokenDetails@":#token-details object containing the details of the new or existing "Ably Token":#token-details along with the @token@ string.
@@ -133,13 +137,12 @@ blang[csharp].
h4. Example
-bc[jsall]. client.auth.authorize({ clientId: 'bob' }, function(err, tokenDetails) {
- if(err) {
- console.log('An error occurred; err = ' + err.message);
- } else {
- console.log('Success; token = ' + tokenDetails.token);
- }
-});
+bc[jsall]. try {
+ const tokenDetails = await client.auth.authorize({ clientId: 'bob' });
+ console.log('Success; token: ' + tokenDetails.token);
+} catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+}
bc[java]. try {
TokenParams tokenParams = new TokenParams();
@@ -205,6 +208,7 @@ h6(#create-token-request).
bq(definition).
default: createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "TokenRequest":#token-request tokenRequest))
+ jsall: createTokenRequest("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenRequest":#token-request>
ruby: "TokenRequest":#token-request create_token_request("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options)
python: "TokenRequest":#token-request create_token_request(token_params="TokenParams":#token-params, key_name=String, key_secret=String)
php: "TokenRequest":#token-request createTokenRequest("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
@@ -225,10 +229,18 @@ h4. Parameters
- auth_options[auth options]AuthOptionsauthOptions := an optional object containing the "authentication options":#auth-optionsan optional "@TokenParams@":#auth-options object containing the authentication optionsvarious keyword arguments with the "authentication options":#auth-optionsan optional set of key value pairs containing the "authentication options":#auth-optionsan optional set of key value pairs in an associative array containing the "authentication options":#auth-optionsan optional "@ARTTokenParams@":#token-params containing the "authentication options":#auth-options for the "Ably Token":#token-details Request __Type: "@AuthOptions@":#auth-options__
--
callback
:= is a function of the form: @function(err, tokenRequest)@
-
callback
:= called with a "@ARTTokenRequest@":#token-request object or an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise.
+
+ On success, the promise is fulfilled with a "@TokenRequest@":#token-request JSON object.
+
+ On failure to issue a "@TokenRequest@":#token-request, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+
+blang[objc,swift].
h4. Callback result
On success, @tokenRequest@ contains a "@TokenRequest@":#token-request JSON object.
@@ -253,13 +265,12 @@ blang[csharp].
h4. Example
-bc[jsall]. client.auth.createTokenRequest({ clientId: 'bob' }, function(err, tokenRequest) {
- if(err) {
- console.log('An error occurred; err = ' + err.message);
- } else {
- console.log('Success; token request = ' + tokenRequest);
- }
-});
+bc[jsall]. try {
+ const tokenRequest = await client.auth.createTokenRequest({ clientId: 'bob' });
+ console.log('Success; token request = ' + tokenRequest);
+} catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+}
bc[java]. try {
TokenParams tokenParams = new TokenParams();
@@ -285,7 +296,7 @@ bc[ruby]. token_request = client.auth.create_token_request(client_id: 'bob')
puts "Success; token request = #{token_request}"
bc[python]. token_request = client.auth.create_token_request(token_params={'client_id': 'bob'})
-print("Success; token request = ' + str(token_request)
+print("Success; token request = ' + str(token_request))
bc[php]. $tokenRequest = $client->auth->createTokenRequest(array('clientId' => 'bob'))
echo("Success; token request = " . $tokenRequest);
@@ -326,6 +337,7 @@ h6(#request-token).
bq(definition).
default: requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "TokenDetails":#token-details tokenDetails))
+ jsall: requestToken("TokenParams":#token-params tokenParams?, "AuthOptions":#auth-options authOptions?): Promise<"TokenDetails":#token-details>
ruby: "TokenDetails":#token-details request_token("TokenParams":#token-params token_params, "AuthOptions":#auth-options auth_options)
python: "TokenDetails":#token-details request_token(token_params="TokenParams":#token-params, key_name=String, key_secret=None, auth_callback=Lambda, auth_url=String, auth_method=String, auth_headers=Dict, auth_params=Dict, query_time=Boolean)
php: "TokenDetails":#token-details requestToken("TokenParams":#token-params tokenParams, "AuthOptions":#auth-options authOptions)
@@ -346,10 +358,18 @@ h4. Parameters
- [auth options]auth_optionsauthOptions := an optional object containing the "authentication options":#auth-optionsvarious keyword arguments with the "authentication options":#auth-optionsan optional "@TokenParams@":#auth-options object containing the authentication optionsan optional set of key value pairs containing the "authentication options":#auth-optionsan optional set of key value pairs in an associative array containing the "authentication options":#auth-options for the requested "Ably Token":#token-details __Type: "@AuthOptions@":#auth-options__
--
callback
:= is a function of the form: @function(err, tokenDetails)@
-
callback
:= called with a "@ARTTokenDetails@":#token-details object or an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise.
+
+ On success, the promise is fulfilled with a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string.
+
+ On failure to obtain an "Ably Token":#token-details, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+
+blang[objc,swift].
h4. Callback result
On success, @tokenDetails@ contains a "@TokenDetails@":#token-details object containing the details of the new "Ably Token":#token-details along with the @token@ string.
@@ -374,13 +394,12 @@ blang[csharp].
h4. Example
-bc[jsall]. client.auth.requestToken({ clientId: 'bob'}, function(err, tokenDetails){
- if(err) {
- console.log('An error occurred; err = ' + err.message);
- } else {
- console.log('Success; token = ' + tokenDetails.token);
- }
-});
+bc[jsall]. try {
+ const tokenDetails = await client.auth.requestToken({ clientId: 'bob'});
+ console.log('Success; token = ' + tokenDetails.token);
+} catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+}
bc[ruby]. token_details = client.auth.request_token(client_id: 'bob')
puts "Success; token = #{token_details.token}"
@@ -437,6 +456,41 @@ if err != nil {
}
fmt.Println(token)
+blang[jsall].
+
+ h6(#revoke-tokens).
+ jsall: revokeTokens
+
+ bq(definition).
+ jsall: revokeTokens("TokenRevocationTargetSpecifier[]":#token-revocation-target-specifier specifiers, "TokenRevocationOptions":#token-revocation-options options?): Promise<"BatchResult":#batch-result<"TokenRevocationSuccessResult":#token-revocation-success-result | "TokenRevocationFailureResult":#token-revocation-failure-result>>
+
+ Calls the "@revokeTokens@ REST API endpoint":/docs/api/rest-api#revoke-tokens to revoke tokens specified by the provided array of "TokenRevocationTargetSpecifier":#token-revocation-target-specifier.
+
+ Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the "token revocation docs":/docs/auth/revocation for more information.
+
+ h4. Parameters
+
+ - specifiers := an array of "TokenRevocationTargetSpecifier":#token-revocation-target-specifier objects __Type: "@TokenRevocationTargetSpecifier[]@":#token-revocation-target-specifier__
+
+ - options := an optional set of options which are used to modify the revocation request __Type: "@TokenRevocationOptions@":#token-revocation-options__
+
+ h4. Returns
+
+ Returns a promise.
+
+ On success, the promise is fulfilled with a "BatchResult":#batch-result containing information about the result of the token revocation request for each provided "TokenRevocationTargetSpecifier":#token-revocation-target-specifier.
+
+ On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object with the error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation.
+
+ h4. Example
+
+ bc[jsall]. try {
+ const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
+ console.log('Revocation successful; revoked tokens: ' + response.results.length);
+ } catch (error) {
+ console.log('An error occurred; err = ' + error.message);
+ }
+
h2(#related-types). Related types
h3(#auth-options).
@@ -447,7 +501,7 @@ h3(#auth-options).
<%= partial partial_version('types/_auth_options') %>
h3(#token-details).
- default: TokenDetails
+ default: TokenDetails Object
objc,swift: ARTTokenDetails
java: io.ably.lib.types.TokenDetails
ruby: Ably::Models::TokenDetails
@@ -511,3 +565,33 @@ The following is an example of creating an Ably JWT:
```
*Note:* At present Ably does not support asymmetric signatures based on a keypair belonging to a third party. If this is something you'd be interested in, please "get in touch":https://ably.com/contact.
+
+h3(#batch-result).
+ jsall: BatchResult
+
+blang[jsall].
+ <%= partial partial_version('types/_batch_result') %>
+
+h3(#token-revocation-target-specifier).
+ jsall: TokenRevocationTargetSpecifier
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_target_specifier') %>
+
+h3(#token-revocation-options).
+ jsall: TokenRevocationOptions
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_options') %>
+
+h3(#token-revocation-success-result).
+ jsall: TokenRevocationSuccessResult
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_success_result') %>
+
+h3(#token-revocation-failure-result).
+ jsall: TokenRevocationFailureResult
+
+blang[jsall].
+ <%= partial partial_version('types/_token_revocation_failure_result') %>
diff --git a/content/api/rest-sdk/channel-status.textile b/content/api/rest-sdk/channel-status.textile
index 60f7177d8c..3144c07ec3 100644
--- a/content/api/rest-sdk/channel-status.textile
+++ b/content/api/rest-sdk/channel-status.textile
@@ -14,12 +14,6 @@ redirect_from:
- /docs/api/versions/v1.0/rest-sdk/channel-status
---
-blang[javascript,nodejs].
-
-
-
h2(#types). Types
The payload of metadata events for channels is the "@ChannelDetails@":#channel-details type which contains the @channelId@ (AKA the "channel's name":/docs/api/realtime-sdk/channels#name) and other static information about the channel, plus a @status@ containing a "@ChannelStatus@":#channel-status instance which contains information about the current state of the channel.
diff --git a/content/api/rest-sdk/channels.textile b/content/api/rest-sdk/channels.textile
index 32c4554b3a..f0038c19ce 100644
--- a/content/api/rest-sdk/channels.textile
+++ b/content/api/rest-sdk/channels.textile
@@ -3,7 +3,6 @@ title: Channels
meta_description: "Client Library SDK REST API Reference Channels documentation."
meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Channels"
section: api
-index: 20
languages:
- javascript
- nodejs
@@ -16,29 +15,12 @@ languages:
- csharp
- go
- flutter
-jump_to:
- Channels API methods:
- - get
- Channel API properties:
- - name
- - presence
- Channel API methods:
- - publish
- - history
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/rest-sdk/channels
- /docs/api/versions/v1.0/rest-sdk/channels
- /docs/api/versions/v0.8/rest-sdk/channels
---
-blang[javascript,nodejs].
-
-
-
h2(#channels-object).
default: Channels
@@ -98,7 +80,7 @@ Provides access to the "REST Presence":/docs/presence-occupancy/presence object
h6(#push).
default: push
-Provides access to the "PushChannel":/docs/push/publish#sub-channels object for this channel which can be used to access members present on the channel, or participate in presence.
+Provides access to the "PushChannel":/docs/api/realtime-sdk/push#push-channel object for this channel which can be used to access members present on the channel, or participate in presence.
h3. Channel Methods
@@ -110,6 +92,7 @@ There are two overloaded versions of this method:
bq(definition#publish-data).
default: publish(String name, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: publish(String name, Object data, "PublishOptions":#publish-options options?) Promise
ruby,php: publish(String name, Object data)
python: publish(name=Unicode, data=Object)
java: void publish(String name, Object data)
@@ -118,21 +101,29 @@ bq(definition#publish-data).
go: (c *RestChannel) Publish(name string, data interface{}) (error "ErrorInfo":#error-info)
flutter: Future publish({String name, Object data})
-Publish a single message on this channel based on a given event name and payload. A callback may optionally be passed in to this call to be notified of success or failure of the operation.A listener may optionally be passed in to this call to be notified of success or failure of the operation.A callback may optionally be passed in to this call to be notified of success of the operation.
+Publish a single message on this channel based on a given event name and payload. A callback may optionally be passed in to this call to be notified of success or failure of the operation.A listener may optionally be passed in to this call to be notified of success or failure of the operation.A callback may optionally be passed in to this call to be notified of success of the operation.
It is also possible to publish a message to multiple channels at once using our "batch publish feature":/docs/messages/batch#batch-publish.
+blang[jsall].
+
+ bq(definition#publish-msg).
+ jsall: publish("Message":#message message, "PublishOptions":#publish-options options?): Promise
+
+ Publish a single message on this channel.
+
bq(definition#publish-msg-array).
default: publish(Object[] messages, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby,php: publish("Message":#message[] messages)
+ jsall: publish("Message[]":#message messages, "PublishOptions":#publish-options options?): Promise
+ ruby,php: publish("Message[]":#message messages)
python: publish(messages=List<"Message":#message>)
- java: void publish("Message":#message[] messages)
+ java: void publish("Message[]":#message messages)
csharp: Task PublishAsync(IEnumerable<"Message":#message> messages)
objc,swift: publish(messages: [ "ARTMessage":#message ], callback: (("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?) -> Void)?)
go: (c *RestChannel) PublishAll(messages []*proto.Message) (error "ErrorInfo":#error-info)
flutter: Future publish({List<"Message":#message> messages})
-Publish several messages on this channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation.A listener may optionally be passed in to this call to be notified of success or failure of the operation.A callback may optionally be passed in to this call to be notified of success of the operation.
+Publish several messages on this channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation.A listener may optionally be passed in to this call to be notified of success or failure of the operation.A callback may optionally be passed in to this call to be notified of success of the operation.
The entire @messages@ array is published atomically. This means that:
@@ -158,10 +149,16 @@ h4. Parameters
-
message
:= payload for the message as a "@Message@":#message object. __Type: "@Message@":#message__
- messages := An array of message objects to publish __Type: "@Message []@":#message__
--
callback
:= is a function of the form @function(err)@ which is called upon completion
-
callback
:= called upon publishing the message, or with an error
-blang[jsall,swift,objc].
+-
options
:= optional parameters to provide to the publish operation __Type:"@PublishOptions@":#publish-options__
+
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On successful publish of the message, @err@ is null. On failure to publish the message, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
@@ -193,25 +190,30 @@ h6(#history).
csharp,go: History
bq(definition).
- default: history(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
- ruby: "PaginatedResult":#paginated-result<"Message":#message> history(Hash options)
- python: "PaginatedResult":#paginated-result<"Message":#message> history(kwargs_options)
- php: "PaginatedResult":#paginated-result<"Message":#message> history(Array options)
- java: "PaginatedResult":#paginated-result<"Message":#message> history("Param":#param[] options)
- csharp: Task<"PaginatedResult":#paginated-result<"Message":#message>> HistoryAsync("PaginatedRequestParams":#paginated-request-params dataQuery)
+ default: history(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"Message":#message>>
+ ruby: "PaginatedResult":#paginated-result<"Message":#message> history(Hash options)
+ python: "PaginatedResult":#paginated-result<"Message":#message> history(kwargs_options)
+ php: "PaginatedResult":#paginated-result<"Message":#message> history(Array options)
+ java: "PaginatedResult":#paginated-result<"Message":#message> history("Param":#param[] options)
+ csharp: Task<"PaginatedResult":#paginated-result<"Message":#message>> HistoryAsync("PaginatedRequestParams":#paginated-request-params dataQuery)
objc,swift: history(query: ARTRealtimeHistoryQuery?, callback: ("ARTPaginatedResult":#paginated-result<"ARTMessage":#message>?, ARTErrorInfo?) -> Void) throws
- go: (c *RestChannel) History(options *PaginateParams) (*"PaginatedResult":#paginated-result, "error":#error-info)
+ go: (c *RestChannel) History(options *PaginateParams) (*"PaginatedResult":#paginated-result, "error":#error-info)
Gets a "paginated":#paginated-result set of historical messages for this channel. If the "channel is configured to persist messages to disk":https://faqs.ably.com/how-long-are-messages-stored-for, then message history will "typically be available for 24 - 72 hours":https://faqs.ably.com/how-long-are-messages-stored-for. If not, messages are only retained in memory by the Ably service for two minutes.
h4. Parameters
-- optionsquery"Param":#param[] options := an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan optional Associative Array containing the query parameters, as specified in the "message history API documentation":/docs/api/rest-sdk/history#channel-history.
+- optionsparamsquery"Param":#param[] options := an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan optional Associative Array containing the query parameters, as specified in the "message history API documentation":/docs/api/rest-sdk/history#channel-history.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTMessage":#message> object or an error
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "PaginatedResult":#paginated-result object containing an array of messages. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
@@ -264,6 +266,15 @@ h3(#channel-options).
<%= partial partial_version('types/_channel_options') %>
+h3(#publish-options).
+ jsall: PublishOptions
+
+Options passed to a "@publish()@":#publish operation to customize its behavior.
+
+h4(). Parameters
+
+- quickAck := Reduces the latency of REST publishes, though provides a "slightly lower quality of service":https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes __Type: @Boolean@__
+
h3(#paginated-request-params).
csharp: PaginatedRequestParams
diff --git a/content/api/rest-sdk/encryption.textile b/content/api/rest-sdk/encryption.textile
index abb7912bf5..2defee6c44 100644
--- a/content/api/rest-sdk/encryption.textile
+++ b/content/api/rest-sdk/encryption.textile
@@ -28,12 +28,6 @@ redirect_from:
- /docs/api/versions/v0.8/rest-sdk/encryption
---
-blang[javascript,nodejs].
-
-
-
The @Ably.Rest.Crypto@@Ably::Util::Crypto@@Ably\Utils\Crypto@@ably.util.crypto@@io.ably.lib.util.crypto@@ARTCrypto@ @IO.Ably.Encryption.Crypto@ object exposes the following public methods:
h2(#methods). Methods
@@ -46,7 +40,7 @@ h6(#get-default-params).
go: DefaultCipherParams
bq(definition).
- jsall: "CipherParams":#cipher-params Crypto.getDefaultParams(Object params)
+ jsall: Crypto.getDefaultParams(Object params): "CipherParams":#cipher-params
ruby: "CipherParams":#cipher-params Crypto.get_default_params(Hash params)
python: "CipherParams":#cipher-params Crypto.get_default_params(Dict params)
php: "CipherParams":#cipher-params Crypto.getDefaultParams(Array params)
@@ -62,7 +56,7 @@ You will rarely need to call this yourself, since the client library will handle
h4. Parameters
-- paramsarguments := The cipher paramsarguments that you want to specify. It must at a minimum include a @key@, which should be either a binary (@byte[]@@ArrayBuffer@ or @WordArray@@Buffer@byte array@NSData@) or a base64-encoded @NS@@String@.
+- paramsarguments := The cipher paramsarguments that you want to specify. It must at a minimum include a @key@, which should be either a binary (@byte[]@@ArrayBuffer@ or @Uint8Array@@Buffer@byte array@NSData@) or a base64-encoded @NS@@String@.
@@ -73,9 +67,9 @@ On success, the method returns a complete "@CipherParams@":#cipher-params object
h4. Example
```[jsall]
- var cipherParams = Ably.Rest.Crypto.getDefaultParams({key: });
- var channelOpts = { cipher: cipherParams };
- var channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts);
+ const cipherParams = Ably.Rest.Crypto.getDefaultParams({ key: });
+ const channelOpts = { cipher: cipherParams };
+ const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts);
```
```[ruby]
@@ -132,6 +126,8 @@ h6(#generate-random-key).
bq(definition).
default: Crypto.generateRandomKey(Int keyLength?, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, @Buffer@ key))
+ javascript: Crypto.generateRandomKey(Number keyLength?): Promise
+ nodejs: Crypto.generateRandomKey(Number keyLength?): Promise
ruby: byte array Crypto.generate_random_key(Int key_length?)
python: byte array Crypto.generate_random_key(Int key_length?)
php: string Crypto.generateRandomKey(Int keyLength?)
@@ -144,15 +140,14 @@ This call obtains a randomly-generated binary key of the specified key lengthkeyLengthkey_length := Optional @Int@ with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256.
+- keyLengthkey_length := Optional @Int@number with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256.
-
mode
:= Optional AES @CipherMode@ which is used when the key is generated
--
callback
:= is a function of the form @function(err, key)@ which is called upon completion
blang[jsall].
- h4. Callback result
+ h4. Returns
- On successfully generating a key, the callback is called with that key as a @WordArray@@Buffer@, and @err@ is @null@. On failure to create a key, @err@ contains an "@ErrorInfo@":#error-info object describing the failure reason.
+ Returns a promise. On success, the promise is fulfilled with the generated key as an @ArrayBuffer@a @Buffer@. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object that details the reason why it was rejected.
blang[java,ruby,objc,swift,php,python,csharp,go].
h4. Returns
@@ -162,13 +157,8 @@ blang[java,ruby,objc,swift,php,python,csharp,go].
h4. Example
```[jsall]
- Ably.Rest.Crypto.generateRandomKey(256, function(err, key) {
- if(err) {
- console.log("Key generation failed: " + err.toString());
- } else {
- var channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', {cipher: {key: key}});
- }
- });
+ const key = await Ably.Rest.Crypto.generateRandomKey(256);
+ const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', { cipher: { key: key } });
```
```[ruby]
diff --git a/content/api/rest-sdk/history.textile b/content/api/rest-sdk/history.textile
index 25a2639239..039ea6ae90 100644
--- a/content/api/rest-sdk/history.textile
+++ b/content/api/rest-sdk/history.textile
@@ -27,17 +27,11 @@ redirect_from:
- /docs/api/versions/v0.8/rest-sdk/history
---
-blang[javascript,nodejs].
-
-
-
h2. Channel object
The "Rest @Channel@ object":/docs/channels exposes the following public method to obtain "@Message@":#message history.
-h3. Methods
+h3(#channel-methods). Methods
h6(#channel-history).
default: history
@@ -45,6 +39,7 @@ h6(#channel-history).
bq(definition).
default: history(Object option, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":#paginated-result<"Message":#message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"Message":#message>>
ruby: "PaginatedResult":#paginated-result<"Message":#message> history(Hash option)
python: "PaginatedResult":#paginated-result<"Message":#message> history(kwargs_options)
php: "PaginatedResult":#paginated-result<"Message":#message> history(Array option)
@@ -57,19 +52,23 @@ Gets a "paginated":#paginated-result set of historical messages for this channel
h4. Parameters
-- optionquery"Param":#param[] option := an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parameters, as specified below.
+- optionparamsquery"Param":#param[] option := an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parameters, as specified below.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTMessage":#message> object or an error
-h4. @options@ parameters@ARTDataQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
+h4. @options@ parameters@params@ parameters@ARTDataQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
-- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
-- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
+- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
+- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any messages retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@ __Type: @String@@Symbol@@Direction@ enum__
-- limit:limitLimit := _100_ maximum number of messages to retrieve up to 1,000 __Type: @Integer@__
+- limit:limitLimit := _100_ maximum number of messages to retrieve up to 1,000 __Type: @Integer@@Number@__
+
+blang[jsall].
+ h4. Returns
-blang[jsall,objc,swift].
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":#paginated-result encapsulating an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Message@":#message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
@@ -103,7 +102,7 @@ h2. Presence object
"Rest @Presence@ object":/docs/presence-occupancy/presence exposes the following public method to obtain presence event history such as enter, update and leave events. These events are represented as "@PresenceMessage@":#presence-message objects.
-h3. Methods
+h3(#presence-methods). Methods
h6(#presence-history).
default: history
@@ -111,6 +110,7 @@ h6(#presence-history).
bq(definition).
default: history(Object option, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>>
ruby: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history(Hash option)
python: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history(kwargs_options)
php: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history(Array option)
@@ -123,19 +123,23 @@ Gets a "paginated":#paginated-result set of historical presence events for this
h4. Parameters
-- option"Param":#param[] option"PaginatedRequestParams":#paginated-request-params query := an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parameters, as specified below.
+- optionparams"Param":#param[] option"PaginatedRequestParams":#paginated-request-params query := an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parameters, as specified below.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message> object or an error
-h4. @options@ parameters@ARTDataQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
+h4. @options@ parameters@params@ parameters@ARTDataQuery@ properties"@PaginatedRequestParams@":#paginated-request-params properties
-- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
-- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
+- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
+- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any presence events retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@ __Type: @String@@Symbol@@Direction@ enum__
-- limit:limitLimit := _100_ maximum number of presence events to retrieve up to 1,000 __Type: @Integer@__
+- limit:limitLimit := _100_ maximum number of presence events to retrieve up to 1,000 __Type: @Integer@@Number@__
+
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
-blang[jsall,objc,swift].
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
diff --git a/content/api/rest-sdk/messages.textile b/content/api/rest-sdk/messages.textile
index c35aefc838..e1618ae157 100644
--- a/content/api/rest-sdk/messages.textile
+++ b/content/api/rest-sdk/messages.textile
@@ -3,7 +3,6 @@ title: Messages
meta_description: "Client Library SDK REST API Reference Message documentation."
meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Message"
section: api
-index: 40
languages:
- javascript
- nodejs
@@ -16,25 +15,10 @@ languages:
- csharp
- go
- flutter
-jump_to:
- Channel API properties:
- - name
- - presence
- Channel API methods:
- - publish
- - history
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/rest-sdk/messages
- /docs/api/versions/v1.0/rest-sdk/messages
- /docs/api/versions/v0.8/rest-sdk/messages
---
-blang[javascript,nodejs].
-
-
-
<%= partial partial_version('types/_message') %>
diff --git a/content/api/rest-sdk/presence.textile b/content/api/rest-sdk/presence.textile
index 4fc8d48a76..4a148299f4 100644
--- a/content/api/rest-sdk/presence.textile
+++ b/content/api/rest-sdk/presence.textile
@@ -27,12 +27,6 @@ redirect_from:
- /docs/api/versions/v0.8/rest-sdk/presence
---
-blang[javascript,nodejs].
-
-
-
h2. Methods
h6(#get).
@@ -42,11 +36,12 @@ h6(#get).
Get the current presence member set for this channel. In the REST client library this method directly queries "Ably's REST presence API":/docs/api/rest-api#presence
bq(definition).
- default: get(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
+ default: get(Object options, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
+ jsall: get(Object params?): Promise<"PresenceMessage[]":#presence-message>
ruby: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> get(Hash options)
python: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> get(kwargs_options)
php: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> get(Array options)
- java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> get("Param":#param[] options)
+ java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> get("Param[]":#param options)
csharp: Task<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>> GetAsync(int? limit = null, string clientId = null, string connectionId = null);
swift,objc: get(query: ARTPresenceQuery, callback: (["ARTPresenceMessage":#presence-message], ARTErrorInfo?) -> Void)
go: (p *RestPresence) Get(options *PaginateParams) (*"PaginatedResult":#paginated-result, error)
@@ -56,22 +51,19 @@ Gets an array of members present on the channel as "PresenceMessage":#presence-m
blang[jsall,ruby,python,php,java,swift,objc,go].
h4. Parameters
- - optionsquery"Param":#param[] 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.
+ - optionsparamsquery"Param[]":#param 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@":#paginated-result@<@"@PresenceMessage@":#presence-message@>@, or with an error
-h4. @options@ parameters@ARTPresenceQuery@ propertiesArguments
+h4. @options@ parameters@params@ parameters@ARTPresenceQuery@ propertiesArguments
- clientIdclient_id:client_id := when provided, will filter array of members returned that match the provided "@clientId@":/docs/api/rest-sdk#client-options"@client_id@":/docs/api/rest-sdk#client-options"@ClientId@":/docs/api/rest-sdk#client-options string
-- connectionIdconnection_id:connection_id := when provided, will filter array of members returned that match the provided @connectionId@@ConnectionId@@connection_id@":/docs/api/realtime-sdk/connection#id string
+- connectionIdconnection_id:connection_id := when provided, will filter array of members returned that match the provided "@connectionId@":/docs/api/realtime-sdk/connection#id"@ConnectionId@":/docs/api/realtime-sdk/connection#id"@connection_id@":/docs/api/realtime-sdk/connection#id string
blang[jsall].
- h4. Callback result
-
- On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of members currently present on the channel. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
+ h4. Returns
- On failure to retrieve the current presence member set, @err@ contains an "@ErrorInfo@":#error-info object with the failure reason.
+ Returns a promise. On success, the promise is fulfilled with an array of "@PresenceMessage@":#presence-message objects corresponding to the current set of present members on the channel. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object that details the reason why it was rejected.
blang[java,ruby,php,python,csharp].
h4. Returns
@@ -91,14 +83,17 @@ blang[java,ruby,php,python,csharp].
Failure to retrieve the current presence member, the @error@ contains an "@ErrorInfo@":#error-info object with the failure reason.
-h6(#history). History
+h6(#history).
+ default: history
+ csharp: History
bq(definition).
default: history(Object options, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> resultPage))
+ jsall: history(Object params?): Promise<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>>
ruby: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history(Hash options)
python: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history(kwargs_options)
php: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history(Array options)
- java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history("Param":#param[] options)
+ java: "PaginatedResult":#paginated-result<"PresenceMessage":#presence-message> history("Param[]":#param options)
csharp: Task<"PaginatedResult":#paginated-result<"PresenceMessage":#presence-message>> HistoryAsync("PaginatedRequestParams":#paginated-request-params query);
objc,swift: history(query: ARTDataQuery?, callback: ("ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message>?, ARTErrorInfo?) -> Void) throws
go: (p *RestPresence) History(params *PaginateParams) (*PaginatedResult, error)
@@ -107,12 +102,16 @@ Gets a "paginated":#paginated-result set of historical presence message events f
h4. Parameters
-- options"Param":#param[] optionsquery"PaginatedRequestParams":#paginated-request-params 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":/docs/storage-history/history#presence-history.
+- optionsparams"Param[]":#param optionsquery"PaginatedRequestParams":#paginated-request-params 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":/docs/storage-history/history#presence-history.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTPresenceMessage":#presence-message> object or an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":#paginated-result object containing an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@PresenceMessage@":#presence-message objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
diff --git a/content/api/rest-sdk/push-admin.textile b/content/api/rest-sdk/push-admin.textile
index f936d32b6d..b8fe703bdc 100644
--- a/content/api/rest-sdk/push-admin.textile
+++ b/content/api/rest-sdk/push-admin.textile
@@ -6,11 +6,11 @@ section: api
index: 80
languages:
- javascript
+ - nodejs
- java
- ruby
- php
- android
- - nodejs
- swift
- objc
jump_to:
@@ -26,12 +26,6 @@ redirect_from:
- /docs/api/versions/v1.1/rest-sdk/push-admin
---
-blang[javascript,nodejs].
-
-
-
<%= partial partial_version('types/_push_admin') %>
h2(#related-types). Related types
@@ -43,25 +37,25 @@ h3(#device-details).
<%= partial partial_version('types/_device_details') %>
+h3(#push-channel).
+ default: PushChannel
+ ruby: Ably::Models::PushChannel
+
+<%= partial partial_version('types/_push_channel') %>
+
h3(#push-channel-subscription).
default: PushChannelSubscription
ruby: Ably::Models::PushChannelSubscription
java,android: ChannelSubscription
- swift,objc: ArtPushChannelSubscription
+ swift,objc: ARTPushChannelSubscription
<%= partial partial_version('types/_push_channel_subscription') %>
-h3(#push-channel).
- default: PushChannel
- ruby: Ably::Models::PushChannel
-
-<%= partial partial_version('types/_push_channel') %>
-
h3(#paginated-result).
- default: PaginatedResult
- swift,objc: ARTPaginatedResult
- ruby: Ably::Models::PaginatedResult
+ default: PaginatedResult
+ swift,objc: ARTPaginatedResult
+ ruby: Ably::Models::PaginatedResult
java,android: io.ably.lib.types.PaginatedResult
- csharp: IO.Ably.PaginatedResult
+ csharp: IO.Ably.PaginatedResult
<%= partial partial_version('types/_paginated_result') %>
diff --git a/content/api/rest-sdk/statistics.textile b/content/api/rest-sdk/statistics.textile
index 51d1d7079a..783d9b0d87 100644
--- a/content/api/rest-sdk/statistics.textile
+++ b/content/api/rest-sdk/statistics.textile
@@ -3,7 +3,6 @@ title: Statistics
meta_description: "Client Library SDK REST API Reference Statistics documentation."
meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Statistics"
section: api
-index: 100
languages:
- javascript
- nodejs
@@ -15,38 +14,27 @@ languages:
- objc
- csharp
- go
-jump_to:
- API reference:
- - stats#stats
- Types:
- - Related Types#related-types
redirect_from:
- /docs/api/versions/v1.1/rest-sdk/statistics
- /docs/api/versions/v1.0/rest-sdk/statistics
- /docs/api/versions/v0.8/rest-sdk/statistics
---
-blang[javascript,nodejs].
-
-
-
h6(#stats).
default: stats
csharp,go: Stats
bq(definition).
- jsall: stats(Object options, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":/docs/api/rest-sdk/types#stats> results))
- ruby: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":/docs/api/rest-sdk/types#stats> stats(Hash options)
- python: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":/docs/api/rest-sdk/types#stats> stats(kwargs_options)
- php: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":/docs/api/rest-sdk/types#stats> stats(Array options)
- java: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":/docs/api/rest-sdk/types#stats-type> stats("Param":#param[] options)
- csharp: Task<"PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":/docs/api/rest-sdk/types#stats-type>> StatsAsync(@StatsRequestParams@ query)
- swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":#/docs/realtime/types#paginated-result<"ARTStats":/docs/api/realtime-sdk/types#stats>?, ARTErrorInfo?) -> Void) throws
+ jsall: stats(Object params?): Promise<"PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type>>
+ ruby: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(Hash options)
+ python: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(kwargs_options)
+ php: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(Array options)
+ java: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats("Param":#param[] options)
+ csharp: Task<"PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type>> StatsAsync("StatsRequestParams":#stats-request-params query)
+ swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":#stats-type>?, ARTErrorInfo?) -> Void) throws
go: (c *RestClient) Stats(params *PaginateParams) (*PaginatedResult, error)
-This call queries the "Ably REST @/stats@ API endpoint":/docs/api/rest-api#stats-type and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/rest-sdk/types#paginated-result is returned, containing an array of "Stats":/docs/api/rest-sdk/types#stats-type for the first page of results. "PaginatedResult":/docs/api/rest-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
+This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/rest-sdk/types#paginated-result is returned, containing an array of "Stats":#stats-type for the first page of results. "PaginatedResult":/docs/api/rest-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
<%= partial partial_version('rest/_stats') %>
@@ -70,7 +58,8 @@ blang[csharp].
h3(#stats-granularity).
objc,swift: ARTStatsGranularity
- csharp: IO.Ably.StatsGranularity
+ jsall: StatsIntervalGranularity
+ csharp: StatsIntervalGranularity
<%= partial partial_version('types/_stats_granularity') %>
diff --git a/content/api/rest-sdk/types.textile b/content/api/rest-sdk/types.textile
index a6ff2d1591..09c46ad2e0 100644
--- a/content/api/rest-sdk/types.textile
+++ b/content/api/rest-sdk/types.textile
@@ -23,12 +23,6 @@ redirect_from:
- /docs/rest/types
---
-blang[javascript,nodejs].
-
-
-
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.
@@ -148,6 +142,8 @@ h3(#stats).
h3(#stats-granularity).
objc,swift: ARTStatsGranularity
+ jsall: StatsIntervalGranularity
+ csharp: StatsIntervalGranularity
<%= partial partial_version('types/_stats_granularity') %>
@@ -157,6 +153,48 @@ h3(#paginated-request-params).
blang[csharp].
<%= partial partial_version('types/_history_request_params'), indent: 2, skip_first_indent: true %>
+blang[jsall].
+
+ h3(#batch-publish-spec).
+ jsall: BatchPublishSpec
+
+ <%= partial partial_version('types/_batch_publish_spec') %>
+
+ h3(#batch-result).
+ jsall: BatchResult
+
+ <%= partial partial_version('types/_batch_result') %>
+
+ h3(#batch-publish-success-result).
+ jsall: BatchPublishSuccessResult
+
+ <%= partial partial_version('types/_batch_publish_success_result') %>
+
+ h3(#batch-publish-failure-result).
+ jsall: BatchPublishFailureResult
+
+ <%= partial partial_version('types/_batch_publish_failure_result') %>
+
+ h3(#batch-presence-success-result).
+ jsall: BatchPresenceSuccessResult
+
+ <%= partial partial_version('types/_batch_presence_success_result') %>
+
+ h3(#batch-presence-failure-result).
+ jsall: BatchPresenceFailureResult
+
+ <%= partial partial_version('types/_batch_presence_failure_result') %>
+
+ h3(#token-revocation-success-result).
+ jsall: TokenRevocationSuccessResult
+
+ <%= partial partial_version('types/_token_revocation_success_result') %>
+
+ h3(#token-revocation-failure-result).
+ jsall: TokenRevocationFailureResult
+
+ <%= partial partial_version('types/_token_revocation_failure_result') %>
+
h2. REST Other types
h3(#auth-options).
@@ -216,3 +254,15 @@ h3(#token-params).
csharp: IO.Ably.TokenParams
<%= partial partial_version('types/_token_params') %>
+
+blang[jsall].
+
+ h3(#token-revocation-target-specifier).
+ jsall: TokenRevocationTargetSpecifier
+
+ <%= partial partial_version('types/_token_revocation_target_specifier') %>
+
+ h3(#token-revocation-options).
+ jsall: TokenRevocationOptions
+
+ <%= partial partial_version('types/_token_revocation_options') %>
diff --git a/content/partials/realtime/_stats.textile b/content/partials/realtime/_stats.textile
index 84441b5a88..8315a8eead 100644
--- a/content/partials/realtime/_stats.textile
+++ b/content/partials/realtime/_stats.textile
@@ -1,22 +1,26 @@
h4. Parameters
-- optionsquery := an optional objectHash@ARTStatsQuery@@StatsRequestParams@"@Param@":#param[] array containing the query parameters
+- optionsqueryparams := an optional objectHash@ARTStatsQuery@@StatsRequestParams@"@Param@[]":#param array containing the query parameters set of parameters used to specify which statistics are retrieved. If not specified the default parameters will be used
--
callback
:= is a function of the form: @function(err, result)@
-
&block
:= yields a @PaginatedResult@ object
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTStats":/docs/api/rest-sdk/types#stats> object or an error
-h4. @options@ parameters@ARTStatsQuery@ properties@StatsRequestParams@ properties
+h4. @options@ parameters@ARTStatsQuery@ properties@StatsRequestParams@ properties@params@ properties
The following options, as defined in the "REST @/stats@ API":/docs/api/rest-api#stats endpoint, are permitted:
-- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
-- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
+- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
+- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@ __Type: @String@@Symbol@@Direction@ enum__
-- limit:limitLimit := _100_ maximum number of stats to retrieve up to 1,000 __Type: @Integer@__
-- unit:unitUnit := _minute_ @:minute@, @:hour@, @:day@ or @:month@.@minute@, @hour@, @day@ or @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: @String@"@ARTStatsGranularity@":#stats-granularity@Symbol@@StatsIntervalGranularity@ enum__
+- limit:limitLimit := _100_ maximum number of stats to retrieve up to 1,000 __Type: @Integer@@Number@__
+- unit:unitUnit := _minute_ @:minute@, @:hour@, @:day@ or @:month@.@minute@, @hour@, @day@ or @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: @String@"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity"@ARTStatsGranularity@":#stats-granularity@Symbol@"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity enum__
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result object containing an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
+blang[objc,swift].
h4. Callback result
On success, @result@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Stats@":/docs/api/realtime-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods.
diff --git a/content/partials/rest/_request.textile b/content/partials/rest/_request.textile
index 47f3a577a9..ae7a9faa98 100644
--- a/content/partials/rest/_request.textile
+++ b/content/partials/rest/_request.textile
@@ -3,13 +3,14 @@ h6(#request).
go,csharp: Request
bq(definition).
- default: request(String method, String path, Object params, Object body, Object headers, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response results))
- ruby,php: "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response request(String method, String path, Object params, Object body, Object headers)
- python: publish(method=String, path=String, params=Object, body=Object, headers=Object)
- java: "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response request(String method, String path, Object params, Object body, Object headers)
- csharp: Task<"HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response> Request(string method, string path, Dictionary requestParams, JToken body, Dictionary headers)
+ default: request(String method, String path, Object params, Object body, Object headers, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response results))
+ jsall: request(method, path, version, params?, body?, headers?): Promise<"HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response>
+ ruby,php: "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response request(String method, String path, Object params, Object body, Object headers)
+ python: publish(method=String, path=String, params=Object, body=Object, headers=Object)
+ java: "HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response request(String method, String path, Object params, Object body, Object headers)
+ csharp: Task<"HttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response> Request(string method, string path, Dictionary requestParams, JToken body, Dictionary headers)
objc,swift: request(method: String, path: String, params: Object?, body: Object?, headers: Object?, callback: ("ARTHttpPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response, ARTErrorInfo?) -> Void)
- go: "HTTPPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response Request(method string, path string, params PaginateParams, body interface, headers http.Header)
+ go: "HTTPPaginatedResponse":/docs/api/rest-sdk/types#http-paginated-response Request(method string, path string, params PaginateParams, body interface, headers http.Header)
Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to handle authentication, paging, fallback hosts, MsgPack and JSON support, etc. themselves.
@@ -17,11 +18,19 @@ h4. Parameters
- method := either @get@, @post@, @put@, @patch@ or @delete@. __Type: Stringstring__
- path := the path to query. __Type: Stringstring__
+
+-
version
:= version of the REST API to use. __Type: Number__
+
- params := (optional) any querystring parameters needed. __Type: ObjectPaginateParamsDictionary__
- body := (optional; for @post@, @put@ and @patch@ methods) the body of the request, as anything that can be serialized into JSON, such as an @Object@ or @Array@.a JToken. __Type: SerializableinterfaceJToken__
- headers := (optional) any headers needed. If provided, these will be mixed in with the default library headers. __Type: Objecthttp.HeaderDictionary__
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with the "@HttpPaginatedResponse@":/docs/api/realtime-sdk/types#http-paginated-response object returned by the HTTP request. The response object will contain an empty or JSON-encodable object. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
+blang[objc,swift].
h4. Callback result
On successfully receiving a response from Ably, @results@ contains an "@HttpPaginatedResponse@@ARTHttpPaginatedResponse@":/docs/api/rest-sdk/types#http-paginated-response containing the @statusCode@ of the response, a @success@ boolean (equivalent to whether the status code is between 200 and 299), @headers@, and an @items@ array containing the current page of results. It supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods, identically to "@PaginatedResult@":/docs/api/rest-sdk/types#paginated-result.
@@ -47,23 +56,16 @@ blang[csharp].
h4. Example
```[jsall]
-rest.request(
- 'get',
- '/channels/someChannel/messages',
- {limit: 1, direction: 'forwards'},
- null,
- null,
- function(err, response) {
- if(err) {
- console.log('An error occurred; err = ' + err.toString());
- } else {
- console.log('Success! status code was ' + response.statusCode);
- console.log(response.items.length + ' items returned');
- if(response.hasNext()) {
- response.next(function(err, nextPage) {
- console.log(nextPage.items.length + ' more items returned');
- });
- }
- }
- });
+ const response = await rest.request(
+ 'get',
+ '/channels/someChannel/messages',
+ 3,
+ { limit: 1, direction: 'forwards' },
+ );
+ console.log('Success! status code was ' + response.statusCode);
+ console.log(response.items.length + ' items returned');
+ if (response.hasNext()) {
+ const nextPage = await response.next();
+ console.log(nextPage.items.length + ' more items returned');
+ }
```
diff --git a/content/partials/rest/_stats.textile b/content/partials/rest/_stats.textile
index 1f3d38d4f5..015a9fd82b 100644
--- a/content/partials/rest/_stats.textile
+++ b/content/partials/rest/_stats.textile
@@ -1,22 +1,26 @@
h4. Parameters
-- optionsquery := an optional objectHash@ARTStatsQuery@@StatsRequestParams@"@Param@":#param[] array containing the query parameters
+- optionsqueryparams := an optional objectHash@ARTStatsQuery@@StatsRequestParams@"@Param@[]":#param array containing the query parameters set of parameters used to specify which statistics are retrieved. If not specified the default parameters will be used
--
callback
:= is a function of the form: @function(err, result)@
-
&block
:= yields a @PaginatedResult@ object
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"ARTStats":/docs/api/rest-sdk/types#stats> object or an error
-h4. @options@ parameters@ARTStatsQuery@ properties@StatsRequestParams@ properties
+h4. @options@ parameters@ARTStatsQuery@ properties@StatsRequestParams@ properties@params@ properties
The following options, as defined in the "REST @/stats@ API":/docs/api/rest-api#stats endpoint, are permitted:
-- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
-- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@__
+- start:startStart := _beginning of time_ earliest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
+- end:endEnd := _current time_ latest @DateTimeOffset@ or @Time@ or time in milliseconds since the epoch for any stats retrieved __Type: @Long@@Int@ or @Time@@DateTimeOffset@@Number@__
- direction:directionDirection := _backwards_ @:forwards@ or @:backwards@@forwards@ or @backwards@ __Type: @String@@Symbol@@Direction@ enum__
-- limit:limitLimit := _100_ maximum number of messages to retrieve up to 1,000 __Type: @Integer@__
-- unit:unitUnit := _minute_ @:minute@, @:hour@, @:day@ or @:month@.@minute@, @hour@, @day@ or @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: @String@"@ARTStatsGranularity@":#stats-granularity@Symbol@@StatsIntervalGranularity@ enum__
+- limit:limitLimit := _100_ maximum number of stats to retrieve up to 1,000 __Type: @Integer@@Number@__
+- unit:unitUnit := _minute_ @:minute@, @:hour@, @:day@ or @:month@.@minute@, @hour@, @day@ or @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: @String@"@StatsIntervalGranularity@":/docs/api/rest-sdk/types#stats-granularity"@ARTStatsGranularity@":#stats-granularity@Symbol@"@StatsIntervalGranularity@":/docs/api/rest-sdk/types#stats-granularity enum__
-blang[jsall,objc,swift].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/rest-sdk/types#paginated-result object containing an array of "@Stats@":/docs/api/rest-sdk/types#stats objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object.
+
+blang[objc,swift].
h4. Callback result
On success, @result@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "@Stats@":/docs/api/rest-sdk/types#stats objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods.
diff --git a/content/partials/types/_batch_presence_failure_result.textile b/content/partials/types/_batch_presence_failure_result.textile
new file mode 100644
index 0000000000..cf3995a7cf
--- /dev/null
+++ b/content/partials/types/_batch_presence_failure_result.textile
@@ -0,0 +1,8 @@
+A @BatchPresenceFailureResult@ contains information about the result of an unsuccessful batch presence request for a single channel.
+
+h4.
+ default: Properties
+
+- channel := The channel name the presence state failed to be retrieved for __Type: @String@__
+
+- error := Describes the reason for which presence state could not be retrieved for the channel as an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object __Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__
diff --git a/content/partials/types/_batch_presence_success_result.textile b/content/partials/types/_batch_presence_success_result.textile
new file mode 100644
index 0000000000..4be5e5e2bf
--- /dev/null
+++ b/content/partials/types/_batch_presence_success_result.textile
@@ -0,0 +1,8 @@
+A @BatchPresenceSuccessResult@ contains information about the result of a successful batch presence request for a single channel.
+
+h4.
+ default: Properties
+
+- channel := The channel name the presence state was retrieved for __Type: @String@__
+
+- presence := An array of "@PresenceMessage@":/docs/api/realtime-sdk/types#presence-message describing members present on the channel __Type: "@PresenceMessage[]@":/docs/api/realtime-sdk/types#presence-message
diff --git a/content/partials/types/_batch_publish_failure_result.textile b/content/partials/types/_batch_publish_failure_result.textile
new file mode 100644
index 0000000000..2f7972cc1c
--- /dev/null
+++ b/content/partials/types/_batch_publish_failure_result.textile
@@ -0,0 +1,8 @@
+A @BatchPublishFailureResult@ contains information about the result of unsuccessful publishes to a channel requested by a single "@BatchPublishSpec@":/docs/api/realtime-sdk/types#batch-publish-spec.
+
+h4.
+ default: Properties
+
+- channel := The name of the channel the message(s) failed to be published to __Type: @String@__
+
+- error := Describes the reason for which the message(s) failed to publish to the channel as an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object __Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__
diff --git a/content/partials/types/_batch_publish_spec.textile b/content/partials/types/_batch_publish_spec.textile
new file mode 100644
index 0000000000..44b3016b1a
--- /dev/null
+++ b/content/partials/types/_batch_publish_spec.textile
@@ -0,0 +1,8 @@
+A @BatchPublishSpec@ describes the messages that should be published by a batch publish operation, and the channels to which they should be published.
+
+h4.
+ default: Properties
+
+- channels := The names of the channels to publish the @messages@ to __Type: @String[]@__
+
+- messages := An array of "@Message@":/docs/api/realtime-sdk/types#message objects __Type: "@Message[]@":/docs/api/realtime-sdk/types#message__
diff --git a/content/partials/types/_batch_publish_success_result.textile b/content/partials/types/_batch_publish_success_result.textile
new file mode 100644
index 0000000000..ebde876657
--- /dev/null
+++ b/content/partials/types/_batch_publish_success_result.textile
@@ -0,0 +1,8 @@
+A @BatchPublishSuccessResult@ contains information about the result of successful publishes to a channel requested by a single "@BatchPublishSpec@":/docs/api/realtime-sdk/types#batch-publish-spec.
+
+h4.
+ default: Properties
+
+- channel := The name of the channel the message(s) was published to __Type: @String@__
+
+- messageId := A unique ID prefixed to the @Message.id@ of each published message __Type: @String@__
diff --git a/content/partials/types/_batch_result.textile b/content/partials/types/_batch_result.textile
new file mode 100644
index 0000000000..0f38217513
--- /dev/null
+++ b/content/partials/types/_batch_result.textile
@@ -0,0 +1,10 @@
+A @BatchResult@ contains information about the results of a batch operation.
+
+h4.
+ default: Properties
+
+- successCount := The number of successful operations in the request __Type: @Number@__
+
+- failureCount := The number of unsuccessful operations in the request __Type: @Number@__
+
+- messages := An array of results for the batch operation (for example, an array of "@BatchPublishSuccessResult@":/docs/api/realtime-sdk/types#batch-publish-success-result or "@BatchPublishFailureResult@":/docs/api/realtime-sdk/types#batch-publish-failure-result for a channel batch publish request) __Type: Object[]__
diff --git a/content/partials/types/_cipher_params.textile b/content/partials/types/_cipher_params.textile
index 184bc8c395..b27c210ec6 100644
--- a/content/partials/types/_cipher_params.textile
+++ b/content/partials/types/_cipher_params.textile
@@ -7,7 +7,7 @@ h4.
java: Members
ruby: Attributes
--
keyKey:key
:= A binary (@byte[]@@ArrayBuffer@ or @WordArray@@Buffer@byte array@NSData@) or base64-encoded @NS@@String@ containing the secret key used for encryption and decryption
+-
keyKey:key
:= A binary (@byte[]@@ArrayBuffer@ or @Uint8Array@@Buffer@byte array@NSData@) or base64-encoded @NS@@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@__
diff --git a/content/partials/types/_client_options.textile b/content/partials/types/_client_options.textile
index 579f20a565..69a7daea15 100644
--- a/content/partials/types/_client_options.textile
+++ b/content/partials/types/_client_options.textile
@@ -25,9 +25,11 @@ h4.
- transportParamsTransportParamstransport_params:transport_params := Optional. Can be used to pass in arbitrary connection parameters, such as "@heartbeatInterval@":/docs/connect#heartbeats and "@remainPresentFor@":/docs/presence-occupancy/presence#unstable-connections __Type: @Object@@Dict@@Hash@@Associative Array@@Param []@@Dictionary@@Map@__
blang[jsall].
- - 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. 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 thus not act independently between library instances when multiple library instances exist concurrently. __Type: @Object@__
+ - logLevel := A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). __Type: @Integer@__
- - 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 []@__
+ - logHandler := A function to handle each line of the library's log output. If @logHandler@ is not specified, @console.log@ is used. __Type: @Callable@__
+
+ - transports := An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: @web_socket@, @xhr_polling@.The transports available in the Node.js client library are: @web_socket@, @xhr_polling@, @comet@. __Type: @String []@__
blang[java].
- 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":https://github.com/ably/ably-java/#logging for more details. __Type: @Integer@__
diff --git a/content/partials/types/_device_details.textile b/content/partials/types/_device_details.textile
index 2807f37bfc..203ca82761 100644
--- a/content/partials/types/_device_details.textile
+++ b/content/partials/types/_device_details.textile
@@ -9,16 +9,16 @@ h4.
- clientIdclient_id := optional trusted "client identifier":/docs/auth/identified-clients for the device __Type: @String@__
-- formFactorform_factor := form factor of the push device. Must be one of @phone@, @tablet@, @desktop@, @tv@, @watch@, @car@ or @embedded@ __Type: @String@__
+- formFactorform_factor := form factor of the push device. Must be one of @phone@, @tablet@, @desktop@, @tv@, @watch@, @car@ or @embedded@@embedded@ or @other@ __Type: @String@__
- metadata := optional metadata object for this device. The metadata for a device may only be set by clients with @push-admin@ privileges __Type: @Object@@Array@@Hash@__
-- platform := platform of the push device. Must be one of @ios@ or @android@ __Type: @String@__
+- platform := platform of the push device. Must be one of @ios@ or @android@@android@ or @browser@ __Type: @String@__
- deviceSecret := Secret value for the device. __Type: @String@__
- push.recipient := push recipient details for this device. See the "REST API push publish documentation":/docs/api/rest-api#message-extras-push for more details __Type: @Object@@Array@@Hash@__
-- push.state := the current state of the push device being either @Active@, @Failing@ or @Failed@ __Type: @String@__
+- push.state := the current state of the push device being either @Active@, @Failing@ or @Failed@@ACTIVE@, @FAILING@ or @FAILED@ __Type: @String@__
-- push.errorReasonpush.error_reason := when the device's state is failing or failed, this attribute contains the reason for the most recent failure __Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__
+- push.errorReasonpush.errorpush.error_reason := when the device's state is failing or failed, this attribute contains the reason for the most recent failure __Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__
diff --git a/content/partials/types/_http_paginated_response.textile b/content/partials/types/_http_paginated_response.textile
index e10ea668f4..44179667ad 100644
--- a/content/partials/types/_http_paginated_response.textile
+++ b/content/partials/types/_http_paginated_response.textile
@@ -12,7 +12,7 @@ h4.
- statusCodestatus_codeStatusCode := the HTTP status code of the response __Type: @Number@__
- successSuccess := whether the HTTP status code indicates success. This is equivalent to @200 <= statusCode < 300@@200 <= status_code < 300@@200 <= StatusCode < 300@ __Type: @Boolean@__
- headersHeaders := the headers of the response __Type: @Object@__
-- errorCodeerror_codeErrorCode := the error code if the @X-Ably-Errorcode@ HTTP header is sent in the response __Type: @Int@__
+- errorCodeerror_codeErrorCode := the error code if the @X-Ably-Errorcode@ HTTP header is sent in the response __Type: @Int@@Number@__
- errorMessageerror_messageErrorMessage := the error message if the @X-Ably-Errormessage@ HTTP header is sent in the response __Type: @String@__
@@ -24,6 +24,7 @@ h6.
bq(definition).
default: first(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response resultPage))
+ jsall: first(): Promise<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response>
ruby: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first
php: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first()
python: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response first()
@@ -32,7 +33,11 @@ bq(definition).
swift,objc: first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)
go: First() ("HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response, error)
-Returns a new @HttpPaginatedResponse@ for the first page of results. When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields an "@HttpPaginatedResponse@":/docs/api/realtime-sdk/types#http-paginated-response.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response.
+blang[default].
+ Returns a new @HttpPaginatedResponse@ for the first page of results. When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields an "@HttpPaginatedResponse@":/docs/api/realtime-sdk/types#http-paginated-response.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response.
+
+blang[jsall].
+ Returns a promise. On success, the promise is fulfilled with a new @HttpPaginatedResponse@ for the first page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
h6.
default: hasNext
@@ -76,6 +81,7 @@ h6.
bq(definition).
default: next(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response resultPage))
+ jsall: next(): Promise<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response>
ruby: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next
php: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next()
python: "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response next()
@@ -84,7 +90,20 @@ bq(definition).
swift,objc: next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)
go: Next() ("HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response, 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 returned@Null@@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":/docs/api/realtime-sdk/types#deferrable and yields an "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response.
+blang[default].
+ Returns a new @HttpPaginatedResponse@ loaded with the next page of results. If there are no further pages, then @null@a blank HttpPaginatedResponse will be returned@Null@@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":/docs/api/realtime-sdk/types#deferrable and yields an "HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response.
+
+blang[jsall].
+ Returns a promise. On success, the promise is fulfilled with a new @HttpPaginatedResponse@ loaded with the next page of results. If there are no further pages, then @null@ is returned. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[jsall].
+ h6(#current).
+ default: current
+
+ bq(definition).
+ default: current(): Promise<"HttpPaginatedResponse":/docs/api/realtime-sdk/types#http-paginated-response>
+
+ Returns a promise. On success, the promise is fulfilled with a new @HttpPaginatedResponse@ loaded with the current page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
h4. Example
diff --git a/content/partials/types/_local_device.textile b/content/partials/types/_local_device.textile
index 1bed9ec7e1..19b8663953 100644
--- a/content/partials/types/_local_device.textile
+++ b/content/partials/types/_local_device.textile
@@ -1,8 +1,30 @@
+
An extension of "@DeviceDetails@":#device-details. In addition to the propertiesmembersattributes of "@DeviceDetails@":#device-details, it includes the following:
+
+
Contains the device identity token and secret of a device.
h4.
default: Properties
java: Members
ruby: Attributes
-- deviceIdentityToken := a unique identity token for the device __Type: @String@__
+-
id
:= a unique ID generated by the device __Type: @String@__
+-
deviceSecret
:= a unique device secret generated by the Ably SDK __Type: @String@__
+
+- deviceIdentityToken := a unique identity token for the device __Type: @String@__
+
+
+h4. Methods
+
+h6.
+ jsall: listSubscriptions
+
+bq(definition).
+ jsall: listSubscriptions(): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":/docs/api/realtime-sdk/types#push-channel-subscription>>
+
+Retrieves push subscriptions active for the local device.
+
+h4. Returns
+
+Returns a promise. On success, the promise is fulfilled with a "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result object containing an array of "PushChannelSubscription":/docs/api/realtime-sdk/types#push-channel-subscription objects for each push channel subscription active for the local device. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected.
+
diff --git a/content/partials/types/_message.textile b/content/partials/types/_message.textile
index 33724929f7..c4b1b09d02 100644
--- a/content/partials/types/_message.textile
+++ b/content/partials/types/_message.textile
@@ -59,6 +59,43 @@ h6(#encoding).
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@__
+blang[jsall].
+
+ h6(#action).
+ default: action
+
+ The action type of the message, one of the "@MessageAction@":/docs/api/realtime-sdk/types#message-action enum values. __Type: @int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }@__
+
+ h6(#serial).
+ default: serial
+
+ This message's unique serial (an identifier that will be the same in all future updates of this message). __Type: @String@__
+
+ h6(#ref-serial).
+ default: refSerial
+
+ If this message references another, the serial of that message. __Type: @String@__
+
+ h6(#ref-type).
+ default: refType
+
+ If this message references another, the type of reference that is. __Type: @String@__
+
+ h6(#created-at).
+ default: createdAt
+
+ The timestamp of the very first version of a given message (will differ from @timestamp@ only if the message has been updated or deleted). __Type: @Integer@__
+
+ h6(#version).
+ default: version
+
+ The version of the message, lexicographically-comparable with other versions (that share the same serial). Will differ from the serial only if the message has been updated or deleted. __Type: @String@__
+
+ h6(#operation).
+ default: operation
+
+ In the case of an updated or deleted message, this will contain metadata about the update or delete operation. __Type: "@Operation@":/docs/api/realtime-sdk/types#message-operation__
+
h3(constructors).
default: Message constructors
diff --git a/content/partials/types/_message_action.textile b/content/partials/types/_message_action.textile
new file mode 100644
index 0000000000..b525ba9066
--- /dev/null
+++ b/content/partials/types/_message_action.textile
@@ -0,0 +1,11 @@
+@Message@ @action@ is a String representing the action type of the message.
+
+```[javascript]
+ const MessageActions = [
+ 'message.create',
+ 'message.update',
+ 'message.delete',
+ 'meta',
+ 'message.summary'
+ ]
+```
diff --git a/content/partials/types/_operation.textile b/content/partials/types/_operation.textile
new file mode 100644
index 0000000000..02e0e9d02f
--- /dev/null
+++ b/content/partials/types/_operation.textile
@@ -0,0 +1,10 @@
+An @Operation@ contains the details of an operation, such as update or deletion, supplied by the actioning client.
+
+h4.
+ default: Properties
+
+- clientId := The client ID of the client that initiated the operation __Type: @String@__
+
+- description := The description provided by the client that initiated the operation __Type: @String@__
+
+- metadata := A JSON object of string key-value pairs that may contain metadata associated with the operation __Type: @Record@__
diff --git a/content/partials/types/_paginated_result.textile b/content/partials/types/_paginated_result.textile
index 9e846c58fe..7cefa9d403 100644
--- a/content/partials/types/_paginated_result.textile
+++ b/content/partials/types/_paginated_result.textile
@@ -18,6 +18,7 @@ h6.
bq(definition).
default: first(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result resultPage))
+ jsall: first(): Promise<"PaginatedResult":#paginated-result>
ruby: "PaginatedResult":#paginated-result first
php: "PaginatedResult":#paginated-result first()
python: "PaginatedResult":#paginated-result first()
@@ -26,7 +27,12 @@ bq(definition).
swift,objc: first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)
go: First() ("PaginatedResult":#paginated-result, error)
-Returns a new @PaginatedResult@ for the first page of results. When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields a "PaginatedResult":#paginated-result.The method is asynchronous and returns a Task which needs to be awaited to get the "PaginatedResult":#paginated-result.
+
+blang[default].
+ Returns a new @PaginatedResult@ for the first page of results. When using the Realtime library, the @first@ method returns a "Deferrable":/docs/api/realtime-sdk/types#deferrable and yields a "PaginatedResult":#paginated-result.The method is asynchronous and returns a Task which needs to be awaited to get the "PaginatedResult":#paginated-result.
+
+blang[jsall].
+ Returns a promise. On success, the promise is fulfilled with a new @PaginatedResult@ for the first page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
h6.
default: hasNext
@@ -70,6 +76,7 @@ h6.
bq(definition).
default: next(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result resultPage))
+ jsall: next(): Promise<"PaginatedResult":#paginated-result | null>
ruby: "PaginatedResult":#paginated-result next
php: "PaginatedResult":#paginated-result next()
python: "PaginatedResult":#paginated-result next()
@@ -78,18 +85,29 @@ bq(definition).
swift,objc: next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)
go: Next() ("PaginatedResult":#paginated-result, 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 returned@Null@@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":/docs/api/realtime-sdk/types#deferrable and yields a "PaginatedResult":#paginated-result.
+blang[default].
+ Returns a new @PaginatedResult@ loaded with the next page of results. If there are no further pages, then @null@a blank PaginatedResult will be returned@Null@@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":/docs/api/realtime-sdk/types#deferrable and yields a "PaginatedResult":#paginated-result.
+
+blang[jsall].
+ Returns a promise. On success, the promise is fulfilled with a new @PaginatedResult@ loaded with the next page of results. If there are no further pages, then @null@ is returned. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[jsall].
+ h6(#current).
+ default: current
+
+ bq(definition).
+ default: current(): Promise<"PaginatedResult":#paginated-result>
+
+ Returns a promise. On success, the promise is fulfilled with a new @PaginatedResult@ loaded with the current page of results. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
h4(#paginated-result-example). Example
```[jsall]
-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());
- });
-});
+const paginatedResult = await channel.history();
+console.log('Page 0 item 0:' + paginatedResult.items[0].data);
+const nextPage = await paginatedResult.next();
+console.log('Page 1 item 1: ' + nextPage.items[1].data);
+console.log('Last page?: ' + nextPage.isLast());
```
```[java,android]
diff --git a/content/partials/types/_push_admin.textile b/content/partials/types/_push_admin.textile
index b317a43214..7e63c50abb 100644
--- a/content/partials/types/_push_admin.textile
+++ b/content/partials/types/_push_admin.textile
@@ -2,17 +2,36 @@ h2(#push-admin). Push Admin object
This object is accessible through @client.push.admin@ and provides:
-h3. Methods
+h3(#properties).
+ default: Push Admin Properties
+ ruby: Push::Admin Properties
+
+The push admin object exposes the following public propertiesattributesmembers:
+
+h6(#device-registrations).
+ default: deviceRegistrations
+ ruby,python: device_registrations
+
+The returned "@DeviceRegistrations@":#device-registrations-object object provides functionality for registering, updating, listing and de-registering push devices.
+
+h6(#channel-subscriptions).
+ default: channelSubscriptions
+ ruby,python: channel_subscriptions
+
+The returned "@PushChannelSubscriptions@":#push-channel-subscriptions object provides functionality for subscribing, listing and unsubscribing individual devices or groups of "identified devices":/docs/auth/identified-clients to push notifications published on channels.
+
+h3(#methods). Methods
h6(#publish).
default: publish
bq(definition).
- default: publish(Object recipient, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable publish(Hash recipient, Hash data) -> yield
- python: publish(recipient=Object, data=Object)
- php: publish(Array recipient, Array data)
- swift,objc: publish(recipient: ARTPushRecipient, data: AnyObject?, callback: (("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?) -> Void)?)
+ default: publish(Object recipient, Object data, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: publish(Object recipient, Object payload): Promise
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable publish(Hash recipient, Hash data) -> yield
+ python: publish(recipient=Object, data=Object)
+ php: publish(Array recipient, Array data)
+ swift,objc: publish(recipient: ARTPushRecipient, data: AnyObject?, callback: (("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?) -> Void)?)
java,android: void publish(String recipient, Object data, "CompletionListener":#completion-listener listener)
Publishes a push notification directly to a device or group of devices sharing a "client identifier":/docs/auth/identified-clients. See the "push notification direct publishing documentation":/docs/push/publish#direct-publishing for more information.
@@ -20,14 +39,18 @@ Publishes a push notification directly to a device or group of devices sharing a
h4. Parameters
- recipient := an objectan arraya Hash containing the push recipient details. See the "push notification publish REST API documentation":/docs/api/rest-api#push-publish for details on the supported recipient fields
-- data := an objectan arraya Hash containing the push notification data. See the "push admin payload structure":/docs/push/publish#payload for details on the supported push payload fields
+- datapayload := an objectan arraya Hash containing the push notification data. See the "push admin payload structure":/docs/push/publish#payload for details on the supported push payload fields
--
callback
:= a function of the form: @function(err)@
-
&block
:= yielded upon success
-
listener
:= Listener to be notified on completion __Type: "@CompletionListener@":#completion-listener__
-
callback
:= called upon publishing the message, or with an error
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
The callback is called upon success or failure to publish the push notification. When this operation fails, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason.
@@ -46,39 +69,24 @@ blang[java].
On successful publish of the message, the @onSuccess@ method of the "CompletionListener":#completion-listener is called. On failure to publish the message, the @onError@ method is called with an "@ErrorInfo@":#error-info argument describing the failure reason.
-h2(#properties).
- default: Push Admin Properties
- ruby: Push::Admin Properties
-
-The push admin object exposes the following public propertiesattributesmembers:
-
-h6(#device-registrations).
- default: deviceRegistrations
- ruby,python: device_registrations
-
-The returned "@DeviceRegistrations@":#device-registrations-object object provides functionality for registering, updating, listing and de-registering push devices.
-
-h6(#channel-subscriptions).
- default: channelSubscriptions
- ruby,python: channel_subscriptions
-
-The returned "@PushChannelSubscriptions@":#push-channel-subscriptions object provides functionality for subscribing, listing and unsubscribing individual devices or groups of "identified devices":/docs/auth/identified-clients to push notifications published on channels.
-
-h2(#device-registrations-object). DeviceRegistrations object
+h2(#device-registrations-object).
+ default: DeviceRegistrations object
+ jsall: PushDeviceRegistrations object
This object is accessible through @client.push.admin.deviceRegistrations@@client.push.admin.device_registrations@ and provides an API to register new push notification devices, update existing devices, deregister old devices, and retrieve or list devices registered to an app.
-h3. Methods
+h3(#device-registrations-methods). Methods
h6(#device-get).
default: get
bq(definition#device-get-id).
- default: get(String deviceId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable get(String deviceId) -> yields "DeviceDetails":#device-details
- python: "DeviceDetails":#device-details get(device_id=String)
- php: "DeviceDetails":#device-details get(String deviceId)
- swift,objc: get(deviceId: ArtDeviceId, callback: ((ARTDeviceDetails?, ARTErrorInfo?) -> Void)
+ default: get(String deviceId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device))
+ jsall: get(String deviceId): Promise<"DeviceDetails":#device-details>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable get(String deviceId) -> yields "DeviceDetails":#device-details
+ python: "DeviceDetails":#device-details get(device_id=String)
+ php: "DeviceDetails":#device-details get(String deviceId)
+ swift,objc: get(deviceId: ArtDeviceId, callback: ((ARTDeviceDetails?, ARTErrorInfo?) -> Void))
java,android: "DeviceDetails":#device-details get(String deviceId)
blang[java,android].
@@ -88,6 +96,7 @@ blang[java,android].
bq(definition#device-get-device).
default: get("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device))
+ jsall: get("DeviceDetails":#device-details deviceDetails): Promise<"DeviceDetails":#device-details>
ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable get("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details
Obtain the @DeviceDetails@ for a device registered for receiving push registrations matching the @deviceId@ argument, or the @id@ attribute of the provided @DeviceDetails@ object. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@.
@@ -95,12 +104,16 @@ Obtain the @DeviceDetails@ for a device registered for receiving push registrati
h4. Parameters
- deviceId := the unique device ID String for the requested device
-- device := a "@DeviceDetails@":#device-details object containing at a minimum the @deviceId@ of the requested device
+- devicedeviceDetails := a "@DeviceDetails@":#device-details object containing at a minimum the @deviceId@ of the requested device
--
callback
:= is a function of the form: @function(err, device)@
-
&block
:= yields a @DeviceDetails@ object upon success
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@DeviceDetails@":#device-details object representing the device registered for push notifications. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @device@ contains the device registered for push notifications as a "@DeviceDetails@":#device-details object.
@@ -125,11 +138,12 @@ h6(#device-list).
default: list
bq(definition).
- default: list(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"DeviceDetails":#device-details device> resultPage))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list(Hash params) -> yields "PaginatedResult":#paginated-result<"DeviceDetails":#device-details>
- python: "PaginatedResult":#paginated-result list(params=Object)
- php: "PaginatedResult":#paginated-result list_(Array params)
- swift,objc: list(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void)
+ default: list(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":#paginated-result<"DeviceDetails":#device-details device> resultPage))
+ jsall: list(Object params): Promise<"PaginatedResult":#paginated-result<"DeviceDetails":#device-details>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list(Hash params) -> yields "PaginatedResult":#paginated-result<"DeviceDetails":#device-details>
+ python: "PaginatedResult":#paginated-result list(params=Object)
+ php: "PaginatedResult":#paginated-result list_(Array params)
+ swift,objc: list(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void))
java,android: "PaginatedResult":#paginated-result list(Param[] params)
Retrieve all devices matching the params filter as a paginated list of "@DeviceDetails@":#device-details objects. Requires @push-admin@ permission.
@@ -138,7 +152,6 @@ h4. Parameters
- params"Param":#param[] params := an object containing the query parameters as key value pairs as specified below.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
&block
:= yields a @PaginatedResult@ object
h4. @params@ properties
@@ -147,7 +160,17 @@ h4. @params@ properties
- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with a @clientId@@:client_id@ param __Type: @String@__
- limit:limit := _100_ maximum number of devices per page to retrieve, up to 1,000 __Type: @Integer@__
-blang[jsall,objc,swift].
+blang[jsall].
+ - state := optional filter by the state of the device. Must be one of @ACTIVE@, @FAILING@ or @FAILED@ __Type: @String@__
+
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@DeviceDetails@":#device-details objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods.
+
+ On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@DeviceDetails@":#device-details objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods.
@@ -167,23 +190,28 @@ h6(#device-save).
default: save
bq(definition).
- default: save("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable save("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details
- python: "DeviceDetails":#device-details save("DeviceDetails":#device-details device_details)
- php: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails)
- swift,objc: save(deviceDetails: "DeviceDetails":#device-details, callback: (("DeviceDetails":#device-details?, ARTErrorInfo?) -> Void)
+ default: save("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "DeviceDetails":#device-details device))
+ jsall: save("DeviceDetails":#device-details deviceDetails): Promise<"DeviceDetails":#device-details>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable save("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details
+ python: "DeviceDetails":#device-details save("DeviceDetails":#device-details device_details)
+ php: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails)
+ swift,objc: save(deviceDetails: "DeviceDetails":#device-details, callback: (("DeviceDetails":#device-details?, ARTErrorInfo?) -> Void))
java,android: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails)
Register a new @DeviceDetails@ object, or update an existing @DeviceDetails@ object with the Ably service. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@.
h4. Parameters
-- device := a "@DeviceDetails@":#device-details object
+- devicedeviceDetails := a "@DeviceDetails@":#device-details object
--
callback
:= is a function of the form: @function(err, device)@
-
&block
:= yields the new @DeviceDetails@ object upon success
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@DeviceDetails@":#device-details object representing the newly registered or updated device. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @device@ contains the newly registered or updated device as a "@DeviceDetails@":#device-details object.
@@ -203,19 +231,21 @@ h6(#device-remove).
default: remove
bq(definition#device-remove-id).
- default: remove(String deviceId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove(String deviceId)
- python: remove(String device_id)
- php: remove(String deviceId)
- swift,objc: remove(deviceDetails: "DeviceDetails":#device-details, callback: (("DeviceDetails":#device-details?, ARTErrorInfo?) -> Void)
+ default: remove(String deviceId, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: remove(String deviceId): Promise
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove(String deviceId)
+ python: remove(String device_id)
+ php: remove(String deviceId)
+ swift,objc: remove(deviceDetails: "DeviceDetails":#device-details, callback: (("DeviceDetails":#device-details?, ARTErrorInfo?) -> Void))
java,android: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails)
bq(definition#device-remove-device).
- default: remove("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove("DeviceDetails":#device-details device) -> yield
- python: remove("DeviceDetails":#device-details device_details)
- php: remove("DeviceDetails":#device-details deviceDetails)
- swift,objc: remove(deviceDetails: "DeviceDetails":#device-details, callback: ((ARTErrorInfo?) -> Void)
+ default: remove("DeviceDetails":#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: remove("DeviceDetails":#device-details deviceDetails): Promise
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove("DeviceDetails":#device-details device) -> yield
+ python: remove("DeviceDetails":#device-details device_details)
+ php: remove("DeviceDetails":#device-details deviceDetails)
+ swift,objc: remove(deviceDetails: "DeviceDetails":#device-details, callback: ((ARTErrorInfo?) -> Void))
java,android: "DeviceDetails":#device-details save("DeviceDetails":#device-details deviceDetails)
Remove a device registered for receiving push registrations that matches the @deviceId@ argument, or the @id@ attribute of the provided "@DeviceDetails@":#device-details object. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@.
@@ -223,12 +253,16 @@ Remove a device registered for receiving push registrations that matches the @de
h4. Parameters
- deviceId := the unique device ID String for the device
-- device := a "@DeviceDetails@":#device-details object containing at a minimum the @deviceId@ of the device
+- devicedeviceDetails := a "@DeviceDetails@":#device-details object containing at a minimum the @deviceId@ of the device
--
callback
:= is a function of the form: @function(err)@
-
&block
:= yields upon success
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success to delete the device, the promise resolves. Note that a request to delete a device that does not exist will result in a successful operation. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
The callback is called upon success or failure to delete the device. Note that a request to delete a device that does not exist will result in a successful operation.
@@ -249,11 +283,12 @@ h6(#device-remove-where).
ruby,python: remove_where
bq(definition).
- default: removeWhere(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove_where(Hash params) -> yield
- python: remove_where(params=Object)
- php: removeWhere(Array params)
- swift,objc: removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void)
+ default: removeWhere(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: removeWhere(Object params): Promise
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable remove_where(Hash params) -> yield
+ python: remove_where(params=Object)
+ php: removeWhere(Array params)
+ swift,objc: removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void)
java,android: removeWhere(Param[] params)
Delete all devices matching the params filter. Requires @push-admin@ permission.
@@ -262,7 +297,6 @@ h4. Parameters
- params"Param":#param[] params := an object containing the filter parameters as key value pairs as specified below.
--
callback
:= is a function of the form: @function(err)@
-
&block
:= yields upon success
h4. @params@ properties
@@ -270,7 +304,12 @@ h4. @params@ properties
- clientId:client_id := optional filter to restrict to devices associated with that client identifier. Cannot be used with a @deviceId@@:device_id@ param __Type: @String@__
- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with a @clientId@@:client_id@ param __Type: @String@__
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success to delete the device, the promise resolves. Note that a request that does match any existing devices will result in a successful operation. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
The callback is called upon success or failure to delete the device. Note that a request that does match any existing devices will result in a successful operation.
@@ -290,17 +329,18 @@ h2(#push-channel-subscriptions). PushChannelSubscriptions object
This object is accessible through @client.push.admin.channelSubscriptions@@client.push.admin.channel_subscriptions@ and provides an API to subscribe a push notification device to a channel ensuring it receives any push notifications published in the future on that channel. Additionally, this object allows these subscriptions to be retrieved, listed, updated or removed.
-h3. Methods
+h3(#push-channel-subscriptions-methods). Methods
h6(#push-channel-sub-list).
default: list
bq(definition).
- default: list(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":#push-channel-subscription> resultPage))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list(Hash params) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":#push-channel-subscription>
- python: "PaginatedResult":#paginated-result list(params=Object)
- php: "PaginatedResult":#paginated-result list_(Array params)
- swift,objc: list(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void)
+ default: list(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":#push-channel-subscription> resultPage))
+ jsall: list(Object params): Promise<"PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list(Hash params) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"PushChannelSubscription":#push-channel-subscription>
+ python: "PaginatedResult":#paginated-result list(params=Object)
+ php: "PaginatedResult":#paginated-result list_(Array params)
+ swift,objc: list(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void))
java,android: "PaginatedResult":#paginated-result list(Param[] params)
Retrieve all push channel subscriptions that match the provided params filter as a paginated list of "@PushChannelSubscription@":#push-channel-subscription objects. Each "@PushChannelSubscription@":#push-channel-subscription represents a device or set of devices sharing the same "client identifier":/docs/auth/identified-clients registered to a channel to receive push notifications.
@@ -309,7 +349,6 @@ h4. Parameters
- params"Param":#param[] params := an object containing the query parameters as key value pairs as specified below.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
&block
:= yields a @PaginatedResult@ object
h4. @params@ properties
@@ -319,7 +358,14 @@ h4. @params@ properties
- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with a @clientId@@:client_id@ param __Type: @String@__
- limit:limit := _100_ maximum number of channel subscriptions per page to retrieve, up to 1,000 __Type: @Integer@__
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@PushChannelSubscription@":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods.
+
+ On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of "@PushChannelSubscription@":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods.
@@ -340,11 +386,12 @@ h6(#push-channel-sub-list-channels).
ruby,python: list_channels
bq(definition).
- default: listChannels(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result resultPage))
- ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list_channels(Hash params) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result
- python: "PaginatedResult":#paginated-result list_channels(params=Object)
- php: "PaginatedResult":#paginated-result listChannels(Array params)
- swift,objc: listChannels(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void)
+ default: listChannels(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result resultPage))
+ jsall: listChannels(Object params): Promise<"PaginatedResult":#paginated-result>
+ ruby: "Deferrable":/docs/api/realtime-sdk/types#deferrable list_channels(Hash params) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result
+ python: "PaginatedResult":#paginated-result list_channels(params=Object)
+ php: "PaginatedResult":#paginated-result listChannels(Array params)
+ swift,objc: listChannels(params: NSDictionary *, callback: (("ARTPaginatedResult":#paginated-result?, ARTErrorInfo?) -> Void))
java,android: "PaginatedResult":#paginated-result listChannels(Param[] params)
Retrieve a list of channels that have at least one device "subscribed to push notifications":/docs/push/publish#sub-channels as a paginated list of channel name @String@ objects. Requires @push-admin@ permission.
@@ -353,14 +400,20 @@ h4. Parameters
- params"Param":#param[] params := an object containing the query parameters as key value pairs as specified below.
--
callback
:= is a function of the form: @function(err, resultPage)@
-
&block
:= yields a @PaginatedResult@ object
h4. @params@ properties
- limit:limit := _100_ maximum number of channels per page to retrieve, up to 1,000 __Type: @Integer@__
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of channel name @String@ values corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods.
+
+ On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result encapsulating an array of channel name @String@ values corresponding to the current page of results. "@PaginatedResult@":/docs/api/realtime-sdk/types#paginated-result supports pagination using "@next()@":/docs/api/realtime-sdk/types#paginated-result and "@first()@":/docs/api/realtime-sdk/types#paginated-result methods.
@@ -380,22 +433,26 @@ h6(#push-channel-sub-save).
default: save
bq(definition).
- default: save("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PushChannelSubscription":#push-channel-subscription channelSubscription))
- ruby: save("PushChannelSubscription":#push-channel-subscription channel_subscription)
- python: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channel_subscription)
- php: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channelSubscription)
- swift,objc: save(channelSubscription: "PushChannelSubscription":#push-channel-subscription, callback: (("PushChannelSubscription":#push-channel-subscription?, ARTErrorInfo?) -> Void)
+ default: save("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PushChannelSubscription":#push-channel-subscription channelSubscription))
+ jsall: save("PushChannelSubscription":#push-channel-subscription subscription): Promise<"PushChannelSubscription":#push-channel-subscription>
+ ruby: save("PushChannelSubscription":#push-channel-subscription channel_subscription)
+ python: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channel_subscription)
+ php: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channelSubscription)
+ swift,objc: save(channelSubscription: "PushChannelSubscription":#push-channel-subscription, callback: (("PushChannelSubscription":#push-channel-subscription?, ARTErrorInfo?) -> Void))
java,android: "PushChannelSubscription":#push-channel-subscription save("PushChannelSubscription":#push-channel-subscription channelSubscription)
Subscribe a device or group of devices sharing a "client identifier":/docs/auth/identified-clients for push notifications published on a channel.
h4. Parameters
-- channelSubscriptionchannel_subscription := a "@PushChannelSubscription@":#push-channel-subscription object
+- channelSubscriptionsubscriptionchannel_subscription := a "@PushChannelSubscription@":#push-channel-subscription object
--
callback
:= is a function of the form: @function(err, channelSubscription)@
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with a "@PushChannelSubscription@":#push-channel-subscription object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
-blang[jsall,swift,objc].
+blang[swift,objc].
h4. Callback result
On success, @channelSubscription@ contains the newly subscribed or updated push channel subscription as a "@PushChannelSubscription@":#push-channel-subscription object.
@@ -406,22 +463,26 @@ h6(#push-channel-sub-remove).
default: remove
bq(definition).
- default: remove("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: remove("PushChannelSubscription":#push-channel-subscription channel_subscription)
- python: remove("PushChannelSubscription":#push-channel-subscription channel_subscription)
- php: remove("PushChannelSubscription":#push-channel-subscription subscription)
- swift,objc: remove(channelSubscription: "PushChannelSubscription":#push-channel-subscription, callback: ((ARTErrorInfo?) -> Void)
+ default: remove("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: remove("PushChannelSubscription":#push-channel-subscription subscription): Promise
+ ruby: remove("PushChannelSubscription":#push-channel-subscription channel_subscription)
+ python: remove("PushChannelSubscription":#push-channel-subscription channel_subscription)
+ php: remove("PushChannelSubscription":#push-channel-subscription subscription)
+ swift,objc: remove(channelSubscription: "PushChannelSubscription":#push-channel-subscription, callback: ((ARTErrorInfo?) -> Void))
java,android: void save("PushChannelSubscription":#push-channel-subscription channelSubscription)
Unsubscribe a device or group of devices sharing a "client identifier":/docs/auth/identified-clients from push notifications on a channel. Requires @push-admin@ permission or, in the case of a subscription associated with a given @deviceId@, @push-subscribe@ permission together with device authentication matching that @deviceId@.
h4. Parameters
-- channelSubscriptionchannel_subscription := a "@PushChannelSubscription@":#push-channel-subscription object
+- channelSubscriptionsubscriptionchannel_subscription := a "@PushChannelSubscription@":#push-channel-subscription object
+
+blang[jsall].
+ h4. Returns
--
callback
:= is a function of the form: @function(err)@
+ Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
-blang[jsall,swift,objc].
+blang[swift,objc].
h4. Callback result
The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.
@@ -433,11 +494,12 @@ h6(#push-channel-sub-remove-where).
ruby,python: remove_where
bq(definition).
- default: removeWhere(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
- ruby: remove_where(Hash params)
- python: remove_where(params=Object)
- php: removeWhere(Array params)
- swift,objc: removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void)
+ default: removeWhere(Object params, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err))
+ jsall: removeWhere(Object params): Promise
+ ruby: remove_where(Hash params)
+ python: remove_where(params=Object)
+ php: removeWhere(Array params)
+ swift,objc: removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) -> Void)
java,android: removeWhere(Param[] params)
Delete all push channel subscriptions matching the @params@ filter. Requires @push-admin@ permission.
@@ -446,15 +508,18 @@ h4. Parameters
- params"Param":#param[] params := an object containing the filter parameters as key value pairs as specified below.
--
callback
:= is a function of the form: @function(err)@
-
h4. @params@ properties
- channel:channel := filter to restrict to subscriptions associated with that @channel@
- clientId:client_id := optional filter to restrict to devices associated with that client identifier. Cannot be used with @deviceId@@:device_id@ param __Type: @String@__
- deviceId:device_id := optional filter to restrict to devices associated with that device identifier. Cannot be used with @clientId@@:client_id@ param __Type: @String@__
-blang[jsall,swift,objc].
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
+blang[swift,objc].
h4. Callback result
The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.
diff --git a/content/partials/types/_push_channel.textile b/content/partials/types/_push_channel.textile
index df42e55641..aa1aa578e1 100644
--- a/content/partials/types/_push_channel.textile
+++ b/content/partials/types/_push_channel.textile
@@ -1,5 +1,4 @@
-
-A @PushChannel@ is a property of a "@RealtimeChannel@":/docs/api/realtime-sdk/channels#properties or "@RestChannel@":/docs/api/rest-sdk/channels#properties. It provides "push devices":/docs/push/index the ability to subscribe and unsubscribe to push notifications on channels.
+A @PushChannel@ is a property of a "@RealtimeChannel@":/docs/api/realtime-sdk/channels#properties or "@RestChannel@":/docs/api/rest-sdk/channels#properties. It provides "push devices":/docs/push the ability to subscribe and unsubscribe to push notifications on channels.
h4. Methods
@@ -8,58 +7,90 @@ h6(#subscribe-device).
bq(definition).
default: subscribeDevice()
+ jsall: subscribeDevice(): Promise
Subscribe your device to the channel's push notifications.
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
h6(#subscribe-client).
default: subscribeClient
bq(definition).
default: subscribeClient()
+ jsall: subscribeClient(): Promise
"Subscribe all devices associated with your device's clientId":/docs/push/publish#sub-channels to the channel's push notifications.
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
h6(#unsubscribe-device).
default: unsubscribeDevice
bq(definition).
default: unsubscribeDevice()
+ jsall: unsubscribeDevice(): Promise
Unsubscribe your device from the channel's push notifications.
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
h6(#unsubscribe-client).
default: unsubscribeClient
bq(definition).
default: unsubscribeClient()
+ jsall: unsubscribeClient(): Promise
"Unsubscribe all devices associated with your device's clientId":/docs/push/publish#sub-channels from the channel's push notifications.
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
h6(#list-subscriptions).
default: listSubscriptions
bq(definition).
+ jsall: listSubscriptions(Record params?): Promise<"PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>>;
java,android: "PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription> listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel)
- objc,swift: listSubscriptions(deviceId: String?, clientId: String?, deviceClientId: String?, `channel: String?, callback: ("ARTPaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>?, ARTErrorInfo?) -> Void)
+ objc,swift: listSubscriptions(deviceId: String?, clientId: String?, deviceClientId: String?, `channel: String?, callback: ("ARTPaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>?, ARTErrorInfo?) -> Void)
Lists push subscriptions on a channel specified by its channel name (@channel@). These subscriptions can be either be a list of client (@clientId@) subscriptions, device (@deviceId@) subscriptions, or if @concatFilters@ is set to @true@, a list of both. This method requires clients to have the "Push Admin capability":push#push-admin. For more information, see @GET rest.ably.io/push/channelSubscriptions@ "Rest API":/docs/api/rest-api.
h4. Parameters
--
deviceId
:= a deviceId to filter by __Type: @String@__
+- deviceId := a deviceId to filter by __Type: @String@__
--
clientId
:= a clientId to filter by __Type: @String@__
+- clientId := a clientId to filter by __Type: @String@__
--
deviceClientId
:= a client ID associated with a device to filter by __Type: @String@__
+- deviceClientId := a client ID associated with a device to filter by __Type: @String@__
-
callback
:= called with a "ARTPaginatedResult":#paginated-result<"PushChannelSubscription":/docs/api/realtime-sdk/push-admin#push-channel-subscription> object or an error
+-
params
:= An optional object containing key-value pairs to filter subscriptions by. Can contain @clientId@, @deviceId@ or a combination of both, and a @limit@ on the number of subscriptions returned, up to 1,000 __Type: @Record@__
+
+blang[jsall].
+ h4. Returns
+
+ Returns a promise. On success, the promise is fulfilled with "@PaginatedResult@":#paginated-result which encapsulates an array of "PushChannelSubscription":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object that details the reason why it was rejected.
+
blang[objc,swift].
h4. Callback result
On success, @resultPage@ contains a "@PaginatedResult@":#paginated-result encapsulating an array of "PushChannelSubscription":/docs/api/realtime-sdk/push-admin#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next()@":#paginated-result and "@first()@":#paginated-result methods.
- On failure to retrieve message history, @err@ contains an "@ErrorInfo@":#error-info object with the failure reason.
+ On failure to retrieve message history, @err@ contains an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object with the failure reason.
blang[java,android].
h4. Returns
@@ -67,4 +98,3 @@ blang[java,android].
On success, the returned "@PaginatedResult@":#paginated-result encapsulates an array of "PushChannelSubscription":#push-channel-subscription objects corresponding to the current page of results. "@PaginatedResult@":#paginated-result supports pagination using "@next@":#paginated-result and "@first@":#paginated-result methods.
Failure to retrieve the message history will raise an "@AblyException@":/docs/api/realtime-sdk/types#ably-exception
-
diff --git a/content/partials/types/_push_channel_subscription.textile b/content/partials/types/_push_channel_subscription.textile
index c26daee5cb..7679031cff 100644
--- a/content/partials/types/_push_channel_subscription.textile
+++ b/content/partials/types/_push_channel_subscription.textile
@@ -11,43 +11,46 @@ h4.
- clientIdclient_id := devices with this "client identifier":/docs/auth/identified-clients are included in this channel subscription. When present, @deviceId@@device_id@ is never present __Type: @String@__
-h3.
- default: PushChannelSubscription constructors
+blang[jsall].
-h6(#push-channel-subscription-for-device).
- default: PushChannelSubscription.forDevice
- ruby: PushChannelSubscription.for_device
+blang[default].
+ h3.
+ default: PushChannelSubscription constructors
-bq(definition).
- default: PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription
- ruby: PushChannelSubscription.for_device(String channel, String device_id) -> PushChannelSubscription
+ h6(#push-channel-subscription-for-device).
+ default: PushChannelSubscription.forDevice
+ ruby: PushChannelSubscription.for_device
-A static factory method to create a @PushChannelSubscription@ object for a channel and single device.
+ bq(definition).
+ default: PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription
+ ruby: PushChannelSubscription.for_device(String channel, String device_id) -> PushChannelSubscription
-h4. Parameters
+ A static factory method to create a @PushChannelSubscription@ object for a channel and single device.
-- channel := channel name linked to this push channel subscription __Type: @String@__
-- deviceIddevice_id := the device with this identifier will be linked with this push channel subscription __Type: @String@__
+ h4. Parameters
-h4. Returns
+ - channel := channel name linked to this push channel subscription __Type: @String@__
+ - deviceIddevice_id := the device with this identifier will be linked with this push channel subscription __Type: @String@__
-A "@PushChannelSubscription@":/docs/api/realtime-sdk/types#push-channel-subscription object
+ h4. Returns
-h6(#push-channel-subscription-for-client-id).
- default: PushChannelSubscription.forClient
- ruby: PushChannelSubscription.for_client
+ A "@PushChannelSubscription@":/docs/api/realtime-sdk/types#push-channel-subscription object
-bq(definition).
- default: PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription
- ruby: PushChannelSubscription.for_client(String channel, String client_id) -> PushChannelSubscription
+ h6(#push-channel-subscription-for-client-id).
+ default: PushChannelSubscription.forClient
+ ruby: PushChannelSubscription.for_client
-A static factory method to create a @PushChannelSubscription@ object for a channel and group of devices sharing a "client identifier":/docs/auth/identified-clients.
+ bq(definition).
+ default: PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription
+ ruby: PushChannelSubscription.for_client(String channel, String client_id) -> PushChannelSubscription
-h4. Parameters
+ A static factory method to create a @PushChannelSubscription@ object for a channel and group of devices sharing a "client identifier":/docs/auth/identified-clients.
-- channel := channel name linked to this push channel subscription __Type: @String@__
-- clientIdclient_id := devices with this "client identifier":/docs/auth/identified-clients are included in the new push channel subscription __Type: @String@__
+ h4. Parameters
-h4. Returns
+ - channel := channel name linked to this push channel subscription __Type: @String@__
+ - clientIdclient_id := devices with this "client identifier":/docs/auth/identified-clients are included in the new push channel subscription __Type: @String@__
-A @PushChannelSubscription@ object
+ h4. Returns
+
+ A @PushChannelSubscription@ object
diff --git a/content/partials/types/_push_device.textile b/content/partials/types/_push_device.textile
index fa7f7d2085..28f761170a 100644
--- a/content/partials/types/_push_device.textile
+++ b/content/partials/types/_push_device.textile
@@ -10,8 +10,23 @@ h6(#activate).
bq(definition).
android: void activate()
objc,swift: activate(callback: ("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?, DeviceDetails?) -> Void)
+ jsall: activate(registerCallback?("DeviceDetails":/docs/api/realtime-sdk/types#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info | null err, "DeviceDetails":/docs/api/realtime-sdk/types#device-details result)), updateFailedCallback?("ErrorInfo":/docs/api/realtime-sdk/types#error-info | null err)): Promise
-Register the device for push. When the "activation process":/docs/push/configure/device#activate-devices is completed, Ably will send a broadcast through the application's "@LocalBroadcastManager@":https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager. Success or failure will be broadcast through @io.ably.broadcast.PUSH_ACTIVATE@call the @(void)didActivateAblyPush:(nullable ARTErrorInfo *)error@@didActivateAblyPush(error: ARTErrorInfo?)@ method from the @ARTPushRegistererDelegate@.
+blang[default].
+ Register the device for push. When the "activation process":/docs/push/configure/device#activate-devices is completed, Ably will send a broadcast through the application's "@LocalBroadcastManager@":https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager. Success or failure will be broadcast through @io.ably.broadcast.PUSH_ACTIVATE@call the @(void)didActivateAblyPush:(nullable ARTErrorInfo *)error@@didActivateAblyPush(error: ARTErrorInfo?)@ method from the @ARTPushRegistererDelegate@.
+
+blang[jsall].
+ "Activates the device":/docs/push/configure/web#activate-browsers for push notifications. Subsequently registers the device with Ably and stores the @deviceIdentityToken@ in local storage.
+
+ h4. Parameters
+
+ - registerCallback := An optional function passed to override the default implementation to register the local device for push activation__Type: @Callable@__
+
+ - updateFailedCallback := An optional callback to be invoked when the device registration failed to update __Type: @Callable@__
+
+ h4. Returns
+
+ Returns a promise. On successful device activation, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected.
h6(#deactivate).
default: deactivate
@@ -19,5 +34,18 @@ h6(#deactivate).
bq(definition).
android: void deactivate()
objc,swift: deactivate(deregisterCallback: ("ARTErrorInfo":/docs/api/realtime-sdk/types#error-info?, deviceId: String?) -> Void)
+ jsall: deactivate(deregisterCallback?("DeviceDetails":/docs/api/realtime-sdk/types#device-details device, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info | null err, String result))): Promise
+
+blang[default].
+ Deregister the device for push. When the deactivation process is completed, Ably will send a broadcast through the application's "@LocalBroadcastManager@":https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager. Success or failure will be broadcast through @io.ably.broadcast.PUSH_DEACTIVATE@call the @(void)didDeactivateAblyPush:(nullable ARTErrorInfo *)error@@didDeactivateAblyPush(error: ARTErrorInfo?)@ method from the@ARTPushRegistererDelegate@.
+
+blang[jsall].
+ Deactivates the device from receiving push notifications.
+
+ h4. Parameters
+
+ - deregisterCallback := An optional function passed to override the default implementation to deregister the local device for push activation__Type: @Callable@__
+
+ h4. Returns
-Deregister the device for push. When the deactivation process is completed, Ably will send a broadcast through the application's "@LocalBroadcastManager@":https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager. Success or failure will be broadcast through @io.ably.broadcast.PUSH_DEACTIVATE@call the @(void)didDeactivateAblyPush:(nullable ARTErrorInfo *)error@@didDeactivateAblyPush(error: ARTErrorInfo?)@ method from the@ARTPushRegistererDelegate@.
+ Returns a promise. On successful device deactivation, the promise resolves. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object that details the reason why it was rejected.
diff --git a/content/partials/types/_realtime_client_options.textile b/content/partials/types/_realtime_client_options.textile
index d67e2ab329..0258dd4e79 100644
--- a/content/partials/types/_realtime_client_options.textile
+++ b/content/partials/types/_realtime_client_options.textile
@@ -17,3 +17,6 @@
- disconnectedRetryTimeoutDisconnectedRetryTimeout:disconnected_retry_timeout := _15,000ms15s_ When the connection enters the @DISCONNECTED@ state, after this delay in millisecondsin secondsas a @NSTimeInterval@, if the state is still @DISCONNECTED@, the client library will attempt to reconnect automatically __Type: @Integer@@NSTimeInterval@__
- suspendedRetryTimeoutSuspendedRetryTimeout:suspended_retry_timeout := _30,000ms30s_ When the connection enters the @SUSPENDED@ state, after this delay in millisecondsin secondsas a @NSTimeInterval@, if the state is still @SUSPENDED@, the client library will attempt to reconnect automatically __Type: @Integer@@NSTimeInterval@__
+
+blang[jsall].
+ - pushServiceWorkerUrl := A URL pointing to a service worker script which is used as the target for web push notifications __Type: @String@__
diff --git a/content/partials/types/_stats.textile b/content/partials/types/_stats.textile
index a70259135e..62ea980410 100644
--- a/content/partials/types/_stats.textile
+++ b/content/partials/types/_stats.textile
@@ -1,6 +1,9 @@
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":/docs/metadata-stats/stats as well as your "application dashboard":https://ably.com/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":https://www.rubydoc.info/gems/ably/Ably/Models/Stats 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.
+
h4.
default: Properties
@@ -8,19 +11,27 @@ h4.
ruby: Attributes
python: Keyword 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@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant@StatsIntervalGranularity enum@@ARTStatsGranularity@@String@__
--
interval_granularityintervalGranularity
:= Deprecated alias for @unit@; scheduled to be removed in version 2.x client library versions. __Type: "@Stats::GRANULARITY@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant@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 a @Stats@ object whose @unit@ is @day@ would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All @Stats@ objects, except those whose @unit@ is @minute@, 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 the @unit@ by looking at the resolution of the @intervalId@. @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 parsed @intervalId@@interval_id@@IntervalId@ (the UTC time at which the time period covered by this @Stats@ object starts) __Type: @Time@@DateTime@@DateTimeOffset@__
-- allAll := aggregate count of both @inbound@ and @outbound@ message stats __Type: "@MessageTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes__
-- apiRequestsapi_requestsApiRequests := breakdown of API requests received via the Ably REST API __Type: "@RequestCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount__
-- channelsChannels := breakdown of channel related stats such as min, mean and peak channels __Type: "@ResourceCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount__
-- connectionsConnections := breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections __Type: "@ConnectionTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic__
-- persistedPersisted := messages persisted and later retrieved via the "history API":/docs/storage-history/history __Type: "@MessageTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes__
-- tokenRequeststoken_requestsTokenRequests := breakdown of Ably Token requests received via the Ably REST API. __Type: "@RequestCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount__
-- pushPush := Detailed stats on push notifications, see "our Push documentation":/docs/push for more details __Type: @PushStats@__
+blang[default].
+ - 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@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity enum@ARTStatsGranularity@@String@__
+ -
interval_granularityintervalGranularity
:= Deprecated alias for @unit@; scheduled to be removed in version 2.x client library versions. __Type: "@Stats::GRANULARITY@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant"@StatsIntervalGranularity@":/docs/api/realtime-sdk/types#stats-granularity 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 a @Stats@ object whose @unit@ is @day@ would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All @Stats@ objects, except those whose @unit@ is @minute@, 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 the @unit@ by looking at the resolution of the @intervalId@. @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 parsed @intervalId@@interval_id@@IntervalId@ (the UTC time at which the time period covered by this @Stats@ object starts) __Type: @Time@@DateTime@@DateTimeOffset@__
+ - allAll := aggregate count of both @inbound@ and @outbound@ message stats __Type: "@MessageTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes__
+ - apiRequestsapi_requestsApiRequests := breakdown of API requests received via the Ably REST API __Type: "@RequestCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount__
+ - channelsChannels := breakdown of channel related stats such as min, mean and peak channels __Type: "@ResourceCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount__
+ - connectionsConnections := breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections __Type: "@ConnectionTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/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@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic__
+ - persistedPersisted := messages persisted and later retrieved via the "history API":/docs/storage-history/history __Type: "@MessageTypes@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes__
+ - tokenRequeststoken_requestsTokenRequests := breakdown of Ably Token requests received via the Ably REST API. __Type: "@RequestCount@":https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount__
+ - pushPush := Detailed stats on push notifications, see "our Push documentation":/push for more details __Type: @PushStats@__
+
+blang[jsall].
+ - appId := the ID of the Ably application the statistics relate to. __Type: @String@__
+ - entries := The statistics for the requested time interval and time period. The @schema@ property provides further information __Type: @Partial>@__
+ - inProgress := Optional. For entires that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format @yyyy-mm-dd:hh:mm:ss@ __Type: @String@__
+ - intervalId := The UTC time period that the stats coverage begins at. If @unit@ was requested as @minute@ this will be in the format @YYYY-mm-dd:HH:MM@, if @hour@ it will be @YYYY-mm-dd:HH@, if @day@ it will be @YYYY-mm-dd:00@ and if @month@ it will be @YYYY-mm-01:00@ __Type: @String@__
+ - schema := The URL of a JSON schema describing the structure of the @Stats@ object __Type: @String@__
diff --git a/content/partials/types/_stats_granularity.textile b/content/partials/types/_stats_granularity.textile
index 33c7b215ca..d61f1bbe35 100644
--- a/content/partials/types/_stats_granularity.textile
+++ b/content/partials/types/_stats_granularity.textile
@@ -1,3 +1,15 @@
+blang[jsall].
+ @StatsIntervalGranularity@ is an enum specifying the granularity of a "@Stats interval@":/docs/api/rest-sdk/statistics#stats-type.
+
+ ```[javascript]
+ const StatsIntervalGranularity = [
+ 'minute',
+ 'hour',
+ 'day',
+ 'month'
+ ]
+ ```
+
blang[swift,objc].
@ARTStatsGranularity@ is an enum specifying the granularity of a "@ARTStats interval@":/docs/api/rest-sdk/statistics#stats-type.
@@ -23,7 +35,7 @@ blang[csharp].
@StatsIntervalGranularity@ is an enum specifying the granularity of a "@Stats interval@":/docs/api/rest-sdk/statistics#stats-type.
```[csharp]
- public enum StatsGranularity
+ public enum StatsIntervalGranularity
{
Minute,
Hour,
diff --git a/content/partials/types/_stats_request_params.textile b/content/partials/types/_stats_request_params.textile
index 547a451dd9..bbbd613b12 100644
--- a/content/partials/types/_stats_request_params.textile
+++ b/content/partials/types/_stats_request_params.textile
@@ -6,5 +6,5 @@ h4. Members
- End := _null_ The end of the queried interval __Type: @DateTimeOffset@__
- Limit := _null_ By default it is null. Limits the number of items returned by history or stats __Type: @Integer@__
- Direction := _Backwards_ Enum which is either @Forwards@ or @Backwards@ __Type: @Direction@ enum__
-- 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__
+- 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@":/docs/api/realtime-sdk/types#stats-granularity 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@__
diff --git a/content/partials/types/_token_revocation_failure_result.textile b/content/partials/types/_token_revocation_failure_result.textile
new file mode 100644
index 0000000000..369e6e3b84
--- /dev/null
+++ b/content/partials/types/_token_revocation_failure_result.textile
@@ -0,0 +1,8 @@
+A @TokenRevocationFailureResult@ contains information about the result of an unsuccessful token revocation request for a single target specifier.
+
+h4.
+ default: Properties
+
+- target := The target specifier __Type: @String@__
+
+- error := Describes the reason for which token revocation failed for the given `target` as an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object __Type: "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info__
diff --git a/content/partials/types/_token_revocation_options.textile b/content/partials/types/_token_revocation_options.textile
new file mode 100644
index 0000000000..fe57c33c97
--- /dev/null
+++ b/content/partials/types/_token_revocation_options.textile
@@ -0,0 +1,8 @@
+A @TokenRevocationOptions@ describes the additional options accepted by revoke tokens request.
+
+h4.
+ default: Properties
+
+- issuedBefore := An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an @issuedBefore@ in the future, or more than an hour in the past, will be rejected __Type: @Number@__
+
+- allowReauthMargin := _false_ If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is @false@, meaning that the effect is near-immediate. __Type: @Boolean@__
diff --git a/content/partials/types/_token_revocation_success_result.textile b/content/partials/types/_token_revocation_success_result.textile
new file mode 100644
index 0000000000..2cee5a8577
--- /dev/null
+++ b/content/partials/types/_token_revocation_success_result.textile
@@ -0,0 +1,10 @@
+A @TokenRevocationSuccessResult@ contains information about the result of a successful token revocation request for a single target specifier.
+
+h4.
+ default: Properties
+
+- target := The target specifier __Type: @String@__
+
+- appliesAt := The time at which the token revocation will take effect, as a Unix timestamp in milliseconds __Type: @Number@__
+
+- issuedBefore := A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked __Type: @Number@__
diff --git a/content/partials/types/_token_revocation_target_specifier.textile b/content/partials/types/_token_revocation_target_specifier.textile
new file mode 100644
index 0000000000..fbbf9e986d
--- /dev/null
+++ b/content/partials/types/_token_revocation_target_specifier.textile
@@ -0,0 +1,8 @@
+A @TokenRevocationTargetSpecifier@ describes which tokens should be affected by a token revocation request.
+
+h4.
+ default: Properties
+
+- type := The type of token revocation target specifier. Valid values include @clientId@, @revocationKey@ and @channel@ __Type: @String@__
+
+- value := The value of the token revocation target specifier __Type: @String@__
diff --git a/src/data/nav/pubsub.ts b/src/data/nav/pubsub.ts
index 44dc1444ef..3430f4058d 100644
--- a/src/data/nav/pubsub.ts
+++ b/src/data/nav/pubsub.ts
@@ -331,7 +331,7 @@ export default {
{
name: 'Push Notifications - Devices',
link: '/docs/api/realtime-sdk/push',
- languages: ['swift', 'objc', 'android'],
+ languages: ['javascript', 'nodejs', 'swift', 'objc', 'android'],
},
{
name: 'Encryption',