Diffusion Apple API  6.2.0
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Functions Variables Properties Pages
Instance Methods | List of all members
PTDiffusionMessagingControlFeature Class Reference

Introduction

The Messaging Control feature provides a client session with the ability to use messaging functionality to communicate directly with other client sessions.

The Messaging Control feature for a session can be obtained from the session's messagingControl property.

For more detail, see: Messaging with the Apple client library.

See Also
PTDiffusionSession
Since
6.0
Inheritance diagram for PTDiffusionMessagingControlFeature:
PTDiffusionFeature

Instance Methods

(void) - addMessageHandlerForPath:withDelegate:sessionProperties:completionHandler:
 
(void) - addMessageHandlerForPath:withDelegate:completionHandler:
 
(void) - addRequestHandler:forPath:sessionProperties:completionHandler:
 
(void) - addRequestHandler:forPath:completionHandler:
 
(void) - sendToSessionId:path:message:options:completionHandler:
 
(void) - sendToSessionId:path:message:completionHandler:
 
(void) - sendToFilter:path:message:options:completionHandler:
 
(void) - sendToFilter:path:message:completionHandler:
 
(void) - sendRequest:toFilter:path:responseStream:completionHandler:
 
(void) - sendRequest:toSessionId:path:binaryCompletionHandler:
 
(void) - sendRequest:toSessionId:path:JSONCompletionHandler:
 
(void) - sendRequest:toSessionId:path:stringCompletionHandler:
 
(void) - sendRequest:toSessionId:path:doubleFloatNumberCompletionHandler:
 
(void) - sendRequest:toSessionId:path:int64NumberCompletionHandler:
 
(void) - sendRequest:toSessionId:path:recordCompletionHandler:
 
- Instance Methods inherited from PTDiffusionFeature
(instancetype) - NS_UNAVAILABLE
 

Additional Inherited Members

- Class Methods inherited from PTDiffusionFeature
(instancetype) + NS_UNAVAILABLE
 
- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (void) addMessageHandlerForPath: (NSString *)  path
withDelegate: (id< PTDiffusionMessageDelegate >)  delegate
completionHandler: (PTDiffusionTopicTreeRegistration *_Nullable)  registration
(NSError *_Nullable error)  completionHandler 

Register a message handler to handle messages received from other client sessions for a branch of the path hierarchy.

This is equivalent to calling addMessageHandler:forPath:sessionProperties:completionHandler: with an empty array for session properties.

Parameters
delegateSpecifies the delegate for all messages sent on paths below and including the specified branch (unless overridden by a handler registered against a more specific branch).
pathIdentifies a branch in the path hierarchy.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (void) addMessageHandlerForPath: (NSString *)  path
withDelegate: (id< PTDiffusionMessageDelegate >)  delegate
sessionProperties: (NSArray< NSString * > *)  sessionProperties
completionHandler: (PTDiffusionTopicTreeRegistration *_Nullable)  registration
(NSError *_Nullable error)  completionHandler 

Register a message handler to handle messages received from other client sessions for a branch of the path hierarchy.

The handler will be invoked for paths below and including the specified path to which messages have been sent. This will only receive messages sent from a client (for example by one of the send methods in the PTDiffusionMessagingFeature) and not any updates to topics that are bound to the same paths.

Each control session can register a single handler for a branch. When the handler is no longer required, it can be closed using the close method (see PTDiffusionTopicTreeRegistration). To change the handler for a particular branch the previous handler must first be closed.

Parameters
delegateSpecifies the delegate for all messages sent on paths below and including the specified branch (unless overridden by a handler registered against a more specific branch).
pathIdentifies a branch in the path hierarchy.
sessionPropertiesa 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.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (void) addRequestHandler: (PTDiffusionRequestHandler *)  handler
forPath: (NSString *)  path
completionHandler: (PTDiffusionTopicTreeRegistration *_Nullable)  registration
(NSError *_Nullable error)  completionHandler 

Register a request handler to handle messages received from other client sessions on a path.

This is equivalent to calling addRequestHandler:forPath:requestClass:responseClass:sessionProperties:completionHandler: with an empty array for session properties.

Parameters
handlerSpecifies the handler to be registered at the server.
pathThe request path.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.0
- (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.

Parameters
handlerSpecifies the handler to be registered at the server.
pathThe request path.
sessionPropertiesa 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.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.0
- (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.

Parameters
requestThe request to send.
filterThe session filter expression.
pathThe path to send the request to.
responseStreamThe stream that will handle the incoming responses. The delegate associated with this stream will be sent messages asynchronously on the main dispatch queue.
completionHandlerBlock 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.
Note
The completion handler block will be invoked with a nil for the error argument and zero for the count argument if no client sessions matched the filter.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.1
- (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.

Parameters
requestThe request to send.
sessionIdThe session to send the request to.
pathThe path to send the request to.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingControlFeature(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.

Parameters
requestThe request to send.
sessionIdThe session to send the request to.
pathThe path to send the request to.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingControlFeature(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.

Parameters
requestThe request to send.
sessionIdThe session to send the request to.
pathThe path to send the request to.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingControlFeature(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.

Parameters
requestThe request to send.
sessionIdThe session to send the request to.
pathThe path to send the request to.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingControlFeature(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.

Parameters
requestThe request to send.
sessionIdThe session to send the request to.
pathThe path to send the request to.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingControlFeature(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.

Parameters
requestThe request to send.
sessionIdThe session to send the request to.
pathThe path to send the request to.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingControlFeature(PTDiffusionPrimitive).

- (void) sendToFilter: (NSString *)  filter
path: (NSString *)  path
message: (PTDiffusionBytes *)  message
completionHandler: (NSUInteger)  count
(NSError *_Nullable error)  completionHandler 

Send a message to all sessions that satisfy a given session filter using a specific path.

This is equivalent to calling sendToFilter:path:message:options:completionHandler: with default options.

Parameters
filterThe session filter expression.
pathThe message path that the message is to be associated with.
messageThe message to send.
completionHandlerBlock 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 count argument indicates the number of clients that satisfied the filter and to which the message was sent. On failure the error argument passed to the block will not be nil and the count argument will be zero. The completion handler will be called asynchronously on the main dispatch queue.
Note
The completion handler block will be invoked with a nil for the error argument and zero for the count argument if no client sessions matched the filter.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (void) sendToFilter: (NSString *)  filter
path: (NSString *)  path
message: (PTDiffusionBytes *)  message
options: (PTDiffusionSendOptions *)  options
completionHandler: (NSUInteger)  count
(NSError *_Nullable error)  completionHandler 

Send a message to all sessions that satisfy a given session filter using a specific path.

See PTDiffusionSession for a full description of filter expressions.

Parameters
filterThe session filter expression.
pathThe message path that the message is to be associated with.
messageThe message to send.
optionsMessage options, including headers and priority.
completionHandlerBlock 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 count argument indicates the number of clients that satisfied the filter and to which the message was sent. On failure the error argument passed to the block will not be nil and the count argument will be zero. The completion handler will be called asynchronously on the main dispatch queue.
Note
The completion handler block will be invoked with a nil for the error argument and zero for the count argument if no client sessions matched the filter.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (void) sendToSessionId: (PTDiffusionSessionId *)  sessionId
path: (NSString *)  path
message: (PTDiffusionBytes *)  message
completionHandler: (NSError *_Nullable error)  completionHandler 

Send a message to a session using a specific path.

This is equivalent to calling sendToSessionId:path:message:options:completionHandler: with default options.

Parameters
sessionIdIdentifies the session to which the message will be sent.
pathThe message path that the message is to be associated with.
messageThe message to send.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (void) sendToSessionId: (PTDiffusionSessionId *)  sessionId
path: (NSString *)  path
message: (PTDiffusionBytes *)  message
options: (PTDiffusionSendOptions *)  options
completionHandler: (NSError *_Nullable error)  completionHandler 

Send a message to a session using a specific path.

Parameters
sessionIdIdentifies the session to which the message will be sent.
pathThe message path that the message is to be associated with.
messageThe message to send.
optionsMessage options, including headers and priority.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0