 |
Diffusion Apple API
6.5.13
Unified Client Library for iOS, tvOS and OS X / macOS
|
|
Diffusion Apple API
6.5.13
Unified Client Library for iOS, tvOS and OS X / macOS
|
This feature provides a client session with request-response messaging capabilities that can be used to implement application services.
Request-response messaging allows a session to send requests to other sessions. Each receiving session provides a corresponding response, which is returned to the sending session. Each request and response carries an application provided value.
The method used to send a request determines which sessions will receive it. Each request is routed using the provided message path – an application provided string. Two addressing schemes are provided: unaddressed requests* and addressed requests.
A session can provide an application service by implementing a handler and registering it with the server. This is somewhat similar to implementing a REST service, except that interactions between the sender and receiver are asynchronous.
Unaddressed requests sent using sendRequest are routed by the server to a handler that has been pre-registered by another session, and matches the message path.
Handlers are registered with addRequestHandler. Each session may register at most one handler for a given message path. Optionally, one or more session property names can be provided (see PTDiffusionSession for a full description of session properties), in which case the values of the session properties for each recipient session will be returned along with its response. To add a request handler, the control client session must have registerHandler (PTDiffusionGlobalPermission) permission. If registering to receive session property values, the session must also have viewSession (PTDiffusionGlobalPermission) permission.
Routing works as follows:
Registration works across a cluster of servers. If no matching handler is registered on the server to which the sending session is connected, the request will be routed to another server in the cluster that has one.
Addressed requests provide a way to perform actions on a group of sessions, or to notify sessions of one-off events (for repeating streams of events, use a topic instead).
An addressed request can be sent to a set of sessions using sendRequest:toFilter:completionHandler:. For the details of session filters, see PTDiffusionSession. Sending a request to a filter will match zero or more sessions. Each response received will be passed to the provided completionHandler. As a convenience, an addressed request can be sent a specific session using the overloaded variant of sendRequest:toSessionId:completionHandler that accepts a session id.
Sending an addressed request requires sendToSession (PTDiffusionPathPermission) permission.
If the sending session is connected to a server belonging to a cluster, the recipient sessions can be connected to other servers in the cluster. The filter will be evaluated against all sessions hosted by the cluster.
To receive addressed requests, a session must set up a local request stream to handle the specific message path, using setRequestStream:forPath:. When a request is received for the message path, the method diffusionStream:didReceive...Request:responder from the PTDiffusionStreamDelegate is triggered. The session should respond using the provided responder. Stream delegates receive a diffusionDidCloseStream: callback when unregistered and a diffusionStream:didFailOnError: if the session is closed.
If a request is sent to a session that does not have a matching stream for the message path, an error will be returned to the sending session.
Obtain this feature from a PTDiffusionSession as follows:
PTDiffusionMessagingFeature * messaging = session.messaging;
For more detail, see: Messaging with the Apple client library.
Additional Inherited Members | |
 Properties inherited from PTDiffusionFeature | |
| PTDiffusionSession * | session |
| - (void) addRequestHandler: | (PTDiffusionRequestHandler *) | handler | |
| forPath: | (NSString *) | path | |
| completionHandler: | (PTDiffusionTopicTreeRegistration *_Nullable) | registration | |
| (NSError *_Nullable error) | completionHandler | ||
Register a request handler to handle requests from other client session for a branch of the message path hierarchy.
Each control session may register a single handler for a branch. When the handler is no longer required, it may be closed using the PTDiffusionTopicTreeRegistration provided by the completionHandler. To change the handler for a particular branch the previous handler must first be closed.
This is equivalent to calling addRequestHandler:forPath:requestClass:responseClass:sessionProperties:completionHandler: with an empty array for session properties.
| handler | Specifies the handler to be registered at the server. |
| path | The request path. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | If any argument is nil. |
Implemented in PTDiffusionMessagingControlFeature.
| - (void) addRequestHandler: | (PTDiffusionRequestHandler *) | handler | |
| forPath: | (NSString *) | path | |
| sessionProperties: | (NSArray< NSString * > *) | sessionProperties | |
| completionHandler: | (PTDiffusionTopicTreeRegistration *_Nullable) | registration | |
| (NSError *_Nullable error) | completionHandler | ||
Register a request handler to handle messages received from other client sessions on a path.
| handler | Specifies the handler to be registered at the server. |
| path | The request path. |
| sessionProperties | a list of keys of session properties that should be supplied with each message. See PTDiffusionSession for a full list of available fixed property keys. To request no properties supply an empty list. To request all fixed properties include [PTDiffusionSession allFixedProperties] as a key. In this case any other fixed property keys would be ignored. To request all user properties include [PTDiffusionSession allUserProperties] as a key. In this case any other user properties are ignored. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | If any argument is nil. |
Implemented in PTDiffusionMessagingControlFeature.
| - (nullable PTDiffusionRequestStream *) removeRequestStreamForPath: | (NSString *) | path |
Remove the request stream mapped to the given path.
| path | The path for which any request stream mapping should be removed. |
nil if there was not an existing dispatch mapping.| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toFilter: | (NSString *) | filter | |
| path: | (NSString *) | path | |
| responseStream: | (PTDiffusionSessionResponseStream *) | responseStream | |
| completionHandler: | (NSUInteger) | count | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to all sessions that satisfy a given session filter.
| request | The request to send. |
| filter | The session filter expression. |
| path | The path to send the request to. |
| responseStream | The stream that will handle the incoming responses. The delegate associated with this stream will be sent messages asynchronously on the main dispatch queue. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. Success indicates that the server has dispatched all the requests. |
nil for the error argument and zero for the count argument if no client sessions matched the filter.| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toPath: | (NSString *) | path | |
| binaryCompletionHandler: | (PTDiffusionBinary *_Nullable) | binary | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request for which a binary response is expected.
The message will be routed to an appropriately registered control handler for the given path.
| request | The request to send. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Provided by category PTDiffusionMessagingFeature(PTDiffusionBinary).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toPath: | (NSString *) | path | |
| doubleFloatNumberCompletionHandler: | (NSNumber *_Nullable) | number | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request for which a double-precision floating point (Eight-byte IEEE 754) response is expected.
The message will be routed to an appropriately registered control handler for the given path.
| request | The request to send. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toPath: | (NSString *) | path | |
| int64NumberCompletionHandler: | (NSNumber *_Nullable) | number | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request for which a 64-bit integer response is expected.
The message will be routed to an appropriately registered control handler for the given path.
| request | The request to send. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toPath: | (NSString *) | path | |
| JSONCompletionHandler: | (PTDiffusionJSON *_Nullable) | json | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request for which a JSON response is expected.
The message will be routed to an appropriately registered control handler for the given path.
| request | The request to send. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Provided by category PTDiffusionMessagingFeature(PTDiffusionJSON).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toPath: | (NSString *) | path | |
| recordCompletionHandler: | (PTDiffusionRecordV2 *_Nullable) | record | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request for which a record response is expected.
The message will be routed to an appropriately registered control handler for the given path.
| request | The request to send. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Provided by category PTDiffusionMessagingFeature(PTDiffusionRecordV2).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toPath: | (NSString *) | path | |
| stringCompletionHandler: | (NSString *_Nullable) | string | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request for which a string response is expected.
The message will be routed to an appropriately registered control handler for the given path.
| request | The request to send. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toSessionId: | (PTDiffusionSessionId *) | sessionId | |
| path: | (NSString *) | path | |
| binaryCompletionHandler: | (PTDiffusionBinary *_Nullable) | binary | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to a session for which a binary response is expected.
| request | The request to send. |
| sessionId | The session to send the request to. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
Provided by category PTDiffusionMessagingFeature(PTDiffusionBinary).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toSessionId: | (PTDiffusionSessionId *) | sessionId | |
| path: | (NSString *) | path | |
| doubleFloatNumberCompletionHandler: | (NSNumber *_Nullable) | string | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to a session for which a double-precision floating point (Eight-byte IEEE 754) response is expected.
| request | The request to send. |
| sessionId | The session to send the request to. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toSessionId: | (PTDiffusionSessionId *) | sessionId | |
| path: | (NSString *) | path | |
| int64NumberCompletionHandler: | (NSNumber *_Nullable) | string | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to a session for which a 64-bit integer response is expected.
| request | The request to send. |
| sessionId | The session to send the request to. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toSessionId: | (PTDiffusionSessionId *) | sessionId | |
| path: | (NSString *) | path | |
| JSONCompletionHandler: | (PTDiffusionJSON *_Nullable) | json | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to a session for which a JSON response is expected.
| request | The request to send. |
| sessionId | The session to send the request to. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
Provided by category PTDiffusionMessagingFeature(PTDiffusionJSON).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toSessionId: | (PTDiffusionSessionId *) | sessionId | |
| path: | (NSString *) | path | |
| recordCompletionHandler: | (PTDiffusionRecordV2 *_Nullable) | record | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to a session for which a record response is expected.
| request | The request to send. |
| sessionId | The session to send the request to. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
Provided by category PTDiffusionMessagingFeature(PTDiffusionRecordV2).
| - (void) sendRequest: | (PTDiffusionRequest *) | request | |
| toSessionId: | (PTDiffusionSessionId *) | sessionId | |
| path: | (NSString *) | path | |
| stringCompletionHandler: | (NSString *_Nullable) | string | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to a session for which a string response is expected.
| request | The request to send. |
| sessionId | The session to send the request to. |
| path | The path to send the request to. |
| completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue. |
| NSInvalidArgumentException | Raised if any supplied arguments are nil. |
Implemented in PTDiffusionMessagingControlFeature.
Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).
| - (nullable PTDiffusionRequestStream *) setRequestStream: | (PTDiffusionRequestStream *) | stream | |
| forPath: | (NSString *) | path | |
Assign the request stream to handle requests sent to the given path.
| stream | The request stream which should be mapped to receive requests sent to the given path. |
| path | The path for which received requests should be dispatched to the given request stream. |
nil if this is a fresh dispatch mapping.
1.8.5