Maximum number of HTTP streaming connections that can be concurrently opened to the same Server (host and port).

Since each LSLightstreamerClient instance may open a single streaming connection, either with HTTP or WebSocket, the limit is applied between all LSLightstreamerClient instances currently running. The limit counts only for HTTP connections, and is enforced to prevent the saturation of the system’s HTTP connection pool. WebSocket connections make no use of the system’s HTTP connection pool and hence are not subject to this limit.

See maxConcurrentSessionsPerServerExceededPolicy for the policy to be applied when the limit is reached. The maximum value is 4 on iOS and tvOS, 6 on macOS. Trying to set a higher value will clip it to the maximum.

Note: this is a class property.

Default: 2 on iOS and tvOS; 3 on macOS.

Lifecycle: the property can be changed at any time, but active connections that are in excess of the value will not be closed. The value is only checked during the execution of the [LSLightstreamerClient connect] method.

Related notifications: a change to this setting will NOT be notified through a call to [LSClientDelegate client:didChangeProperty:].

Extra time, expressed in seconds, the client is allowed to wait for a response to a request before dropping the connection and try with a different approach.

It can either be a fixed value, in which case the same timeout is always used, or the string auto meaning that the library might change this timeout at will. In this case it is possible to check the current value with the the currentConnectTimeout property.

Streaming: The timeout is applied on any attempt to setup the streaming connection. If after the timeout no data has arrived on the stream connection, the client may automatically switch transport or may resort to a polling connection.

Polling and pre-flight request: The timeout is applied to every connection. If after the timeout no data has arrived on the polling connection, the entire connection process restarts from scratch.

Format: a decimal number (e.g. 2.0), or auto.

Default: auto.

Lifecycle: this property can be changed at any time.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument connectTimeout on any LSClientDelegate listening to the related LSLightstreamerClient.

Extra time the client is allowed to wait for a response to a request before dropping the connection and try with a different approach.

If connectTimeout is set to auto this value might be later changed by the library, on the other hand if connectTimeout is configured to a fixed value this value will have no effect.

Default: 4 seconds.

Lifecycle: this property can be changed at any time.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument currentConnectTimeout on any LSClientDelegate listening to the related LSLightstreamerClient.

Length, expressed in bytes, to be used by the Server for the response body on a HTTP stream connection (a minimum length, however, is ensured by the server).

After the content length exhaustion, the connection will be closed and a new bind connection will be automatically reopened.

Note: this setting only applies to the HTTP-STREAMING case (i.e. not to WebSockets).

Default: A length decided by the library, to ensure the best performance. It can be of a few MB or much higher, depending on the environment.

Lifecycle: the content length should be set on the [LSLightstreamerClient connectionOptions] object before calling the [LSLightstreamerClient connect] method. However, the property can be changed at any time: the supplied value will be used for the next HTTP bind request.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument contentLength on any LSClientDelegate listening to the related LSLightstreamerClient.

Maximum time the client will wait before opening a new session in case the previous one is unexpectedly closed while correctly working.

The actual delay is a randomized value between 0 and this value. This randomization might help avoid a load spike on the cluster due to simultaneous r econnections, should one of the active servers be stopped. Note that this delay is only applied before the first reconnection: should such reconnection fail the setting of retryDelay is applied.

Default: 0.1 seconds

Lifecycle: this property can be changed at any time.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument firstRetryMaxDelay on any LSClientDelegate listening to the related LSLightstreamerClient.

Value of the forced transport (if any), that can be used to disable/enable the Stream-Sense algorithm and to force the client to use a fixed transport or a fixed combination of a transport and a connection type.

When a combination is specified the Stream-Sense algorithm is completely disabled.

The property can be used to switch between streaming and polling connection types and between HTTP and WebSocket transports.

In some cases, the requested status may not be reached, because of connection or environment problems. In that case the client will continuously attempt to reach the configured status(es).

Note that if the Stream-Sense algorithm is disabled, the client may still enter the CONNECTED:STREAM-SENSING status; however, in that case, if it eventually finds out that streaming is not possible, no recovery will be tried.

Platform limitations: On watchOS the WebSocket transport is not available.

Default: nil (full Stream-Sense enabled).

Lifecycle: this property can be changed at any time. If called while the client is connecting or connected it will instruct to switch connection type to match the given configuration.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument forcedTransport on any LSClientDelegate listening to the related LSLightstreamerClient.

Enables/disables the setting of extra HTTP headers to all the request performed to the Lightstreamer server by the client.

Note that the Content-Type header is reserved by the client library itself, while other headers might be refused by the environment and others might cause the connection to the server to fail. For instance, you cannot use this property to specify custom cookies to be sent to Lightstreamer Server; leverage [LSLightstreamerClient addCookies:forURL:] instead. The use of custom headers might also cause the client to send an OPTIONS request to the server before opening the actual connection.

Default: nil (meaning no extra headers are sent).

Lifecycle: this property can be changed at any time: each request will carry headers accordingly to the most recent setting. Note that if extra headers are specified while a WebSocket is open, the requests will continue to be sent through the WebSocket and thus this setting will be ignored until a new session starts.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument HTTPExtraHeaders on any LSClientDelegate listening to the related LSLightstreamerClient.

Maximum time the Server is allowed to wait for any data to be sent in response to a polling request, if none has accumulated at request time.

Setting this time to a nonzero value and the polling interval to zero leads to an “asynchronous polling” behaviour, which, on low data rates, is very similar to the streaming case. Setting this time to zero and the polling interval to a nonzero value, on the other hand, leads to a classical “synchronous polling”.

Note that the Server may, in some cases, delay the answer for more than the supplied time, to protect itself against a high polling rate or because of bandwidth restrictions. Also, the Server may impose an upper limit on the wait time, in order to be able to check for client-side connection drops.

Default: 19 seconds.

Lifecycle: the idle timeout should be set on the [LSLightstreamerClient connectionOptions] object before calling the [LSLightstreamerClient connect] method. However, the property can be changed at any time: the supplied value will be used for the next polling request (this only applies to the *-POLLING cases).

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument idleTimeout on any LSClientDelegate listening to the related LSLightstreamerClient.

Interval between two keepalive packets sent by Lightstreamer Server on a stream connection when no actual data is being transmitted.

The Server may, however, impose a lower limit on the keepalive interval, in order to protect itself. Also, the Server may impose an upper limit on the keepalive interval, in order to be able to check for client-side connection drops. If 0 is specified, the interval will be decided by the Server.

Default: 0 (meaning that the Server will send keepalive packets based on its own configuration).

Lifecycle: the keepalive interval should be set on the [LSLightstreamerClient connectionOptions] object before calling the [LSLightstreamerClient connect] method. However, the property can be changed at any time: the supplied value will be used for the next bind request (this only applies to the *-STREAMING cases).

Note that, if the value has just been set and a connection to Lightstreamer Server has not been established yet, the returned value is the time that is being requested to the Server. Afterwards, the returned value is the time used by the Server, that may be different, because of Server side constraints.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument keepaliveInterval on any LSClientDelegate listening to the related LSLightstreamerClient.

Maximum bandwidth, expressed in kilobit/sec, that can be consumed for the data coming from Lightstreamer Server, as requested for this session.

The maximum bandwidth limit really applied by the Server on the session is provided by realMaxBandwidth.

A limit on bandwidth may already be posed by the Metadata Adapter, but the client can furtherly restrict this limit. The limit applies to the bytes received in each streaming or polling connection. The string unlimited is also allowed, to mean that the maximum bandwidth can be entirely decided on the Server side (the check is case insensitive).

Note: bandwidth control is an optional feature, available depending on Edition and License Type.

Format: a decimal number (e.g. 5.0), or unlimited.

Default: unlimited.

Lifecycle: this property can changed at any time. If a connection is currently active, the bandwidth limit for the connection is changed on the fly. Remember that the Server may apply a different limit.

Note that, if the value has just been set and a connection to Lightstreamer Server has not been established yet, the returned value is the bandwidth limit that is being requested to the Server.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument requestedMaxBandwidth on any LSClientDelegate listening to the related .

Moreover, upon any change or attempt to change the limit, the Server will notify the client and such notification will be received through a call to [LSClientDelegate client:didChangeProperty:] with argument realMaxBandwidth on any ClientListener listening to the related LSLightstreamerClient.

The maximum bandwidth, expressed in kilobit/sec, that can be consumed for the data coming from Lightstreamer Server.

This is the actual maximum bandwidth, in contrast with requestedMaxBandwidth. The value may differ from the requested one because of restrictions operated on the server side, or because bandwidth management is not supported (in this case it is always unlimited), but also because of number rounding.

Format: a decimal number (e.g. 5.0), or unlimited.

Lifecycle: if a connection to Lightstreamer Server is not currently active, nil is returned; soon after the connection is established, the value becomes available, as notified by a call to [LSClientDelegate client:didChangeProperty:] with argument realMaxBandwidth.

Related notifications: when the value becomes available, a notification is sent with call to [LSClientDelegate client:didChangeProperty:] with argument realMaxBandwidth on any LSClientDelegate listening to the related LSLightstreamerClient.

Polling interval used for polling connections.

The client switches from the default streaming mode to polling mode when the client network infrastructure does not allow streaming. Also, polling mode can be forced by setting forcedTransport to WS-POLLING or HTTP-POLLING.

The polling interval affects the rate at which polling requests are issued. It is the time between the start of a polling request and the start of the next request. However, if the polling interval expires before the first polling request has returned, then the second polling request is delayed. This may happen, for instance, when the Server delays the answer because of the idle timeout setting. In any case, the polling interval allows for setting an upper limit on the polling frequency.

The Server does not impose a lower limit on the client polling interval. However, in some cases, it may protect itself against a high polling rate by delaying its answer. Network limitations and configured bandwidth limits may also lower the polling rate, despite of the client polling interval.

The Server may, however, impose an upper limit on the polling interval, in order to be able to promptly detect terminated polling request sequences and discard related session information.

Default: 0 (pure “asynchronous polling” is configured).

Lifecycle: the polling interval should be set on the [LSLightstreamerClient connectionOptions] object before calling the [LSLightstreamerClient connect] method. However, the property can be changed at any time: the supplied value will be used for the next bind request (this only applies to the *-POLLING cases).

Note that, if the value has just been set and a polling request to Lightstreamer Server has not been performed yet, the returned value is the polling interval that is being requested to the Server. After each polling request, the value may be changed to the one imposed by the Server.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument pollingInterval on any LSClientDelegate listening to the related LSLightstreamerClient.

Time the client, after entering STALLED status, can wait for a keepalive packet or any data on a stream connection, before disconnecting and trying to reconnect to the Server.

Default: 3 seconds.

Lifecycle: this property can be changed at any time.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument reconnectTimeout on any LSClientDelegate listening to the related LSLightstreamerClient.

Time the client can wait before opening a new session in case the previous one failed to open or was closed before it became stable.

Note that the delay is calculated from the moment the effort to create a new connection is made, not from the moment the failure is detected or the connection timeout expired.

Default: 5 seconds.

Lifecycle: this property can be changed at any time.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument retryDelay on any LSClientDelegate listening to the related LSLightstreamerClient.

Reverse-heartbeat interval on the control connection.

If the given value equals 0 then the reverse-heartbeat mechanism will be disabled; otherwise if the given value is greater than 0 the mechanism will be enabled with the specified interval.

When the mechanism is active, the client will ensure that there is at most the specified interval between a control request and the following one, by sending empty control requests (the “reverse heartbeats”) if necessary.

This can serve various purposes:

• Preventing the communication infrastructure from closing an inactive socket that is ready for reuse for more HTTP control requests, to avoid connection reestablishment overhead. However it is not guaranteed that the connection will be kept open, as the underlying TCP implementation may open a new socket each time a HTTP request needs to be sent. Note that this will be done only when a session is in place.

• Allowing the Server to detect when a streaming connection or Websocket is interrupted but not closed. In these cases, the client eventually closes the connection, but the Server cannot see that (the connection remains “half-open”) and just keeps trying to write. This is done by notifying the timeout to the Server upon each streaming request. For long polling, the idleTimeout setting has a similar function.

• Allowing the Server to detect cases in which the client has closed a connection in HTTP streaming, but the socket is kept open by some intermediate node, which keeps consuming the response. This is also done by notifying the timeout to the Server upon each streaming request, whereas, for long polling, the idleTimeout setting has a similar function.

Default: 0 (meaning that the mechanism is disabled).

Lifecycle: this setting should be performed before calling the [LSLightstreamerClient connect] method. However, the value can be changed at any time: the setting will be obeyed immediately, unless a higher heartbeat frequency was notified to the Server for the current connection. The setting will always be obeyed upon the next connection (either a bind or a brand new session).

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument reverseHeartbeatInterval on any LSClientDelegate listening to the related LSLightstreamerClient.

Extra time the client can wait when an expected keepalive packet has not been received on a stream connection (and no actual data has arrived), before entering the STALLED status.

Default: 2 seconds.

Lifecycle: This property can be changed at any time.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument stalledTimeout on any LSClientDelegate listening to the related LSLightstreamerClient.

Enables/disables the “early-open” of the WebSocket connection to the address specified in [LSConnectionDetails serverAddress].

When enabled a WebSocket is open to the address specified through [LSConnectionDetails serverAddress] before a potential server instance address is received during session creation. In this case if a server instance address is received, the previously open WebSocket is closed and a new one is open to the received server instance address.

If disabled, the session creation is completed to verify if such a server instance address is configured in the server before opening the WebSocket.

For these reasons this setting should be set to NO if the server specifies a <control_link_address> in its configuration; viceversa it should be set to YES if such element is not set on the target server(s) configuration.

Note: server clustering is an optional feature, available depending on Edition and License Type.

Platform limitations: On watchOS the WebSocket transport is not available. This property has no effect.

Default: YES.

Lifecycle: this property can be changed at any time. If called while the client already owns a session it will be applied the next time a session is requested to a server.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument earlyWSOpenEnabled on any LSClientDelegate listening to the related LSLightstreamerClient.

Policy to be applied during the [LSLightstreamerClient connect] execution if there are already maxConcurrentSessionsPerServer HTTP streaming sessions open to the same Server (host and port).

Possible values are:

• USE-POLLING: The client switches to a forced HTTP polling mode, with idle timeout set to 0 seconds and polling interval set to 1 second (change to the polling timeout is applied only if it is currently lower). Switching to polling mode tries to avoid the exhaustion of the system-wide connection pool (typically sized 4 on iOS and 6 on macOS) by leaving the connection reusable by this and other clients.

• BLOCK: The client aborts the [LSLightstreamerClient connect] call by throwing an exception.

• NONE: No action is taken. If the system-wide connection pool is exhausted, the [LSLightstreamerClient connect] call may timeout unexpectedly.

Default: NONE

Lifecycle: this property can be changed at any time. The value is only checked during the execution of the [LSLightstreamerClient connect] method.

Related notifications: a change to this setting will NOT be notified through a call to [LSClientDelegate client:didChangeProperty:].

Enables/disables a restriction on the forwarding of the extra http headers specified through HTTPExtraHeaders.

If YES, said headers will only be sent during the session creation process (and thus will still be available to the metadata adapter notifyUser method) but will not be sent on following requests. On the contrary, when set to YES, the specified extra headers will be sent to the server on every request.

Default: NO.

Lifecycle: this property can be changed at any time enabling/disabling the sending of headers on future requests.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument HTTPExtraHeadersOnSessionCreationOnly on any LSClientDelegate listening to the related LSLightstreamerClient.

Disable/enable the automatic handling of server instance address that may be returned by the Lightstreamer server during session creation.

In fact, when a Server cluster is in place, the Server address specified through [LSConnectionDetails serverAddress] can identify various Server instances; in order to ensure that all requests related to a session are issued to the same Server instance, the Server can answer to the session opening request by providing an address which uniquely identifies its own instance.

Setting this value to YES permits to ignore that address and to always connect through the address supplied in serverAddress. This may be needed in a test environment, if the Server address specified is actually a local address to a specific Server instance in the cluster.

Note: server clustering is an optional feature, available depending on Edition and License Type.

Default: NO.

Lifecycle: this property can be changed at any time. If called while connected, it will be applied when the next session creation request is issued.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument serverInstanceAddressIgnored on any LSClientDelegate listening to the related LSLightstreamerClient.

Turns on or off the slowing algorithm.

This heuristic algorithm tries to detect when the client CPU is not able to keep the pace of the events sent by the Server on a streaming connection. In that case, an automatic transition to polling is performed.

In polling, the client handles all the data before issuing the next poll, hence a slow client would just delay the polls, while the Server accumulates and merges the events and ensures that no obsolete data is sent.

Only in very slow clients, the next polling request may be so much delayed that the Server disposes the session first, because of its protection timeouts. In this case, a request for a fresh session will be reissued by the client and this may happen in cycle.

Default: YES.

Lifecycle: the algorithm should be enabled/disabled on the [LSLightstreamerClient connectionOptions] object before calling the [LSLightstreamerClient connect] method. However, the property can be changed at any time: the supplied value will be used for the next connection attempt.

Related notifications: a change to this setting will be notified through a call to [LSClientDelegate client:didChangeProperty:] with argument slowingEnabled on any LSClientDelegate listening to the related LSLightstreamerClient.