<LSClientDelegate > Protocol Reference

Protocol to be implemented to receive LSLightstreamerClient events comprehending notifications of connection activity and errors. More...

#import <LSClientDelegate.h>

Inheritance diagram for <LSClientDelegate >:

Instance Methods
(void)	- clientDidRemoveDelegate:
	Event handler that receives a notification when the LSClientDelegate instance is removed from a LSLightstreamerClient through removeDelegate: (LSLightstreamerClient). More...
(void)	- clientDidAddDelegate:
	Event handler that receives a notification when the LSClientDelegate instance is added to a LSLightstreamerClient through addDelegate: (LSLightstreamerClient). More...
(void)	- client:didReceiveServerError:withMessage:
	Event handler that is called when the Server notifies a refusal on the client attempt to open a new connection or the interruption of a streaming connection. More...
(void)	- client:didChangeStatus:
	Event handler that receives a notification each time the LSLightstreamerClient status has changed. More...
(void)	- client:didChangeProperty:
	Event handler that receives a notification each time the value of a property of LSLightstreamerClient::connectionDetails or LSLightstreamerClient::connectionOptions is changed. More...
(void)	- client:willSendRequestForAuthenticationChallenge:
	Event handler that receives a notificaiton each time the underlying connection is going to request authentication for a challenge in order to proceed. More...

Detailed Description

Protocol to be implemented to receive LSLightstreamerClient events comprehending notifications of connection activity and errors.

Events for these delegates are dispatched by a different thread than the one that generates them. This means that, upon reception of an event, it is possible that the internal state of the client has changed. On the other hand, all the notifications for a single LSLightstreamerClient, including notifications to LSClientDelegate s, LSSubscriptionDelegate s and LSClientMessageDelegate s will be dispatched by the same thread.

Method Documentation

client:didChangeProperty:()

- (void LSClientDelegate) client: (nonnull LSLightstreamerClient *)  client didChangeProperty: (nonnull NSString *)  property

optional

Event handler that receives a notification each time the value of a property of LSLightstreamerClient::connectionDetails or LSLightstreamerClient::connectionOptions is changed.

Properties of these objects can be modified by direct calls to them or by server sent events.

Parameters

client

the LSLightstreamerClient instance.

property

the name of the changed property. Possible values are: adapterSet serverAddress user password serverInstanceAddress serverSocketName sessionId contentLength idleMillis keepaliveMillis maxBandwidth pollingMillis reconnectTimeout stalledTimeout connectTimeout currentConnectTimeout retryDelay firstRetryMaxDelay slowingEnabled forcedTransport serverInstanceAddressIgnored reverseHeartbeatMillis earlyWSOpenEnabled httpExtraHeaders httpExtraHeadersOnSessionCreationOnly

client:didChangeStatus:()

- (void LSClientDelegate) client: (nonnull LSLightstreamerClient *)  client didChangeStatus: (nonnull NSString *)  status

optional

Event handler that receives a notification each time the LSLightstreamerClient status has changed.

The status changes may be originated either by custom actions (e.g. by calling disconnect (LSLightstreamerClient)) or by internal actions. The normal cases are the following:

• After issuing connect (LSLightstreamerClient), if the current status is "DISCONNECTED*", the client will switch to "CONNECTING" first and to "CONNECTED:STREAM-SENSING" as soon as the pre-flight request receives its answer.
  As soon as the new session is established, it will switch to "CONNECTED:WS-STREAMING" if the environment permits WebSockets; otherwise it will switch to "CONNECTED:HTTP-STREAMING" if the environment permits streaming or to "CONNECTED:HTTP-POLLING" as a last resort.
  On the other hand if the status is already "CONNECTED:*" a switch to "CONNECTING" is usually not needed.
• After issuing disconnect (LSLightstreamerClient) , the status will switch to "DISCONNECTED".
• In case of a server connection refusal, the status may switch from "CONNECTING" directly to "DISCONNECTED". After that, the client:didReceiveServerError:withMessage: event handler will be invoked.

Possible special cases are the following:

• In case of Server unavailability during streaming, the status may switch from "CONNECTED:*-STREAMING" to "STALLED" (see LSConnectionOptions::stalledTimeout). If the unavailability ceases, the status will switch back to ""CONNECTED:-STREAMING""; otherwise, if the unavailability persists (see LSConnectionOptions::reconnectTimeout), the status will switch to "CONNECTING" and eventually to "CONNECTED:</em>-STREAMING".
• In case the connection or the whole session is forcibly closed by the Server, the status may switch from "CONNECTED:<em>-STREAMING" or "CONNECTED:</em>-POLLING" directly to "DISCONNECTED". After that, the client:didReceiveServerError:withMessage: event handler will be invoked.
• Depending on the setting in LSConnectionOptions::slowingEnabled, in case of slow update processing, the status may switch from "CONNECTED:WS-STREAMING" to "CONNECTED:WS-POLLING" or from "CONNECTED:HTTP-STREAMING" to "CONNECTED:HTTP-POLLING".
• If the status is "CONNECTED:*POLLING" and any problem during an intermediate poll occurs, the status may switch to "CONNECTING" and eventually to "CONNECTED:POLLING". The same holds for the "CONNECTED:STREAMING" case, when a rebind is needed.
• In case a forced transport was set through LSConnectionOptions::forcedTransport, only the related final status or statuses are possible.
• In case of connection problems the status may switch from any value to "DISCONNECTED:WILL-RETRY" (see LSConnectionOptions::retryDelay).

By setting a custom handler it is possible to perform actions related to connection and disconnection occurrences. Note that connect (LSLightstreamerClient) and disconnect (LSLightstreamerClient), as any other method, can be issued directly from within a handler.

Parameters

client

the LSLightstreamerClient instance.

status

the new status. It can be one of the following values: "CONNECTING" the client has started a connection attempt and is waiting for a Server answer. "CONNECTED:STREAM-SENSING" the client received a first response from the server and is now evaluating if a streaming connection is fully functional. "CONNECTED:WS-STREAMING" a streaming connection over WebSocket has been established. "CONNECTED:HTTP-STREAMING" a streaming connection over HTTP has been established. "CONNECTED:WS-POLLING" a polling connection over WebSocket has been started. Note that, unlike polling over HTTP, in this case only one connection is actually opened (see ConnectionOptions::setSlowingEnabled ). "CONNECTED:HTTP-POLLING" a polling connection over HTTP has been started. "STALLED" a streaming session has been silent for a while, the status will eventually return to its previous CONNECTED:*-STREAMING status or will switch to "DISCONNECTED:WILL-RETRY". "DISCONNECTED:WILL-RETRY" a connection or connection attempt has been closed; a new attempt will be performed after a timeout. "DISCONNECTED" a connection or connection attempt has been closed. The client will not connect anymore until a new connect (LSLightstreamerClient) call is issued.

client:didReceiveServerError:withMessage:()

- (void LSClientDelegate) client: (nonnull LSLightstreamerClient *)  client didReceiveServerError: (NSInteger)  errorCode withMessage: (nullable NSString *)  errorMessage

optional

Event handler that is called when the Server notifies a refusal on the client attempt to open a new connection or the interruption of a streaming connection.

In both cases, the client:didChangeStatus: event handler has already been invoked with a "DISCONNECTED" status and no recovery attempt has been performed. By setting a custom handler, however, it is possible to override this and perform custom recovery actions.

Parameters

client	the LSLightstreamerClient instance.
errorCode	the error code. It can be one of the following: 1 - user/password check failed 2 - requested Adapter Set not available 7 - licensed maximum number of sessions reached (this can only happen with some licenses) 8 - configured maximum number of sessions reached 9 - configured maximum server load reached 10 - new sessions temporarily blocked 11 - streaming is not available because of Server license restrictions (this can only happen with special licenses) 30-39 - the current connection or the whole session has been closed by external agents; the possible cause may be: The session was closed by the administrator, through JMX (32) or through a "destroy" request (31); The Metadata Adapter imposes limits on the overall open sessions for the current user and has requested the closure of the current session upon opening of a new session for the same user on a different browser window (35); An unexpected error occurred on the Server while the session was in activity (33, 34); An unknown or unexpected cause; any code different from the ones identified in the above cases could be issued. A detailed description for the specific cause is currently not supplied (i.e. errorMessage is nil in this case). 61 - there was an error in the parsing of the server response thus the client cannot continue with the current session. <= 0 - the Metadata Adapter has refused the user connection; the code value is dependent on the specific Metadata Adapter implementation
errorMessage	the description of the error as sent by the Server.

client:willSendRequestForAuthenticationChallenge:()

- (void LSClientDelegate) client: (nonnull LSLightstreamerClient *)  client willSendRequestForAuthenticationChallenge: (nonnull NSURLAuthenticationChallenge *)  challenge

optional

Event handler that receives a notificaiton each time the 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:.
Note that if more than one delegate is added to the same client, only the first one implementing this method will be notified of this event.
Note also that this notification is called directly from the network thread. The method implementation should be fast and nonblocking. Any slow operations should have been performed in advance.

Parameters

client	the LSLightstreamerClient instance.
challenge	The challenge that the client must authenticate in order to proceed with its request.

clientDidAddDelegate:()

- (void LSClientDelegate) clientDidAddDelegate: (nonnull LSLightstreamerClient *)  client

optional

Event handler that receives a notification when the LSClientDelegate instance is added to a LSLightstreamerClient through addDelegate: (LSLightstreamerClient).

This is the first event to be fired on the delegate.

Parameters

client

the LSLightstreamerClient this instance was added to.

clientDidRemoveDelegate:()

- (void LSClientDelegate) clientDidRemoveDelegate: (nonnull LSLightstreamerClient *)  client

optional

Event handler that receives a notification when the LSClientDelegate instance is removed from a LSLightstreamerClient through removeDelegate: (LSLightstreamerClient).

This is the last event to be fired on the delegate.

Parameters

client

the LSLightstreamerClient this instance was removed from.

---

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

• LSClientDelegate.h