Lightstreamer iOS Client  1.4.5
Native iOS Client library for Lightstreamer
Instance Methods | Class Methods | Properties | List of all members
LSMPNSubscription Class Reference

The LSMPNSubscription class wraps the key (as an LSMPNKey object) and the specifications (as an LSMPNInfo object) of a mobile push notifications (MPN) subscription. More...

#import <LSMPNSubscription.h>

Inheritance diagram for LSMPNSubscription:

Instance Methods

(id) - initWithKey:info:
 Initializes an LSMPNSubscription object with the specified parameters. More...
 
(LSMPNStatusInfo *) - checkStatus
 Inquires the status of the MPN subscription on the Server. More...
 
(LSMPNStatusInfo *) - checkStatus:
 Inquires the status of the MPN subscription on the Server. More...
 
(void) - modify:
 Modifies the specifications of the MPN subscription. More...
 
(BOOL) - modify:error:
 Modifies the specifications of the MPN subscription. More...
 
(void) - deactivate
 Deactivates the MPN subscription. More...
 
(BOOL) - deactivate:
 Deactivates the MPN subscription. More...
 

Class Methods

(LSMPNSubscription *) + mpnSubscriptionWithKey:info:
 Creates and returns an LSMPNSubscription object with the specified parameters. More...
 

Properties

LSClientclient
 The LSClient instance that originated (i.e. More...
 
LSMPNKeympnKey
 The MPN key identifying this MPN subscription. More...
 
LSMPNInfompnInfo
 The specifications of this MPN subscription. More...
 
BOOL deactivated
 Tells if this MPN subscription has been deactivated or not. More...
 

Detailed Description

The LSMPNSubscription class wraps the key (as an LSMPNKey object) and the specifications (as an LSMPNInfo object) of a mobile push notifications (MPN) subscription.

It represents a view on the actual MPN subscription stored on the Server's database. The LSMPNSubscription class supports operations like checking its current status, modifying the specifications and deactivating the MPN subscription.
MPN subscriptions are cached locally and the cache is stored in the LSClient instance that originated (i.e. activated or inquired) the MPN subscription. Thus, once an LSMPNSubscription object, with a certain MPN key, has been obtained from an LSCLient instance, any operation returning the same MPN subscription from the same LSClient instance will return the same LSMPNSubscription instance. On the other hand, deactivating an MPN subscription removes it from the local cache and marks its corresponding LSMPNSubscription instance as deactivated.
Moreover, the LSClient local cache survives a reconnection: if the LSClient reconnects (automatically or manually) with the same base parameters (i.e. LSConnectionInfo::pushServerURL, LSConnectionInfo::adapter and LSConnectionInfo::user), the MPN subscription cache is preserved. If one of these parameters changes, the cache is cleared and any dangling LSMPNSubscription instance is made invalid (no more operations will be possible on it).
LSMPNSubscription instances keep a reference to their originating LSClient, see client. In order for any operation to be successful, the originating LSClient must be connected at the moment the operation is executed.
Note that, while the LSMPNkey instance is constant, the LSMPNInfo instance may be replaced by calls that modify the MPN subscription's specifications, e.g. modify: (LSMPNSubscription), or activateMPN:coalescing: (LSClient) with coalescing flag set, or by calls that update the local cache from the Server, e.g. inquireMPN: (LSClient), inquireMPNsWithStatus: (LSClient) and inquireAllMPNs (LSClient).
Since MPN subscriptions are stored on the Server on a per-device and per-app basis, under normal conditions only the device/app pair that created an MPN subscription may be accessing or modifying it or its cached LSMPNSubscription representation.

Method Documentation

- (LSMPNStatusInfo *) checkStatus

Inquires the status of the MPN subscription on the Server.


If the MPN subscription has been forcibly deactivated on the Server, the call will result in a LSPushServerException with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
Note that the status of an MPN subscription is never cached.
The method is blocking if executed outside of a batch, otherwise it is non-blocking: outside of a batch, it will return only after receiving the Server response. Inside a batch, the method will return immediately with nil, but the request will be processed only on batch commit (see commitBatch (LSClient)).

Returns
The MPN subscription status info, i.e. whether it is active or triggered, and the time when the status has been set. Contains also status info about the MPN device, i.e. whether it is active or suspended and the corresponding time.
Exceptions
LSPushClientExceptionThrown in case the MPN subscription has been deactivated, or in case the context is invalid (e.g. can't obtain a valid device token or app ID).
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (LSMPNStatusInfo *) checkStatus: (NSError *__autoreleasing *)  error

Inquires the status of the MPN subscription on the Server.

Non-exception-throwing variant of checkStatus, see for more information.

Parameters
errorIn case of error, upon return contains an NSError object that describes the problem.
Returns
The MPN subscription status info, i.e. whether it is active or triggered, and the time when the status has been set. Contains also status info about the MPN device, i.e. whether it is active or suspended and the corresponding time.
Exceptions
LSPushClientExceptionThrown in case the MPN subscription has been deactivated, or in case the context is invalid (e.g. can't obtain a valid device token or app ID).
- (void) deactivate

Deactivates the MPN subscription.

Once deactivated, no more mobile push (i.e. remote) notifications will be sent on table update. A deactivation has also the effect of deleting the MPN subscription.
If the MPN subscription has been forcibly deactivated on the Server, the call will result in a LSPushServerException with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
Note that MPN subscriptions are cached locally, see LSMPNSubscription description for more information. This method always contacts the Server and updates the related MPN subscription in the local cache.
The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server response. Inside a batch, the method will return immediately but the request will be processed only on batch commit (see commitBatch (LSClient)).

Exceptions
LSPushClientExceptionThrown in case the MPN subscription has already been deactivated, or in case the context is invalid (e.g. can't obtain a valid device token or app ID).
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (BOOL) deactivate: (NSError *__autoreleasing *)  error

Deactivates the MPN subscription.

Non-exception-throwing variant of deactivate, see for more information.

Parameters
errorIn case of error, upon return contains an NSError object that describes the problem.
Returns
YES if the MPN subscription could be deactivated, NO if it couldn't. In the latter case, an error is provided.
Exceptions
LSPushClientExceptionThrown in case the MPN subscription has already been deactivated, or in case the context is invalid (e.g. can't obtain a valid device token or app ID).
- (id) initWithKey: (LSMPNKey *)  mpnKey
info: (LSMPNInfo *)  mpnInfo 

Initializes an LSMPNSubscription object with the specified parameters.


This initializer is for internal use only.

Parameters
mpnKeyKey of the MPN subscription (see LSMPNKey for more information).
mpnInfoSpecifications of the MPN subscription. An unmodifiable copy of the object is stored internally.
- (void) modify: (LSMPNInfo *)  mpnInfo

Modifies the specifications of the MPN subscription.

Once the change has been submitted to the server, the mpnInfo property is updated with the passed mpnInfo instance, whereas the MPN key remains unchanged.
If the MPN subscription has been forcibly deactivated on the Server, the call will result in a LSPushServerException with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
The operation works only on the current MPN subscription (i.e. the MPN subscription identified by the MPN key). No coalescence is possible with this operation: even if the new specifications had the same adapter set, data adapter, group, schema and trigger expression of another MPN subscription, this MPN subscription would remain distinct. See activateMPN:coalescing: (LSClient) for more information on coalescence.
The same limitations that apply during activation (see activateMPN:coalescing: (LSClient)) apply during modification. Additionally, moving MPN subscriptions from an adapter set to another is not allowed. This means the LSTableInfo::adapterSet field must be the same of the original MPN subscription AND the same of the current connection. If this field is nil, the adapter set of the current connection is considered as specified.
Note that MPN subscriptions are cached locally, see LSMPNSubscription description for more information. This method always contacts the Server and updates the related MPN subscription in the local cache.
The method is blocking if executed outside of a batch, otherwise it is non-blocking: outside of a batch, it will return only after receiving the Server response. Inside a batch, the method will return immediately, but the request will be processed only on batch commit (see commitBatch (LSClient)).

Parameters
mpnInfoContains the new table and format specifications of the mobile push notifications. An unmodifiable copy of the object is stored internally.
Exceptions
LSPushClientExceptionThrown in case the MPN subscription has been deactivated, or in case the context is invalid (e.g. can't obtain a valid device token or app ID).
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (BOOL) modify: (LSMPNInfo *)  mpnInfo
error: (NSError *__autoreleasing *)  error 

Modifies the specifications of the MPN subscription.

Non-exception-throwing variant of modify:, see for more information.

Parameters
mpnInfoContains the new table and format specifications of the mobile push notifications. An unmodifiable copy of the object is stored internally.
errorIn case of error, upon return contains an NSError object that describes the problem.
Returns
YES if the MPN subscription could be modified, NO if it couldn't. In the latter case, an error is provided.
Exceptions
LSPushClientExceptionThrown in case the MPN subscription has been deactivated, or in case the context is invalid (e.g. can't obtain a valid device token or app ID).
+ (LSMPNSubscription *) mpnSubscriptionWithKey: (LSMPNKey *)  mpnKey
info: (LSMPNInfo *)  mpnInfo 

Creates and returns an LSMPNSubscription object with the specified parameters.


This factory method is for internal use only.

Parameters
mpnKeyKey of the MPN subscription (see LSMPNKey for more information).
mpnInfoSpecifications of the MPN subscription. An unmodifiable copy of the object is stored internally.

Property Documentation

- (LSClient*) client
readnonatomicweak

The LSClient instance that originated (i.e.

activated or inquired) this LSMPNSubscription instance.

- (BOOL) deactivated
readnonatomicassign

Tells if this MPN subscription has been deactivated or not.

May be changed by deactivation calls, e.g. deactivate, or deactivateMPNsWithStatus: (LSClient) and deactivateAllMPNs (LSClient), or by calls that update the local cache from the Server, e.g. inquireMPN: (LSClient) and inquireAllMPNs (LSClient).
See the LSMPNSubscription description for more information.

- (LSMPNInfo*) mpnInfo
readnonatomicassign

The specifications of this MPN subscription.

The returned object is unmodifiable: trying to change one of its properties causes an LSPushClientException to be raised.
The stored object may be replaced over time by calls that modify the MPN subscription's specifications, e.g. modify:, or activateMPN:coalescing: (LSClient) with coalescing flag set, or by calls that update the local cache from the Server, e.g. inquireMPN: (LSClient), inquireMPNsWithStatus: (LSClient) and inquireAllMPNs (LSClient).
See the LSMPNSubscription description for more information.

- (LSMPNKey*) mpnKey
readnonatomicassign

The MPN key identifying this MPN subscription.


The documentation for this class was generated from the following file: