PubSub+ Messaging API For C  7.29.0.6
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Session Configuration Properties

Items that can be configured for a Session. More...

Macros

#define SOLCLIENT_SESSION_PROP_USERNAME   "SESSION_USERNAME"
 The username required for authentication. More...
 
#define SOLCLIENT_SESSION_PROP_PASSWORD   "SESSION_PASSWORD"
 The password required for authentication. More...
 
#define SOLCLIENT_SESSION_PROP_HOST   "SESSION_HOST"
 The IPv4 or IPv6 address or host name to connect to. More...
 
#define SOLCLIENT_SESSION_PROP_PORT   "SESSION_PORT"
 Deprecated. More...
 
#define SOLCLIENT_SESSION_PROP_BUFFER_SIZE   "SESSION_BUFFER_SIZE"
 The maximum amount of messages to buffer (in bytes) when the TCP session is flow controlled (see Message Buffer Size Configuration). More...
 
#define SOLCLIENT_SESSION_PROP_CONNECT_BLOCKING   "SESSION_CONNECT_BLOCKING"
 Use SOLCLIENT_PROP_ENABLE_VAL to enable blocking connect operation. More...
 
#define SOLCLIENT_SESSION_PROP_SEND_BLOCKING   "SESSION_SEND_BLOCKING"
 Use SOLCLIENT_PROP_ENABLE_VAL to enable blocking send operation. More...
 
#define SOLCLIENT_SESSION_PROP_SUBSCRIBE_BLOCKING   "SESSION_SUBSCRIBE_BLOCKING"
 Use SOLCLIENT_PROP_ENABLE_VAL to enable blocking subscribe/unsubscribe operation. More...
 
#define SOLCLIENT_SESSION_PROP_BLOCK_WHILE_CONNECTING   "SESSION_BLOCK_WHILE_CONNECTING"
 Use SOLCLIENT_PROP_ENABLE_VAL to block the calling thread on operations such as sending a message, subscribing, or unsubscribing when the Session is being connected or reconnected. More...
 
#define SOLCLIENT_SESSION_PROP_BLOCKING_WRITE_TIMEOUT_MS   "SESSION_WRITE_TIMEOUT_MS"
 The timeout period (in milliseconds) for blocking write operation. More...
 
#define SOLCLIENT_SESSION_PROP_CONNECT_TIMEOUT_MS   "SESSION_CONNECT_TIMEOUT_MS"
 The timeout period (in milliseconds) for a connect operation to a given host (per host). More...
 
#define SOLCLIENT_SESSION_PROP_SUBCONFIRM_TIMEOUT_MS   "SESSION_SUBCONFIRM_TIMEOUT_MS"
 The timeout period (in milliseconds) for subscription confirm (add or remove). More...
 
#define SOLCLIENT_SESSION_PROP_IGNORE_DUP_SUBSCRIPTION_ERROR   "SESSION_IGNORE_DUP_SUBSCRIPTION_ERROR"
 Use SOLCLIENT_PROP_ENABLE_VAL to ignore errors for duplicate subscription/topic on subscribe or subscription not found errors on unsubscribe. More...
 
#define SOLCLIENT_SESSION_PROP_TCP_NODELAY   "SESSION_TCP_NODELAY"
 Use SOLCLIENT_PROP_ENABLE_VAL to enable TCP no delay. More...
 
#define SOLCLIENT_SESSION_PROP_SOCKET_SEND_BUF_SIZE   "SESSION_SOCKET_SEND_BUF_SIZE"
 The value for the socket send buffer size (in bytes). More...
 
#define SOLCLIENT_SESSION_PROP_SOCKET_RCV_BUF_SIZE   "SESSION_SOCKET_RCV_BUF_SIZE"
 The value for socket receive buffer size (in bytes). More...
 
#define SOLCLIENT_SESSION_PROP_KEEP_ALIVE_INT_MS   "SESSION_KEEP_ALIVE_INTERVAL_MS"
 The amount of time (in milliseconds) to wait between sending out Keep-Alive messages. More...
 
#define SOLCLIENT_SESSION_PROP_KEEP_ALIVE_LIMIT   "SESSION_KEEP_ALIVE_LIMIT"
 The maximum number of consecutive Keep-Alive messages that can be sent without receiving a response before the connection is closed by the API. More...
 
#define SOLCLIENT_SESSION_PROP_APPLICATION_DESCRIPTION   "SESSION_APPLICATION_DESCRIPTION"
 A string that uniquely describes the application instance. More...
 
#define SOLCLIENT_SESSION_PROP_CLIENT_MODE   "SESSION_CLIENT_MODE"
 Deprecated. More...
 
#define SOLCLIENT_SESSION_PROP_BIND_IP   "SESSION_BIND_IP"
 (Optional) The hostname or IP address of the machine on which the application is running. More...
 
#define SOLCLIENT_SESSION_PROP_PUB_WINDOW_SIZE   "SESSION_PUB_WINDOW_SIZE"
 The publisher window size for Guaranteed messages. More...
 
#define SOLCLIENT_SESSION_PROP_PUB_ACK_TIMER   "SESSION_PUB_ACK_TIMER"
 The duration of publisher acknowledgment timer (in milliseconds). More...
 
#define SOLCLIENT_SESSION_PROP_VPN_NAME   "SESSION_VPN_NAME"
 The name of the Message VPN to attempt to join when connecting to an broker running SolOS-TR. More...
 
#define SOLCLIENT_SESSION_PROP_VPN_NAME_IN_USE   "SESSION_VPN_NAME_IN_USE"
 A read-only Session property that indicates which Message VPN the Session is connected to. More...
 
#define SOLCLIENT_SESSION_PROP_CLIENT_NAME   "SESSION_CLIENT_NAME"
 The Session client name that is used during client login to create a unique Session. More...
 
#define SOLCLIENT_SESSION_PROP_COMPRESSION_LEVEL   "SESSION_COMPRESSION_LEVEL"
 Enables messages to be compressed with ZLIB before transmission and decompressed on receive. More...
 
#define SOLCLIENT_SESSION_PROP_GENERATE_RCV_TIMESTAMPS   "SESSION_RCV_TIMESTAMP"
 When enabled, a receive timestamp is recorded for each message and passed to the application callback in the rxCallbackInfo_t structure. More...
 
#define SOLCLIENT_SESSION_PROP_GENERATE_SEND_TIMESTAMPS   "SESSION_SEND_TIMESTAMP"
 When enabled, a send timestamp is automatically included (if not already present) in the Solace-defined fields for each message sent. More...
 
#define SOLCLIENT_SESSION_PROP_GENERATE_SENDER_ID   "SESSION_SEND_SENDER_ID"
 When enabled, a sender ID is automatically included (if not already present) in the Solace-defined fields for each message sent. More...
 
#define SOLCLIENT_SESSION_PROP_GENERATE_SEQUENCE_NUMBER   "SESSION_SEND_SEQUENCE_NUMBER"
 When enabled, a sequence number is automatically included (if not already present) in the Solace-defined fields for each message sent. More...
 
#define SOLCLIENT_SESSION_PROP_CONNECT_RETRIES_PER_HOST   "SESSION_CONNECT_RETRIES_PER_HOST"
 When using a host list, this property defines how many times to try to connect or reconnect to a single host before moving to the next host in the list. More...
 
#define SOLCLIENT_SESSION_PROP_CONNECT_RETRIES   "SESSION_CONNECT_RETRIES"
 How many times to try to connect to the host broker (or list of broker) during connection setup. More...
 
#define SOLCLIENT_SESSION_PROP_RECONNECT_RETRIES   "SESSION_RECONNECT_RETRIES"
 How many times to retry to reconnect to the host broker (or list of broker) after a connected Session goes down. More...
 
#define SOLCLIENT_SESSION_PROP_RECONNECT_RETRY_WAIT_MS   "SESSION_RECONNECT_RETRY_WAIT_MS"
 How much time (in ms) to wait between each attempt to connect or reconnect to a host. More...
 
#define SOLCLIENT_SESSION_PROP_USER_ID   "SESSION_USER_ID"
 A read-only informational string providing information about the application, such as the name of operating system user that is running the application, the hostname, and the PID of the application. More...
 
#define SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE   "SESSION_REPLY_TO_DEFAULT_DEST"
 A read-only informational string that indicates the default reply-to destination that is used when a request message is sent that does not have a reply-to destination specified. More...
 
#define SOLCLIENT_SESSION_PROP_REPLY_TO_DEFAULT_DEST   SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE
 Deprecated: see SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE. More...
 
#define SOLCLIENT_SESSION_PROP_REAPPLY_SUBSCRIPTIONS   "SESSION_REAPPLY_SUBSCRIPTIONS"
 Use SOLCLIENT_PROP_ENABLE_VAL to have the API remember subscriptions and reapply them upon a Session reconnect. More...
 
#define SOLCLIENT_SESSION_PROP_TOPIC_DISPATCH   "SESSION_TOPIC_DISPATCH"
 Use SOLCLIENT_PROP_ENABLE_VAL to have the API dispatch messages based on Topic (see Dispatching Messages Based on a Topic). More...
 
#define SOLCLIENT_SESSION_PROP_PROVISION_TIMEOUT_MS   "SESSION_PROVISION_TIMEOUT_MS"
 Maximum amount of time (in milliseconds) to wait for a provision command (create or delete an endpoint) More...
 
#define SOLCLIENT_SESSION_PROP_CALCULATE_MESSAGE_EXPIRATION   "SESSION_CALCULATE_MESSAGE_EXPIRATION"
 If this property is true and time-to-live (solClient_msg_setTimeToLive()) has a positive value in a message, the expiration time is calculated when the message is sent or received and can be retrieved with solClient_msg_getExpiration. More...
 
#define SOLCLIENT_SESSION_PROP_VIRTUAL_ROUTER_NAME   "SESSION_VIRTUAL_ROUTER_NAME"
 A read-only property that indicates the connected broker's virtual router name. More...
 
#define SOLCLIENT_SESSION_PROP_NO_LOCAL   "SESSION_NO_LOCAL"
 If this property is true, messages published on the Session cannot be received on the same Session even if the client has a subscription that matches the published topic. More...
 
#define SOLCLIENT_SESSION_PROP_AD_PUB_ROUTER_WINDOWED_ACK   "SESSION_AD_PUB_ROUTER_WINDOWED_ACK"
 When disabled, initiate a window size of 1 to broker, but do not wait for acknowledgments before transmitting up to the actual window size. More...
 
#define SOLCLIENT_SESSION_PROP_MODIFYPROP_TIMEOUT_MS   "SESSION_MODIFYPROP_TIMEOUT_MS"
 Maximum amount of time (in milliseconds) to wait for session property modification. More...
 
#define SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE   "SESSION_ACK_EVENT_MODE"
 This property specifies if a session event SOLCLIENT_SESSION_EVENT_ACKNOWLEDGEMENT acknowledges a single message (see SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE_PER_MSG) or a range of messages (see SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE_WINDOWED). More...
 
#define SOLCLIENT_SESSION_PROP_SSL_EXCLUDED_PROTOCOLS   "SESSION_SSL_EXCLUDED_PROTOCOLS"
 This property specifies a comma separated list of excluded SSL protocol(s). More...
 
#define SOLCLIENT_SESSION_PROP_SSL_VALIDATE_CERTIFICATE   "SESSION_SSL_VALIDATE_CERTIFICATE"
 This is used to specify whether the API should validate server certificates with certificates in the truststore. More...
 
#define SOLCLIENT_SESSION_PROP_OPENSSL_SECURITY_LEVEL   "SESSION_OPENSSL_SECURITY_LEVEL"
 A number from 0-5 passed to the openSsl library as the security level. More...
 
#define SOLCLIENT_SESSION_PROP_SSL_CLIENT_CERTIFICATE_FILE   "SESSION_SSL_CLIENT_CERTIFICATE_FILE"
 This property specifies the client certificate file name. More...
 
#define SOLCLIENT_SESSION_PROP_SSL_CLIENT_PRIVATE_KEY_FILE   "SESSION_SSL_CLIENT_PRIVATE_KEY_FILE"
 This property specifies the client private key file name. More...
 
#define SOLCLIENT_SESSION_PROP_SSL_CLIENT_PRIVATE_KEY_FILE_PASSWORD   "SESSION_SSL_CLIENT_PRIVATE_KEY_FILE_PASSWORD"
 This property specifies the password used to encrypt the client private key file. More...
 
#define SOLCLIENT_SESSION_PROP_SSL_CONNECTION_DOWNGRADE_TO   "SESSION_SSL_CONNECTION_DOWNGRADE_TO"
 This property specifies a transport protocol that SSL connection will be downgraded to after client authentication. More...
 
#define SOLCLIENT_SESSION_PROP_INITIAL_RECEIVE_BUFFER_SIZE   "SESSION_INITIAL_RECEIVE_BUFFER_SIZE"
 If not zero, the minimum starting size for the API receive buffer. More...
 
#define SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME   "SESSION_AUTHENTICATION_SCHEME"
 This property specifies the authentication scheme. More...
 
#define SOLCLIENT_SESSION_PROP_KRB_SERVICE_NAME   "SESSION_KRB_SERVICE_NAME"
 This property specifies the first part of Kerberos Service Principal Name (SPN) of the form ServiceName/Hostname@REALM (for Windows) or Host Based Service of the form ServiceName@Hostname (for Linux and SunOS). More...
 
#define SOLCLIENT_SESSION_PROP_UNBIND_FAIL_ACTION   "SESSION_UNBIND_FAIL_ACTION"
 A property to define the behavior if an unbind-response is not received after an unbind-request (solClient_flow_destroy()) is sent to the Solace Appliance. More...
 
#define SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL   ("SESSION_WEB_TRANSPORT_PROTOCOL")
 This property specifies a WEB Transport Protocol in the default WEB Transport Protocol downgrade list to use for the session connection. More...
 
#define SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_IN_USE   ("SESSION_WEB_TRANSPORT_PROTOCOL_IN_USE")
 Read-only property which returns the WEB Transport Protocol currently in use for web messaging. More...
 
#define SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST   ("SESSION_WEB_TRANSPORT_PROTOCOL_LIST")
 This property specifies a comma separated list of WEB Transport Protocols to use for session connection. More...
 
#define SOLCLIENT_SESSION_PROP_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS   ("SESSION_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS")
 Specifies how long to wait (in milliseconds) for a login response before moving to the next available protocol in a user specified or the default WEB Transport Protocol downgradelist. More...
 
#define SOLCLIENT_SESSION_PROP_GUARANTEED_WITH_WEB_TRANSPORT   ("SESSION_GUARANTEED_WITH_WEB_TRANSPORT")
 Enables guaranteed messaging with web transport protocols. More...
 
#define SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION   "SESSION_GD_RECONNECT_FAIL_ACTION"
 A property to define the behavior when the CCSMP API is unable to reconnect guaranteed delivery after reconnecting the session. More...
 
#define SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN   "SESSION_OAUTH2_ACCESS_TOKEN"
 The OAUTH2 access token. More...
 
#define SOLCLIENT_SESSION_PROP_OAUTH2_ISSUER_IDENTIFIER   "SESSION_OAUTH2_ISSUER_IDENTIFIER"
 The optional Issuer identifier URI for OAUTH2 access token based authentication. More...
 
#define SOLCLIENT_SESSION_PROP_OIDC_ID_TOKEN   "SESSION_OIDC_ID_TOKEN"
 The OIDC (OpenId Connect) ID Token. More...
 

Detailed Description

Items that can be configured for a Session.

Some Session Properties can also be set as environment variables. If a session property can be set as an environment variable, the API will only look for that environment variable if the property is not specified in the session property list passed to solClient_session_create.

The following environment variables are recognized:

Macro Definition Documentation

#define SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE   "SESSION_ACK_EVENT_MODE"

This property specifies if a session event SOLCLIENT_SESSION_EVENT_ACKNOWLEDGEMENT acknowledges a single message (see SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE_PER_MSG) or a range of messages (see SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE_WINDOWED).

Default: SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE_PER_MSG.
Setting this property to SOLCLIENT_SESSION_PROP_ACK_EVENT_MODE_WINDOWED will not affect RejectedMessageError events, they will still be emitted on a per message basis.

#define SOLCLIENT_SESSION_PROP_AD_PUB_ROUTER_WINDOWED_ACK   "SESSION_AD_PUB_ROUTER_WINDOWED_ACK"

When disabled, initiate a window size of 1 to broker, but do not wait for acknowledgments before transmitting up to the actual window size.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_AD_PUB_ROUTER_WINDOWED_ACK

#define SOLCLIENT_SESSION_PROP_APPLICATION_DESCRIPTION   "SESSION_APPLICATION_DESCRIPTION"

A string that uniquely describes the application instance.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_APPLICATION_DESCRIPTION

#define SOLCLIENT_SESSION_PROP_BIND_IP   "SESSION_BIND_IP"

(Optional) The hostname or IP address of the machine on which the application is running.

On a multihomed machine, it is strongly recommended to provide this parameter to ensure that the API uses the correct network interface at Session connect time. Default: SOLCLIENT_SESSION_PROP_DEFAULT_BIND_IP

#define SOLCLIENT_SESSION_PROP_BLOCK_WHILE_CONNECTING   "SESSION_BLOCK_WHILE_CONNECTING"

Use SOLCLIENT_PROP_ENABLE_VAL to block the calling thread on operations such as sending a message, subscribing, or unsubscribing when the Session is being connected or reconnected.

The operation must already be blocking (see SOLCLIENT_SESSION_PROP_SEND_BLOCKING and SOLCLIENT_SESSION_PROP_SUBSCRIBE_BLOCKING). Otherwise, SOLCLIENT_NOT_READY is returned if the Session is being connected. Default: SOLCLIENT_SESSION_PROP_DEFAULT_BLOCK_WHILE_CONNECTING

#define SOLCLIENT_SESSION_PROP_BLOCKING_WRITE_TIMEOUT_MS   "SESSION_WRITE_TIMEOUT_MS"

The timeout period (in milliseconds) for blocking write operation.

The valid range is > 0. Default: SOLCLIENT_SESSION_PROP_DEFAULT_BLOCKING_WRITE_TIMEOUT_MS

#define SOLCLIENT_SESSION_PROP_BUFFER_SIZE   "SESSION_BUFFER_SIZE"

The maximum amount of messages to buffer (in bytes) when the TCP session is flow controlled (see Message Buffer Size Configuration).

The valid range is > 0. Default: SOLCLIENT_SESSION_PROP_DEFAULT_BUFFER_SIZE

#define SOLCLIENT_SESSION_PROP_CALCULATE_MESSAGE_EXPIRATION   "SESSION_CALCULATE_MESSAGE_EXPIRATION"

If this property is true and time-to-live (solClient_msg_setTimeToLive()) has a positive value in a message, the expiration time is calculated when the message is sent or received and can be retrieved with solClient_msg_getExpiration.

#define SOLCLIENT_SESSION_PROP_CLIENT_MODE   "SESSION_CLIENT_MODE"

Deprecated.

The CCSMP API detects the broker capabilities, so it is no longer necessary to specify to use 'clientMode' or not. This property is ignored when specified.

#define SOLCLIENT_SESSION_PROP_CLIENT_NAME   "SESSION_CLIENT_NAME"

The Session client name that is used during client login to create a unique Session.

An empty string causes a unique client name to be generated automatically. If specified, it must be a valid Topic name, and a maximum of 160 bytes in length. For all brokers (SolOS-TR or SolOS-CR) the SOLCLIENT_SESSION_PROP_CLIENT_NAME is also used to uniquely identify the sender in a message's senderId field if SOLCLIENT_SESSION_PROP_GENERATE_SENDER_ID is set. Default: SOLCLIENT_SESSION_PROP_DEFAULT_CLIENT_NAME

Examples:
ex/ios/examples/SubscribeOnBehalfOfClientExample.m, and ex/subscribeOnBehalfOfClient.c.
#define SOLCLIENT_SESSION_PROP_COMPRESSION_LEVEL   "SESSION_COMPRESSION_LEVEL"

Enables messages to be compressed with ZLIB before transmission and decompressed on receive.

The valid range is 0 (off) or 1..9, where 1 is less compression (fastest) and 9 is most compression (slowest). Default: SOLCLIENT_SESSION_PROP_DEFAULT_COMPRESSION_LEVEL

Note: If no port is specified in the SESSION_HOST property, the API will automatically connect to either the default non-compressed listen port (55555) or default compressed listen port (55003) based on the specified COMPRESSION_LEVEL. If a port is specified in the SESSION_HOST property you must specify the non-compressed listen port if not using compression (compression level 0) or the compressed listen port if using compression (compression levels 1 to 9).

Examples:
ex/common.c, ex/directPubSub.c, ex/ios/Example.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/TopicDispatchExample.m, ex/perfADPub.c, ex/perfADSub.c, ex/perfTest.c, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_CONNECT_BLOCKING   "SESSION_CONNECT_BLOCKING"

Use SOLCLIENT_PROP_ENABLE_VAL to enable blocking connect operation.

A blocking connect operation suspends until the Session is successfully connected, including restoring all remembered subscriptions if SOLCLIENT_SESSION_PROP_REAPPLY_SUBSCRIPTIONS is enabled. Otherwise solClient_session_connect() returns SOLCLIENT_IN_PROGRESS.

See Also
Threading Effects on Blocking Modes for a discussion of blocking operation in the Context thread. Default: SOLCLIENT_SESSION_PROP_DEFAULT_CONNECT_BLOCKING
Examples:
ex/ios/examples/PerfTestExample.m, and ex/perfTest.c.
#define SOLCLIENT_SESSION_PROP_CONNECT_RETRIES   "SESSION_CONNECT_RETRIES"

How many times to try to connect to the host broker (or list of broker) during connection setup.

Zero means no automatic connection retries (that is, try once and give up). -1 means try to connect forever. The default valid range is >= -1.

When using a host list, each time the API works through the host list without establishing a connection is considered an connect retry. For example, if a SOLCLIENT_SESSION_PROP_CONNECT_RETRIES value of two is used, the API could possibly work through all of the listed hosts without connecting to them three times: one time through for the initial connect attempt, and then two times through for connect retries. Each connect retry begins with the first host listed. After each unsuccessful attempt to connect to a host, the API waits for the amount of time set for SOLCLIENT_SESSION_PROP_RECONNECT_RETRY_WAIT_MS before attempting another connection to a host, and the number times to attempt to connect to one host before moving on to the next listed host is determined by the value set for SOLCLIENT_SESSION_PROP_CONNECT_RETRIES_PER_HOST. Default: SOLCLIENT_SESSION_PROP_DEFAULT_CONNECT_RETRIES

Examples:
ex/common.c, ex/ios/Example.m, ex/ios/examples/PerfTestExample.m, ex/ios/examples/TopicDispatchExample.m, ex/perfTest.c, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_CONNECT_RETRIES_PER_HOST   "SESSION_CONNECT_RETRIES_PER_HOST"

When using a host list, this property defines how many times to try to connect or reconnect to a single host before moving to the next host in the list.

A value of 0 (the default) means make a single connection attempt (that is, 0 retries). A value of -1 means attempt an infinite number of reconnect retries (that is, the API will only try to connect or reconnect to first host listed.) NOTE: This property works in conjunction with the connect and reconnect retries Session properties; it does not replace them.

Examples:
ex/ios/examples/SecureSessionExample.m, and ex/secureSession.c.
#define SOLCLIENT_SESSION_PROP_CONNECT_TIMEOUT_MS   "SESSION_CONNECT_TIMEOUT_MS"

The timeout period (in milliseconds) for a connect operation to a given host (per host).

The valid range is > 0. Default: SOLCLIENT_SESSION_PROP_DEFAULT_CONNECT_TIMEOUT_MS

Examples:
ex/ios/examples/DirectPubSubExample.m.
#define SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION   "SESSION_GD_RECONNECT_FAIL_ACTION"

A property to define the behavior when the CCSMP API is unable to reconnect guaranteed delivery after reconnecting the session.

This may occur if the session is configured with a host list where each Solace router in the host list is unaware of state on the previous router. It can also occur if the time to reconnect to the same router exceeds the publisher flow timeout on the router. May be set as an environment variable (See Session Configuration Properties).
Default: SOLCLIENT_SESSION_PROP_DEFAULT_GD_RECONNECT_FAIL_ACTION

#define SOLCLIENT_SESSION_PROP_GENERATE_RCV_TIMESTAMPS   "SESSION_RCV_TIMESTAMP"

When enabled, a receive timestamp is recorded for each message and passed to the application callback in the rxCallbackInfo_t structure.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_GENERATE_RCV_TIMESTAMPS

Examples:
ex/directPubSub.c.
#define SOLCLIENT_SESSION_PROP_GENERATE_SEND_TIMESTAMPS   "SESSION_SEND_TIMESTAMP"

When enabled, a send timestamp is automatically included (if not already present) in the Solace-defined fields for each message sent.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_GENERATE_SEND_TIMESTAMPS

Examples:
ex/common.c, ex/directPubSub.c, ex/ios/Example.m, ex/ios/examples/TopicDispatchExample.m, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_GENERATE_SENDER_ID   "SESSION_SEND_SENDER_ID"

When enabled, a sender ID is automatically included (if not already present) in the Solace-defined fields for each message sent.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_GENERATE_SENDER_ID

Examples:
ex/common.c, ex/ios/Example.m, ex/ios/examples/TopicDispatchExample.m, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_GENERATE_SEQUENCE_NUMBER   "SESSION_SEND_SEQUENCE_NUMBER"

When enabled, a sequence number is automatically included (if not already present) in the Solace-defined fields for each message sent.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_GENERATE_SEQUENCE_NUMBER

Examples:
ex/common.c, ex/ios/Example.m, ex/ios/examples/TopicDispatchExample.m, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_GUARANTEED_WITH_WEB_TRANSPORT   ("SESSION_GUARANTEED_WITH_WEB_TRANSPORT")

Enables guaranteed messaging with web transport protocols.

Refer to Session Transport Trotocol Types for supported transport protocols. Only has effect when a session is established over a web messaging transport. Default SOLCLIENT_SESSION_PROP_DEFAULT_GUARANTEED_WITH_WEB_TRANSPORT

#define SOLCLIENT_SESSION_PROP_IGNORE_DUP_SUBSCRIPTION_ERROR   "SESSION_IGNORE_DUP_SUBSCRIPTION_ERROR"

Use SOLCLIENT_PROP_ENABLE_VAL to ignore errors for duplicate subscription/topic on subscribe or subscription not found errors on unsubscribe.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_IGNORE_DUP_SUBSCRIPTION_ERROR

#define SOLCLIENT_SESSION_PROP_INITIAL_RECEIVE_BUFFER_SIZE   "SESSION_INITIAL_RECEIVE_BUFFER_SIZE"

If not zero, the minimum starting size for the API receive buffer.

Must be zero or >= 1024 and <=64*1024*1024

#define SOLCLIENT_SESSION_PROP_KEEP_ALIVE_INT_MS   "SESSION_KEEP_ALIVE_INTERVAL_MS"

The amount of time (in milliseconds) to wait between sending out Keep-Alive messages.

Typically, this feature should be enabled for message receivers. Use 0 to disable Keep-Alives (0 is required before broker release 4.2). The valid range is 0 (disabled) or >= 50. Default: SOLCLIENT_SESSION_PROP_DEFAULT_KEEP_ALIVE_INT_MS

#define SOLCLIENT_SESSION_PROP_KEEP_ALIVE_LIMIT   "SESSION_KEEP_ALIVE_LIMIT"

The maximum number of consecutive Keep-Alive messages that can be sent without receiving a response before the connection is closed by the API.

The valid range is >= 3. Default: SOLCLIENT_SESSION_PROP_DEFAULT_KEEP_ALIVE_LIMIT

#define SOLCLIENT_SESSION_PROP_KRB_SERVICE_NAME   "SESSION_KRB_SERVICE_NAME"

This property specifies the first part of Kerberos Service Principal Name (SPN) of the form ServiceName/Hostname@REALM (for Windows) or Host Based Service of the form ServiceName@Hostname (for Linux and SunOS).

Default: SOLCLIENT_SESSION_PROP_DEFAULT_KRB_SERVICE_NAME.

The Hostname of SPN or Host Based Service is the host portion of an entry specified by the session property SOLCLIENT_SESSION_PROP_HOST. The REALM of the SPN is Kerberos realm. The maximum length of an SPN is 256 characters.
Note: This property is used for all entries specified by the property SOLCLIENT_SESSION_PROP_HOST.

#define SOLCLIENT_SESSION_PROP_MODIFYPROP_TIMEOUT_MS   "SESSION_MODIFYPROP_TIMEOUT_MS"

Maximum amount of time (in milliseconds) to wait for session property modification.

Default: SOLCLIENT_SESSION_PROP_DEFAULT_MODIFYPROP_TIMEOUT_MS

#define SOLCLIENT_SESSION_PROP_NO_LOCAL   "SESSION_NO_LOCAL"

If this property is true, messages published on the Session cannot be received on the same Session even if the client has a subscription that matches the published topic.

If this restriction is requested, and the broker does not have No Local support, the Session connect will fail with subcode SOLCLIENT_SUBCODE_NO_LOCAL_NOT_SUPPORTED.

Examples:
ex/noLocalPubSub.c.
#define SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN   "SESSION_OAUTH2_ACCESS_TOKEN"

The OAUTH2 access token.

When authentication scheme SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_OAUTH2 is used at least one of SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN and SOLCLIENT_SESSION_PROP_OIDC_ID_TOKEN must be set.

#define SOLCLIENT_SESSION_PROP_OAUTH2_ISSUER_IDENTIFIER   "SESSION_OAUTH2_ISSUER_IDENTIFIER"

The optional Issuer identifier URI for OAUTH2 access token based authentication.

#define SOLCLIENT_SESSION_PROP_OIDC_ID_TOKEN   "SESSION_OIDC_ID_TOKEN"

The OIDC (OpenId Connect) ID Token.

When authentication scheme SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_OAUTH2 is used at least one of SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN and SOLCLIENT_SESSION_PROP_OIDC_ID_TOKEN must be set.

#define SOLCLIENT_SESSION_PROP_OPENSSL_SECURITY_LEVEL   "SESSION_OPENSSL_SECURITY_LEVEL"

A number from 0-5 passed to the openSsl library as the security level.

Use 0 with caution, it is less secure than the default, which is 1.

#define SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE   "SESSION_REPLY_TO_DEFAULT_DEST"

A read-only informational string that indicates the default reply-to destination that is used when a request message is sent that does not have a reply-to destination specified.

See solClient_session_sendRequest(). This parameter is only valid when the Session is connected.

#define SOLCLIENT_SESSION_PROP_PORT   "SESSION_PORT"

Deprecated.

While still supported, the port number can also now be specified as part of the host in SOLCLIENT_SESSION_PROP_HOST (for example, "hostname:55555"). In general, port numbers are not needed except in special situations, because the API chooses the correct port to connect to the broker. If SOLCLIENT_SESSION_PROP_PORT is set, this port number is used for all entries in SOLCLIENT_SESSION_PROP_HOST that do not explicitly specify port. The port number to connect to. The valid range is 1..65535. Default: SOLCLIENT_SESSION_PROP_DEFAULT_PORT or SOLCLIENT_SESSION_PROP_DEFAULT_PORT_COMPRESSION, based on setting of SOLCLIENT_SESSION_PROP_COMPRESSION_LEVEL

#define SOLCLIENT_SESSION_PROP_PROVISION_TIMEOUT_MS   "SESSION_PROVISION_TIMEOUT_MS"

Maximum amount of time (in milliseconds) to wait for a provision command (create or delete an endpoint)

#define SOLCLIENT_SESSION_PROP_PUB_ACK_TIMER   "SESSION_PUB_ACK_TIMER"

The duration of publisher acknowledgment timer (in milliseconds).

When a published message is not acknowledged within the time specified for this timer, the API automatically retransmits the message. There is no limit on the number of retransmissions for any message. However, while the API is resending, applications can become flow controlled. The flow control behavior is controlled by SOLCLIENT_SESSION_PROP_SEND_BLOCKING and SOLCLIENT_SESSION_PROP_BLOCKING_WRITE_TIMEOUT_MS. The valid range is 20..60000. Default: SOLCLIENT_SESSION_PROP_DEFAULT_PUB_ACK_TIMER

#define SOLCLIENT_SESSION_PROP_PUB_WINDOW_SIZE   "SESSION_PUB_WINDOW_SIZE"

The publisher window size for Guaranteed messages.

The Guaranteed Message Publish Window Size property limits the maximum number of messages that can be published before the API must receive an acknowledgment from the broker. The valid range is 1..255, or 0 to disable publishing Guaranteed messages. Default: SOLCLIENT_SESSION_PROP_DEFAULT_PUB_WINDOW_SIZE

Examples:
ex/perfADPub.c.
#define SOLCLIENT_SESSION_PROP_REAPPLY_SUBSCRIPTIONS   "SESSION_REAPPLY_SUBSCRIPTIONS"

Use SOLCLIENT_PROP_ENABLE_VAL to have the API remember subscriptions and reapply them upon a Session reconnect.

Reapply subscriptions will only apply direct topic subscriptions upon a Session reconnect. It will not reapply topic subscriptions on durable and non-durable endpoints. Default: SOLCLIENT_SESSION_PROP_DEFAULT_REAPPLY_SUBSCRIPTIONS

Examples:
ex/common.c, ex/directPubSub.c, ex/ios/Example.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/PerfTestExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/examples/TopicDispatchExample.m, ex/perfTest.c, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, ex/secureSession.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_RECONNECT_RETRIES   "SESSION_RECONNECT_RETRIES"

How many times to retry to reconnect to the host broker (or list of broker) after a connected Session goes down.

Zero means no automatic reconnection attempts. -1 means try to reconnect forever. The default valid range is >= -1.

When using a host list, each time the API works through the host list without establishing a connection is considered a reconnect retry. Each reconnect retry begins with the first host listed. After each unsuccessful attempt to reconnect to a host, the API waits for the amount of time set for SOLCLIENT_SESSION_PROP_RECONNECT_RETRY_WAIT_MS before attempting another connection to a host, and the number times to attempt to connect to one host before moving on to the next listed host is determined by the value set for SOLCLIENT_SESSION_PROP_CONNECT_RETRIES_PER_HOST. Default: SOLCLIENT_SESSION_PROP_DEFAULT_RECONNECT_RETRIES

Examples:
ex/common.c, ex/directPubSub.c, ex/ios/Example.m, ex/ios/examples/DirectPubSubExample.m, ex/ios/examples/PerfTestExample.m, ex/ios/examples/SecureSessionExample.m, ex/ios/examples/TopicDispatchExample.m, ex/noLocalPubSub.c, ex/perfTest.c, ex/RRDirectReplier.c, ex/RRDirectRequester.c, ex/RRGuaranteedReplier.c, ex/RRGuaranteedRequester.c, ex/secureSession.c, and ex/topicDispatch.c.
#define SOLCLIENT_SESSION_PROP_RECONNECT_RETRY_WAIT_MS   "SESSION_RECONNECT_RETRY_WAIT_MS"

How much time (in ms) to wait between each attempt to connect or reconnect to a host.

If a connect or reconnect attempt to host is not successful, the API waits for the amount of time set for SOLCLIENT_SESSION_PROP_RECONNECT_RETRY_WAIT_MS, and then makes another connect or reconnect attempt. SESSION_CONNECT_RETRIES_PER_HOST sets how many connection or reconnection attempts can be made before moving on to the next host in the list. The valid range is >=0. Default: SOLCLIENT_SESSION_PROP_DEFAULT_RECONNECT_RETRY_WAIT_MS.

#define SOLCLIENT_SESSION_PROP_REPLY_TO_DEFAULT_DEST   SOLCLIENT_SESSION_PROP_P2PINBOX_IN_USE
#define SOLCLIENT_SESSION_PROP_SEND_BLOCKING   "SESSION_SEND_BLOCKING"

Use SOLCLIENT_PROP_ENABLE_VAL to enable blocking send operation.

A blocking send operation suspends when the Session is transport flow controlled, otherwise the send operation returns SOLCLIENT_WOULD_BLOCK. Successful return from a blocking send operation only means the message has been accepted by the transport, it does not guarantee the message has been processed by the broker. For the latter you must used Guaranteed Message Delivery mode and wait for the session event (SOLCLIENT_SESSION_EVENT_ACKNOWLEDGEMENT) that acknowledges the message.

See Also
Threading Effects on Blocking Modes for a discussion of blocking operation in the Context thread. Default: SOLCLIENT_SESSION_PROP_DEFAULT_SEND_BLOCKING
Examples:
ex/perfADPub.c.
#define SOLCLIENT_SESSION_PROP_SOCKET_RCV_BUF_SIZE   "SESSION_SOCKET_RCV_BUF_SIZE"

The value for socket receive buffer size (in bytes).

0 indicates do not set and leave at operating system default. The valid range is 0 or >= 1024. Default: SOLCLIENT_SESSION_PROP_DEFAULT_SOCKET_RCV_BUF_SIZE

#define SOLCLIENT_SESSION_PROP_SOCKET_SEND_BUF_SIZE   "SESSION_SOCKET_SEND_BUF_SIZE"

The value for the socket send buffer size (in bytes).

0 indicates do not set and leave at operating system default. The valid range is 0 or >= 1024. Default: SOLCLIENT_SESSION_PROP_DEFAULT_SOCKET_SEND_BUF_SIZE.

Note that Linux operating system actually allocates twice the size of the buffer requested in the setsockopt(2) call, and so a succeeding getsockopt(2) call will not return the same size of buffer as requested in the setsockopt(2) call. TCP uses the extra space for administrative purposes and internal kernel structures, and the sysctl variables reflect the larger sizes compared to the actual TCP windows.

#define SOLCLIENT_SESSION_PROP_SSL_CLIENT_CERTIFICATE_FILE   "SESSION_SSL_CLIENT_CERTIFICATE_FILE"

This property specifies the client certificate file name.

Examples:
ex/ios/examples/SecureSessionExample.m, and ex/secureSession.c.
#define SOLCLIENT_SESSION_PROP_SSL_CLIENT_PRIVATE_KEY_FILE   "SESSION_SSL_CLIENT_PRIVATE_KEY_FILE"

This property specifies the client private key file name.

Examples:
ex/ios/examples/SecureSessionExample.m, and ex/secureSession.c.
#define SOLCLIENT_SESSION_PROP_SSL_CLIENT_PRIVATE_KEY_FILE_PASSWORD   "SESSION_SSL_CLIENT_PRIVATE_KEY_FILE_PASSWORD"

This property specifies the password used to encrypt the client private key file.

Examples:
ex/ios/examples/SecureSessionExample.m, and ex/secureSession.c.
#define SOLCLIENT_SESSION_PROP_SSL_CONNECTION_DOWNGRADE_TO   "SESSION_SSL_CONNECTION_DOWNGRADE_TO"

This property specifies a transport protocol that SSL connection will be downgraded to after client authentication.

Allowed transport protocol is "PLAIN_TEXT". May be combined with non-zero compression level to achieve compression without encryption.

Examples:
ex/ios/examples/SecureSessionExample.m, and ex/secureSession.c.
#define SOLCLIENT_SESSION_PROP_SSL_EXCLUDED_PROTOCOLS   "SESSION_SSL_EXCLUDED_PROTOCOLS"

This property specifies a comma separated list of excluded SSL protocol(s).

Valid SSL protocols are 'SSLv3', 'TLSv1', 'TLSv1.1', 'TLSv1.2'. Default: SOLCLIENT_SESSION_PROP_DEFAULT_SSL_EXCLUDED_PROTOCOLS.

Examples:
ex/ios/examples/SecureSessionExample.m, and ex/secureSession.c.
#define SOLCLIENT_SESSION_PROP_SSL_VALIDATE_CERTIFICATE   "SESSION_SSL_VALIDATE_CERTIFICATE"
#define SOLCLIENT_SESSION_PROP_SUBCONFIRM_TIMEOUT_MS   "SESSION_SUBCONFIRM_TIMEOUT_MS"

The timeout period (in milliseconds) for subscription confirm (add or remove).

The valid range is >= 1000. Default: SOLCLIENT_SESSION_PROP_DEFAULT_SUBCONFIRM_TIMEOUT_MS

#define SOLCLIENT_SESSION_PROP_SUBSCRIBE_BLOCKING   "SESSION_SUBSCRIBE_BLOCKING"

Use SOLCLIENT_PROP_ENABLE_VAL to enable blocking subscribe/unsubscribe operation.

A blocking subscribe operation will suspend when the Session is transport flow controlled, otherwise the subscribe operation returns SOLCLIENT_WOULD_BLOCK. A successful return from a blocking subscribe operation only means the subscription has been accepted by the transport, it does not guarantee the subscription has been processed by the broker. For the latter you must use a confirmed operation (see SOLCLIENT_SUBSCRIBE_FLAGS_WAITFORCONFIRM)

See Also
Threading Effects on Blocking Modes for a discussion of blocking operation in the Context thread. Default: SOLCLIENT_SESSION_PROP_DEFAULT_SUBSCRIBE_BLOCKING
Examples:
ex/perfTest.c.
#define SOLCLIENT_SESSION_PROP_TCP_NODELAY   "SESSION_TCP_NODELAY"
#define SOLCLIENT_SESSION_PROP_TOPIC_DISPATCH   "SESSION_TOPIC_DISPATCH"
#define SOLCLIENT_SESSION_PROP_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS   ("SESSION_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS")

Specifies how long to wait (in milliseconds) for a login response before moving to the next available protocol in a user specified or the default WEB Transport Protocol downgradelist.

Default SOLCLIENT_SESSION_PROP_DEFAULT_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS

#define SOLCLIENT_SESSION_PROP_UNBIND_FAIL_ACTION   "SESSION_UNBIND_FAIL_ACTION"

A property to define the behavior if an unbind-response is not received after an unbind-request (solClient_flow_destroy()) is sent to the Solace Appliance.

If this occurs it is possible that the endpoint may be still bound and unavailable until the session is terminated. In this occurrence the session can be configured to retry sending the unbind-request or to fail the session transport. If the sesion transport fails, the session will behave as defined by the SOLCLIENT_SESSION_PROP_RECONNECT_RETRIES configuration. Default: SOLCLIENT_SESSION_PROP_DEFAULT_UNBIND_FAIL_ACTION.

#define SOLCLIENT_SESSION_PROP_USER_ID   "SESSION_USER_ID"

A read-only informational string providing information about the application, such as the name of operating system user that is running the application, the hostname, and the PID of the application.

#define SOLCLIENT_SESSION_PROP_VIRTUAL_ROUTER_NAME   "SESSION_VIRTUAL_ROUTER_NAME"

A read-only property that indicates the connected broker's virtual router name.

Appliance endpoint and destination names created with a virtual router name are valid for use with that broker, or to address destinations on remote brokers (in a multiple-broker network) when publishing messages. Applications requiring the virtual router name do not need to poll this property every time it is required, and they may cache the name. Applications should query the name once after connecting the Session, and again after a reconnect operation reports the SOLCLIENT_SESSION_EVENT_VIRTUAL_ROUTER_NAME_CHANGED event. Prior to connecting, an empty string is returned.

#define SOLCLIENT_SESSION_PROP_VPN_NAME_IN_USE   "SESSION_VPN_NAME_IN_USE"

A read-only Session property that indicates which Message VPN the Session is connected to.

When not connected, an empty string is returned.

#define SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL   ("SESSION_WEB_TRANSPORT_PROTOCOL")

This property specifies a WEB Transport Protocol in the default WEB Transport Protocol downgrade list to use for the session connection.

Valid values are Session Transport Trotocol Types. Default: SOLCLIENT_SESSION_PROP_DEFAULT_WEB_TRANSPORT_PROTOCOL If the connection fails, the API will try to connect using the next (less efficient) available protocol in the list until it finds one that works. If there is none available, then the session connection fails.

#define SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_IN_USE   ("SESSION_WEB_TRANSPORT_PROTOCOL_IN_USE")

Read-only property which returns the WEB Transport Protocol currently in use for web messaging.

An empty string is returned when a session is not connected or it is not a web messaging session. Valid values are Session Transport Trotocol Types. Valid values are Session Transport Trotocol Types.

#define SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST   ("SESSION_WEB_TRANSPORT_PROTOCOL_LIST")

This property specifies a comma separated list of WEB Transport Protocols to use for session connection.

The API will use the first one in the list to start session connection. If the connection fails, the API will try to connect using the next available protocol in the list until it finds one that works. If there is none available, then the session connection fails. Note: Only one of the session properties SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL and SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST is allowed to be configured. There shall be no duplicates in the list.

Examples:
ex/ios/intro/HelloWorldWebPubExample.m, ex/ios/intro/HelloWorldWebSubExample.m, Intro/HelloWorldWebPub.c, and Intro/HelloWorldWebSub.c.