Lightstreamer OS X Client  1.2.4
Native OS X Client library for Lightstreamer
Instance Methods | List of all members
<LSConnectionDelegate> Protocol Reference

The LSConnectionDelegate protocol receives notifications of connection activity and errors. More...

#import <LSConnectionDelegate.h>

Inheritance diagram for <LSConnectionDelegate>:

Instance Methods

(void) - clientConnection:didStartSessionWithPolling:
 Notification that the session has been successfully opened. More...
 
(void) - clientConnection:didReceiveNewBytes:
 Notification that the connection received new bytes from the Server. More...
 
(void) - clientConnection:didChangeActivityWarningStatus:
 Notification that the connection did enter or did exit a stalled state. More...
 
(void) - clientConnectionDidEstablish:
 Notification that the connection has been established. More...
 
(void) - clientConnectionDidClose:
 Notification that the connection did close. More...
 
(void) - clientConnection:didEndWithCause:
 Notification that the connection did end due to a Server-side decision. More...
 
(void) - clientConnection:didReceiveDataError:
 Notification that a block of data received from the Server could not be correctly interpreted. More...
 
(void) - clientConnection:didReceiveServerFailure:
 Notification that an unrecoverable exception signaled by the Server has been received. More...
 
(void) - clientConnection:didReceiveConnectionFailure:
 Notification that an unrecoverable connection error has been detected. More...
 
(void) - clientConnection:didSucceedChangingDeviceTokenOnServerWithInfo:
 Notification that the device token has been successully changed on the Server. More...
 
(void) - clientConnection:didFailChangingDeviceTokenOnServerWithError:
 Notification that the device token change has been tried on the Server and failed. More...
 
(void) - clientConnectionDidSucceedResettingBadgeOnServer:
 Notification that the application's icon badge has been successfully reset on the Server. More...
 
(void) - clientConnection:didFailResettingBadgeOnServerWithError:
 Notification that an application's icon badge reset has been tried on the server and failed. More...
 
(void) - clientConnection:willSendRequestForAuthenticationChallenge:
 Notification that the LSClient's underlying connection is going to request authentication for a challenge in order to proceed. More...
 
(void) - clientConnection:isAboutToSendURLRequest:
 Notification that the LSClient is going to submit an URL request. More...
 

Detailed Description

The LSConnectionDelegate protocol receives notifications of connection activity and errors.


Note: almost all notifications are sent in sequence on a dedicated thread. Only notifications regarding client authentication and request decoration are called directly from the session thread. See clientConnection:willSendRequestForAuthenticationChallenge: (LSConnectionDelegate-p) and clientConnection:isAboutToSendURLRequest: (LSConnectionDelegate-p) for more information.

Method Documentation

- (void) clientConnection: (LSClient *)  client
didChangeActivityWarningStatus: (BOOL)  warningStatus 
optional

Notification that the connection did enter or did exit a stalled state.

"Stalled" means that the LSClient object did not receive any new bytes for more then the probeWarningSecs specified on the LSConnectionInfo object when opening the connection. It may be a simptom of an impending connection drop.

Parameters
clientThe LSClient object that handles the connection.
warningStatusYES if the connection did enter a stalled state, NO otherwise.
- (void) clientConnection: (LSClient *)  client
didEndWithCause: (int)  cause 
optional

Notification that the connection did end due to a Server-side decision.

When this notification is received the LSClient will stop trying to reconnect automatically. See the "END" message in the text protocol documentation for details on the possible causes.

Parameters
clientThe LSClient object that handles the connection.
causeSpecifies the cause that led the Server to close the connection.
- (void) clientConnection: (LSClient *)  client
didFailChangingDeviceTokenOnServerWithError: (LSException *)  error 
optional

Notification that the device token change has been tried on the Server and failed.

The change attempt is the consequence of a previous invocation of registrationForMPNSucceededWithToken: (LSClient). Note that the token change may fail in two situations that not necessarily denote an error condition:

  • if there were no active MPN subscriptions related to this device and application;
  • if too much time has passed since the old device token was invalidated by APNS Feedback Service.

In both cases, the error reported is an LSPushServerException with error code 45 (device unknown).

Parameters
clientThe LSClient object that handles the connection.
errorThe specific error that caused the device token change to fail.
- (void) clientConnection: (LSClient *)  client
didFailResettingBadgeOnServerWithError: (LSException *)  error 
optional

Notification that an application's icon badge reset has been tried on the server and failed.

The reset attempt is the consequence of a previous invocation of applicationMPNBadgeReset (LSClient):.

Parameters
clientThe LSClient object that handles the connection.
errorThe specific error that caused the badge reset to fail.
- (void) clientConnection: (LSClient *)  client
didReceiveConnectionFailure: (LSPushConnectionException *)  failure 
optional

Notification that an unrecoverable connection error has been detected.

Unless the connection is manually closed, the LSClient will automatically try to reconnect.

Parameters
clientThe LSClient object that handles the connection.
failureThe specific error that has been detected.
- (void) clientConnection: (LSClient *)  client
didReceiveDataError: (LSPushUpdateException *)  error 
optional

Notification that a block of data received from the Server could not be correctly interpreted.

Parameters
clientThe LSClient object that handles the connection.
errorThe specific exception that explains the error.
- (void) clientConnection: (LSClient *)  client
didReceiveNewBytes: (int)  bytesLength 
optional

Notification that the connection received new bytes from the Server.

Parameters
clientThe LSClient object that handles the connection.
bytesLengthThe number of bytes received
- (void) clientConnection: (LSClient *)  client
didReceiveServerFailure: (LSPushServerException *)  failure 
optional

Notification that an unrecoverable exception signaled by the Server has been received.

Unless the connection is manually closed, the LSClient will automatically try to reconnect.

Parameters
clientThe LSClient object that handles the connection.
failureThe specific exception that has been received.
- (void) clientConnection: (LSClient *)  client
didStartSessionWithPolling: (BOOL)  polling 
optional

Notification that the session has been successfully opened.

This notification is received just once per session, i.e. in a polled connection will be received only once. Anyway, it may be received more than once if the LSClient has to reconnect due to external reasons (e.g. connection drops).

Parameters
clientThe LSClient object that handles the connection.
pollingTells if the session is in streaming mode or polling mode.
- (void) clientConnection: (LSClient *)  client
didSucceedChangingDeviceTokenOnServerWithInfo: (LSMPNTokenChangeInfo *)  info 
optional

Notification that the device token has been successully changed on the Server.

The change attempt is the consequence of a previous invocation of registrationForMPNSucceededWithToken: (LSClient). If the device token had been invalidated by the APNS Feedback Service, it is now valid again and all associated MPN subscriptions have been automatically reactivated from suspended state.

Parameters
clientThe LSClient object that handles the connection.
infoAdditional information about the device token change (such as the number of reactivated MPN subscriptions).
- (void) clientConnection: (LSClient *)  client
isAboutToSendURLRequest: (NSMutableURLRequest *)  urlRequest 
optional

Notification that the LSClient is going to submit an URL request.

It gives a chance to decorate the request before it is sent to the server, e.g. to set a specific header field or cookie policy.
Note: this notification is called directly from the session thread. The method implementation should be fast and nonblocking. Any slow operations should have been performed in advance.
Warning: implement this notification only if you know what you are doing. Arbitrary changes to the URL request content may lead to connection malfunctioning.

Parameters
clientThe LSClient object that handles the connection.
urlRequestThe URL request being sent.
- (void) clientConnection: (LSClient *)  client
willSendRequestForAuthenticationChallenge: (NSURLAuthenticationChallenge *)  challenge 
optional

Notification that the LSClient's underlying connection is going to request authentication for a challenge in order to proceed.

If the delegate implements this method, the connection will suspend until [challenge sender] is called with one of the following methods:

  • useCredential:forAuthenticationChallenge:,
  • continueWithoutCredentialForAuthenticationChallenge:,
  • cancelAuthenticationChallenge:,
  • performDefaultHandlingForAuthenticationChallenge: or
  • rejectProtectionSpaceAndContinueWithChallenge:.

If not implemented, the default behavior will call performDefaultHandlingForAuthenticationChallenge: on the [challenge sender].
Note: this notification is called directly from the session thread. The method implementation should be fast and nonblocking. Any slow operations should have been performed in advance.

Parameters
clientThe LSClient object that handles the connection.
challengeThe challenge that the client must authenticate in order to proceed with its request.
- (void) clientConnectionDidClose: (LSClient *)  client
optional

Notification that the connection did close.

It may be received only after a call to closeConnection on the LSClient object.

Parameters
clientThe LSClient object that handles the connection.
- (void) clientConnectionDidEstablish: (LSClient *)  client
optional

Notification that the connection has been established.

This notification is received each time the LSClient reconnects automatically, even if on the same session. I.e., in a polled connection will be received at each poll cycle. It may also be received more than once also if the LSClient has to reconnect due to external reasons (e.g. connection drops).

Parameters
clientThe LSClient object that handles the connection.
- (void) clientConnectionDidSucceedResettingBadgeOnServer: (LSClient *)  client
optional

Notification that the application's icon badge has been successfully reset on the Server.

The reset attempt is the consequence of a previous invocation of applicationMPNBadgeReset (LSClient):.

Parameters
clientThe LSClient object that handles the connection.

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