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

Introduction

A session represents a single connection to a single Diffusion server.

The Quick Start guide provides basic instructions on how to get connected to a Diffusion server.

Also see:

See Also
PTDiffusionSessionStateChange
Since
5.6
Inheritance diagram for PTDiffusionSession:

Class Methods

(instancetype) + NS_UNAVAILABLE
 
(void) + openWithURL:configuration:completionHandler:
 
(void) + openWithURL:completionHandler:
 
(NSString *) + anonymousPrincipal
 
(NSString *) + allFixedProperties
 
(NSString *) + allUserProperties
 
(NSString *) + rolesPropertyKey
 
(NSString *) + sessionIdPropertyKey
 
(NSString *) + principalPropertyKey
 
(NSString *) + connectorPropertyKey
 
(NSString *) + transportPropertyKey
 
(NSString *) + clientTypePropertyKey
 
(NSString *) + countryPropertyKey
 
(NSString *) + languagePropertyKey
 
(NSString *) + serverNamePropertyKey
 
(NSString *) + clientIPPropertyKey
 
(NSString *) + latitudePropertyKey
 
(NSString *) + longitudePropertyKey
 
(NSString *) + startTimePropertyKey
 

Properties

PTDiffusionSessionConfigurationconfiguration
 
PTDiffusionSessionIdsessionId
 
NSString * principal
 
PTDiffusionSessionStatestate
 
id< PTDiffusionErrorListenererrorListener
 
PTDiffusionTopicsFeaturetopics
 
PTDiffusionTopicControlFeaturetopicControl
 
PTDiffusionTopicUpdateControlFeaturetopicUpdateControl
 
PTDiffusionTopicUpdateFeaturetopicUpdate
 
PTDiffusionMessagingFeaturemessaging
 
PTDiffusionMessagingControlFeaturemessagingControl
 
PTDiffusionSecurityFeaturesecurity
 
PTDiffusionPingsFeaturepings
 
PTDiffusionTimeSeriesFeaturetimeSeries
 
PTDiffusionTopicNotificationsFeaturetopicNotifications
 
PTDiffusionSubscriptionControlFeaturesubscriptionControl
 
PTDiffusionTopicViewsFeaturetopicViews
 

Instance Methods

(instancetype) - NS_UNAVAILABLE
 
(void) - close
 
(PTDiffusionSessionLockAttempt *) - lockWithName:completionHandler:
 
(PTDiffusionSessionLockAttempt *) - lockWithName:scope:completionHandler:
 

Method Documentation

+ (NSString *) allFixedProperties

This constant can be used instead of a property key in requests for session property values to indicate that all fixed session properties are required.

Since
6.0
+ (NSString *) allUserProperties

This constant can be used instead of a property key in requests for session property values to indicate that all user defined session properties are required.

Since
6.0
+ (NSString *) anonymousPrincipal

Value assigned to the principal property if this is an anonymous session.

Since
6.0
+ (NSString *) clientIPPropertyKey

Session property key for client IP address.

Since
6.2
+ (NSString *) clientTypePropertyKey

Session property key for client type.

Since
6.2
- (void) close

Close the session. Once closed a session cannot be restarted.

Since
5.6
+ (NSString *) connectorPropertyKey

Session property key for connector name.

Since
6.2
+ (NSString *) countryPropertyKey

Session property key for country code.

Since
6.2
+ (NSString *) languagePropertyKey

Session property key for language code.

Since
6.2
+ (NSString *) latitudePropertyKey

Session property key for client latitude.

Since
6.2
- (PTDiffusionSessionLockAttempt *) lockWithName: (NSString *)  name
completionHandler: (PTDiffusionSessionLock *_Nullable)  lock
(NSError *_Nullable error)  completionHandler 

Attempt to acquire a session lock.

The completion handler block will be called with the requested lock if the server assigns it to the session. Otherwise, the completion handler block will be called with an error indicating why the lock could not be acquired.

Acquiring the lock can take an arbitrarily long time if other sessions are competing for the lock. The server will retain the session's request for the lock until it is assigned to the session, the session is closed, or the session cancels the CompletableFuture.

A session can call this method multiple times. If the lock is acquired, all calls will complete successfully with equal SessionLocks.

Calling cancel on the returned PTDiffusionCancellable has no effect on other pending calls to acquire this lock.

Upon successful acquisition, the session owns the lock and is responsible for unlocking it. When calling cancel on the returned PTDiffusionCancellable, take care that it has not already completed by checking the return value. The following Swift code releases the lock if the request could not be canceled.

let attempt = session.lock(withName: "my-lock") { (lock, error) in
    / / ..
}

if (!attempt.cancel()) {
    attempt.lock?.unlock() { (wasOwned, error) in }
}

A session that acquires a lock will remain its owner until it is unlocked or the session closes. The variant of this methods that takes a scope parameter provides the further option of releasing the lock when the session loses its connection to the server.

Access control

To allow fine-grained access control, lock names are interpreted as path names, controlled with the ACQUIRE_LOCK topic permission. This allows permission to be granted to a session to acquire the lock update-topic/a while preventing the session from acquiring the lock update-topic/b, for example.

Parameters
nameThe name of the session lock.
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.

If this session has successfully acquired the session lock, or this session already owns the session lock, the completion handler will be called with the lock instance.

If the completion handler is called with an error to indicate failure, this session does not own the session lock. Common reasons for failure include:

  • The calling session does not have the AQUIRE_LOCK permission for this lock name.
  • The session is closed.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
See Also
- lockWithName:scope:completionHandler:
Since
6.3
- (PTDiffusionSessionLockAttempt *) lockWithName: (NSString *)  name
scope: (PTDiffusionSessionLockScope *)  scope
completionHandler: (PTDiffusionSessionLock *_Nullable)  lock
(NSError *_Nullable error)  completionHandler 

Variant of lockWithName:completionHandler: that provides control over when a lock will be released.

If called with unlockOnSessionLoss (PTDiffusionSessionLockScope), this method behaves exactly like lockWithName:completionHandler:.

If called with unlockOnConnectionLoss (PTDiffusionSessionLockScope), any lock that is returned will be unlocked if the session loses its connection to the server. This is useful to allow another session to take ownership of the lock while this session is reconnecting.

Parameters
nameThe name of the session lock
scopePreferred scope. The scope of a lock controls when it will be released automatically. If a session makes multiple requests for a lock using different scopes, and the server assigns the lock to the session fulfilling the requests, the lock will be given the weakest scope (unlockOnConnectionLoss (PTDiffusionSessionLockScope)).
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.
See Also
- lockWithName:completionHandler:
Since
6.3
+ (NSString *) longitudePropertyKey

Session property key for client longitude.

Since
6.2
+ (void) openWithURL: (NSURL *)  url
completionHandler: (PTDiffusionSession *_Nullable)  session
(NSError *_Nullable error)  completionHandler 

Starts asynchronously connecting to a Diffusion server using the default session configuration.

Parameters
urlThe location of the server to connect to. Encapsulates host, port and protocol to use. Must be absolute.
completionHandlerThe completion handler to call on connection success or failure. The completion handler will be called from the main dispatch queue and will only be called once.
Note
Your completion handler must store a strong reference to the session instance in order for it to remain open.
The completion handler block is called after the session's state property has been set to connected but before those observing through the notification center are informed.
Since
5.6
+ (void) openWithURL: (NSURL *)  url
configuration: (PTDiffusionSessionConfiguration *)  configuration
completionHandler: (PTDiffusionSession *_Nullable)  session
(NSError *_Nullable error)  completionHandler 

Starts asynchronously connecting to a Diffusion server using the given session configuration.

Parameters
urlThe location of the server to connect to. Encapsulates host, port and protocol to use. Must be absolute.
configurationThe configuration options to connect with.
completionHandlerThe completion handler to call on connection success or failure. The completion handler will be called from the main dispatch queue and will only be called once.
Note
Your completion handler must store a strong reference to the session instance in order for it to remain open.
The completion handler block is called after the session's state property has been set to connected but before those observing through the notification center are informed.
Since
5.6
+ (NSString *) principalPropertyKey

Session property key for principal.

Since
6.2
+ (NSString *) rolesPropertyKey

Session property key for session roles.

Since
6.2
+ (NSString *) serverNamePropertyKey

Session property key for server name.

Since
6.2
+ (NSString *) sessionIdPropertyKey

Session property key for session identifier.

See Also
PTDiffusionSessionId
Since
6.2
+ (NSString *) startTimePropertyKey

Session property key for client start time.

Since
6.2
+ (NSString *) transportPropertyKey

Session property key for transport.

Since
6.2

Property Documentation

- (PTDiffusionSessionConfiguration*) configuration
readnonatomiccopy

The configuration used to open the session.

Since
5.6
- (id<PTDiffusionErrorListener>) errorListener
readwritenonatomicweak

The delegate to use to report unexpected, non-fatal errors to.

Since
6.0
- (PTDiffusionMessagingFeature*) messaging
readnonatomicassign

The Messaging feature provides messaging capabilities.

Since
5.6
- (PTDiffusionMessagingControlFeature*) messagingControl
readnonatomicassign

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

Since
6.0
- (PTDiffusionPingsFeature*) pings
readnonatomicassign

The Pings feature provides a client session with the ability to test the roundtrip time associated with sending a request to the server and receiving the associated response.

Since
5.7
- (NSString*) principal
readnonatomicassign

The name of the security principal associated with the session.

Returns
The principal name. If the session has no associated principal, it is known as an anonymous session, in which case the empty string anonymousPrincipal will be assigned to this property.
Since
6.0
- (PTDiffusionSecurityFeature*) security
readnonatomicassign

The Security feature provides a client session with the ability to change the associated principal.

Since
5.6
- (PTDiffusionSessionId*) sessionId
readnonatomicassign

The unique identifier for the session as assigned by the server it connects to.

This property is Key-Value Observable with changes being notified on the main dispatch queue.

- (PTDiffusionSessionState*) state
readnonatomicassign

The current state of the session.

This property is Key-Value Observable with changes being notified on the main dispatch queue. KVO notifications are sent before the invocation of any callback handler blocks.

Note
Session state can also be observed using the notification center. See PTDiffusionSessionStateChange for details.
Since
5.7
- (PTDiffusionSubscriptionControlFeature*) subscriptionControl
readnonatomicassign

The Subscription Control feature allows a client session to subscribe or unsubscribe other sessions to topics, as well as also providing a mechanism for handling requests to subscribe to routing topics.

Since
6.1
- (PTDiffusionTimeSeriesFeature*) timeSeries
readnonatomicassign

The Time Series feature provides a client session with the ability to update and query time series topics.

Since
6.0
- (PTDiffusionTopicControlFeature*) topicControl
readnonatomicassign

The Topic Control features provides the capability to manage topics.

Since
5.7
- (PTDiffusionTopicNotificationsFeature*) topicNotifications
readnonatomicassign

The Topic Notifications feature allows a client session to receive notifications about changes to selected topics.

Since
6.1
- (PTDiffusionTopicsFeature*) topics
readnonatomicassign

The Topics feature provides the capability to receive streamed topic updates and/or fetch the state of topics.

Since
5.6
- (PTDiffusionTopicUpdateFeature*) topicUpdate
readnonatomicassign

The Topic Update feature provides a client session with the ability to update topics.

Since
6.3
- (PTDiffusionTopicUpdateControlFeature*) topicUpdateControl
readnonatomicassign

The Topic Update Control feature provides the capability to update topics.

Deprecated:
Since 6.3. PTDiffusionTopicUpdateControlFeature has been replaced by PTDiffusionTopicUpdateFeature, which provides equivalent and additional functionality such as conditional updates. This property will be removed in a future release.
Since
5.7
- (PTDiffusionTopicViewsFeature*) topicViews
readnonatomicassign

The Topic Views feature allows a client session to manage topic views.

Since
6.3