The SessionProperties type exposes the following members.
The duration of the publisher acknowledgement 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 SessionProperties.SendBlocking and SessionProperties.BlockingWriteTimeoutInMsecs.
The valid range is 20..60000. Default: 2000
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 acknowledgement from the appliance. Default: 50.
(Optional) The hostname or IP address of the machine on which the application is running. On a multi-homed machine, it is strongly recommended to provide this parameter to ensure that the API uses the correct network interface at session connect time. Default: empty string
The timeout period (in milliseconds) for blocking write operation. The valid range is > 0.
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 SendBlocking). Otherwise, SOLCLIENT_NOT_READY is returned if the session is being connected. Default: true
A string that describes the application instance. This string is available from SolAdmin or CLI.
Set to true to enable client mode. Client mode uses a single TCP connection to the appliance for both publisher and subscriber channels. To use this mode, the appliance requires a Topic Routing Blade.
The session client name that is used during client login (appliances running SolOS-TR only) 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 appliances (SolOS-TR) the ClientName is also used to uniquely identify the sender in a message's senderId field if IncludeSenderId is set to true. Default: empty string
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). Compression is only supported when the session is connected to an appliance running SolOS-TR. Default: 0 (no compression)
Use true to enable blocking connection operation. Default: true
How many times to try to connect to the host appliance (or list of appliances) 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.
API reattempts a connection retry, it begins with the first host listed. 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.
After each unsuccessful attempt to connect to a host, the API waits for the amount of time set for ReconnectRetriesWaitInMsecs 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 ConnectRetriesPerHost.
See Host for more details on the reconnect logic.
Zero means no automatic connection retries (that is, try once and give up). -1 means retry forever. The valid range is >= -1. Default: 0
When using a host list for the Host, 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 only tries to connect or reconnect to first host listed.) Default: 0
NOTE: This property works in conjunction with the connect and reconnect retries settings; It does not replace them.
The timeout period (in milliseconds) for a connect operation. The valid range is > 0.
Returns the count of properties.(Inherited from BaseProperties.)
Specify 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 the 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 SessionProperties)Default: AUTO_RETRY
Enables guaranteed messaging with web transport Default: false
When enabled, a receive timestamp is recorded for each message and passed back as a property of IMessage. Default: false
When enabled, a send timestamp is automatically generated as a message property for each message sent. Default: false
When enabled, a sequence number is automatically included in the Solace-defined fields for each message sent. Default: false
The IPv4 or IPv6 address or host name to connect to. Multiple host entries separated by commas (up to sixteen) are allowed. With multiple entries, each is tried in turn until one succeeds.
Host contains one or more host entries (up to sixteen). The host entry may also include an optional ProxyHost configuration, separated from the message router configuration by a percent (%) sign. A host entry has the following form:
Protocol is the protocol used for the transport channel. The valid values are:
Host is the IPv4 or IPv6 address or host name to connect to for a connection. IPv6 addresses must be enclosed in brackets ()
Port is the port to connect to for a connection. A value is only required when using a port other than the automatically assigned default port number. The default port for TCP is 55555 when compression is not in use, or 55003 when compression is in use. The default port for SSL is 55443.
ProxyService is a description of the non-transparent proxy. If it is necessary to configure the proxy server that is used to connect to the message router, then the proxy server is configured in the ProxyService string. The ProxyService string format is specified as:
If authentication is required for the proxy server, the username and password may be optionally specified before the proxy host.
proxyHost is the IPv4 or IPv6 address or host name of the proxy server.
proxyPort is the port to connect to for a connection. If the port number is not specified, the default for SOCKS5 is port 1080, and the default for Http-Connect is port 3128.
The following examples show how to specify transport channel types. Unless it is otherwise specified, the default port 55555 is used.
The following examples show how to connect to a message router through a proxy server.
Configuring Multiple Hosts for Redundancy and Failover
Some applications might want to have a list of appliances available for connection. Typically these appliances will be in separate geographic locations and use of a host list allows applications to fail over to the alternate connections if the first appliance is unavailable. The host list is configured in the Host property of SessionProperties as a comma separated list of hosts. Each host can optionally include a port number as well. For example, if there are two appliances at 192.168.160.128 and 192.168.160.129, but the second is using the non-default port 50005 for the message bus, the SessionProperties.Host would be configured as:
SessionProperties.Host = "192.168.160.128,192.168.160.129:50005"
In this case, when Connect is called, the API attempts to connect, first to 192.168.160.128, if that connection fails for any reason it attempts to connect to 192.168.160.129:50005. This process is repeated until all entries in the host list are attempted. After each entry has been attempted, if all fail, the session properties ConnectRetries and ReconnectRetriesWaitInMsecs determine the behavior of the API. If ConnectRetries is non-zero, SolClient waits for ReconnectRetriesWaitInMsecs milliseconds then starts connection attempts again from the beginning of the list.
If an established session fails, to any host in the list, when ReconnectRetries is non-zero, then API automatically attempts to reconnect, starting at the beginning of the list. Note that the session connect timer, ConnectTimeoutInMsecs, runs separately for each connection attempt. So an application waiting for a connection established UpNotice or connection failure ConnectFailedError could have to wait up to ( (number of hosts in the hosts list) times (ConnectTimeoutInMsecs) ) for the event.
Multiple Hosts and Guaranteed MessagingIf a client application publishes Guaranteed messages ( NonPersistent or Persistent ) and then a disconnect occurs, the API will automatically reconnect to other listed hosts. However, because another host will not know the state of the publisher flow to the original host, the API must reset publisher flow state. Unacknowledged messages are renumbered and resent by the API. If the alternate router is configured as a replication site this may lead to duplicate messages in the system. It is up to the application to resolve this duplication in what ever way is appropriate to the application.
Applications may wish to configure the session so that auto-reconnect only occurs if no guaranteed messages have been published. This is the legacy behaviour of the API. If this is desired the set the session property GdReconnectFailAction to the value DISCONNECT. This session property can also be set as environment variable which then allows legacy applications to run without modification or recompile.
May be set as an environment variable. (see SessionProperties)
Default: empty string
Set to true ignore errors for duplicate subscription/topic on subscribe or unsubscribe. Default: true
When enabled, a sender ID is automatically included in the Solace-defined fields for each message sent. Default: false
Use 0 to disable keep-alive. If not zero, the minimum valid value is 50. Default: 3000.
The number of keep-alive intervals with no received traffic that are allowed before a session is declared down. The minimum valid value is 3.
This property specifies the ServiceName of Service Principle Name (SPN) for Kerberos. It is used for all entries specified by the property Host The Service Principal Name (SPN) has the format "ServiceName/ApplianceName@REALM" where ServiceName is specified by this property, ApplianceName is the host portion of an entry specified by Host, and REALM is obtained from the Kerberos configuration. The maximum length for an SPN is 256 characters.
The maximum number of flows supported on this session. Default: 100.
Maximum amount of time (in milliseconds) to wait for session property modification. Default: 100000 (10 seconds)
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 appliance does not have No Local support, the session connects fail with subcode NoLocalNotSupported. Default: false
The optional Issuer identifier URI for OAUTH2 access token based authentication.
A read-only informational string that indicates the default reply-to destination string that is used when a sent request message does not have a reply-to destination specified. See SendRequest(IMessage, IMessage, Int32) for more details. This parameter is only valid when session is connected. Defaults to empty string, when it is not connected.
The password required for authentication.
May be set as an environment variable. (see SessionProperties)Default: empty string
This property is deprecated. While still supported, the port number can also now be specified as part of the host in Host (e.g. "hostname:55555"). In general, port numbers are not needed to be specified except in special situations. If this property is set, this port number is used for all entries in Host that do not explicitly specify port.It represents the port number to connect to. Valid range is 0..65535; 0 means use default for the selected CompressionLevel.
Default: 0 (getting this property returns the appropriate default port: 55003 if compression is enabled, 55555 otherwise).
The timeout (in milliseconds) for an endpoint provision or deprovision confirmation. The valid range is >= 1000.
Set to true to allow the API to remember subscriptions and reapply them upon a session reconnect.
Note: Reapply subscriptions will only apply direct topic subscriptions unpon a Session reconnect. It will not reapply topic subscriptions on durable and non-durable endpoints.Default: false
How many times to retry to connect to the host appliance (or list of appliances) after a connected session goes down.
When using a host list, each time the API works through the host list without establishing a connection is considered a reconnect retry. If the API reattempts a reconnect retry, it begins with the first host listed. For example, if a ReconnectRetries 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 reconnect retries.
After each unsuccessful attempt to reconnect to a host, the API waits for the amount of time set for ReconnectRetriesWaitInMsecs 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 ConnectRetriesPerHost.
See Host for more details on the reconnect logic.
Zero means no automatic reconnection attempts (that is, try once and give up). -1 means try to reconnect forever. The valid range is >= -1. Default: 0
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 ReconnectRetriesWaitInMsecs, and then makes another connect or reconnect attempt. ConnectRetriesPerHost sets how many connection or reconnection attempts can be made before moving to the next host in the list.
The valid range is >=0. Default: 3000
Controls the buffering of transmit messages. When sending small messages, the session buffer size should be set to multiple times the typical message size to improve performance. Regardless of the buffer size, the API always accepts at least one message to transmit. So even if a single message's size exceeds this value, it is accepted and transmitted, as along as the current buffered data is zero. However, no more messages are accepted until the amount of data buffered is reduced below this value.
Default: 90000 ///
Set to true 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 messagehas been processed by the appliance. For the latter you must used Guaranteed Message Delivery mode and wait for the session event (Acknowledgement) that acknowledges the message.
Note: The API does not support a synchronous (send and wait for acknowledgement operation), however such an operation can be easily implemented in an application by waiting for a Acknowledgement.
The socket receive buffer size value. 0 indicates do not set and leave at operating system default. The valid range is 0 or >= 1024.
The socket send buffer size value. 0 indicates do not set and leave at operating system default. The valid range is 0 or >= 1024.
Specifies a comma separated list of the cipher suites. Allowed cipher suites are: 'ECDHE-RSA-AES256-GCM-SHA384', 'ECDHE-RSA-AES256-SHA384', 'ECDHE-RSA-AES256-SHA', 'AES256-GCM-SHA384', 'AES256-SHA256', 'AES256-SHA', 'ECDHE-RSA-DES-CBC3-SHA', 'DES-CBC3-SHA', 'ECDHE-RSA-AES128-GCM-SHA256', 'ECDHE-RSA-AES128-SHA256', 'ECDHE-RSA-AES128-SHA', 'AES128-GCM-SHA256', 'AES128-SHA256', 'AES128-SHA', 'RC4-SHA', 'RC4-MD5'.
The client certificate object to be used by ISession objects when the session's AuthenticationScheme property is set to CLIENT_CERTIFICATE. When specified, the certificate object must have a valid PrivateKey property referring to either a or a private key object. This property is mutually exclusive with SSLClientCertificateFile, SSLClientPrivateKeyFile, and SSLClientPrivateKeyFilePassword. Either the certificate and private key are specified via the X509Certificate2 object, or they are specified via the aforementioned filename-based properties. If both are specified, an exception will be thrown.
This Property is restricted and has different behaviour for the following SessionProperties operation: Serialization, this Property is not serialized; FromDictionary(IDictionaryString, String), this Property can not be set from this operation; ToDictionary, this Property can not be added to the Dictionary result of this operation; ToString, this Property does not have an equivalent ToString field;
Specifies a transport protocol that SSL connection will be downgraded to after client authentication. Allowed transport protocol is "PLAIN_TEXT"
Specifies a comma separated list of excluded SSL protocol(s). Valid protocols are 'SSLv3', 'TLSv1', 'TLSv1.1', 'TLSv1.2'.
This property is deprecated.
NOT RECOMMENDED Per RFC-6125 section 6.4.4, the Common Name (CN) of a certificate should not be used to validate the certificate. Instead SSLValidateCertificateHost (enabled by default) indicates that the server certificate must contain a Subject Alternate Name (SAN) that matches the host name (Host).
This property is only used if SSLValidateCertificateHost is disabled. This property specifies a comma separated list of acceptable common names in certificate validation. The number of common names specified by an applications is limited to 16. Leading and trailing whitespaces are considered to be part of the common names and are not ignored. If the application does not provide any common names, there is no common name verification.
Default: empty string
The collection of all trusted root certificates to be used by ISession objects. The trusted root certificates are used in establishing trust with a PubSub+ message broker when connecting via a protocol over SSL/TLS. This occurs when specifying protocols such as tcps or https in a Host. This property is mutually exclusive with SSLTrustStoreDir. Trusted certificates may be specified with one property or the other, but not both. If both are specified, an exception will be thrown when the session is created with CreateSession(SessionProperties, EventHandlerMessageEventArgs, EventHandlerSessionEventArgs). Trusted certificate store can be invalid when there are no valid certificates in the collection. An exception will be thrown when the session is created with CreateSession(SessionProperties, EventHandlerMessageEventArgs, EventHandlerSessionEventArgs).
Specifies the directory where the trusted certificates are. The maximum depth for the certificate chain verification that shall be allowed is 3.
Indicates if the certificate validation with certificates in the truststore is enabled. Default: true
Note on certificate validation: When validating certificates, the messaging APIs for C and .NET use the following validation rules, after building the chain from the server certificate to a self-signed root certificate using certificates presented by the server and certificates in the trust store :
Indicates if the session connection should fail when a certificate with an invalid date is received.
This property only applies when SSLValidateCertificate is enabled.
Indicates if the sesssion connection should fail when a certificate with an invalid host is received. When enabled, and connecting to a named host, the certificate Subject Alternative Name must contain a DNS entry that matches the host string.
When enabled, and connecting to a host by IP address, the certificate Subject Alternative Name must contain an IP Address that matches.
If there is no Subject Alternate Name the certificate common name (CN) may be checked against the host string.
This property only applies when SSLValidateCertificate is enabled.
Set to true to enable blocking subscribe/unsubscribe operation.
The timeout (in milliseconds) for an add or remove subscription confirmation. The valid range is >= 1000. Default: 10000
Subscriber priorities are used to choose a client to receive messages that are sent with the DeliverToOne property set to true. These messages are sent to the subscriber with the highest priority. Subscribers have two priorities; this priority (SubscriberLocalPriority) is for messages published locally.
The valid range is 1..4. Default: 1
Subscriber priorities are used to choose a client to receive messages that are sent with the DeliverToOne property set to true. These messages are sent to the subscriber with the highest priority. Subscribers have two priorities; this priority (SubscriberNetworkPriority) is for messages published on appliances other than the one that the client is connected to.
Valid range is 1..4. Default: 1
Set to true to enable TCP No Delay on the underlying TCP connection.
Set to true to have the API dispatch messages based on topic. For more details see the IMessageDispatcher documentation. Default: false
A read-only informational string that provides 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. Returns empty string, if the session has not been connected.
The username required for authentication. Default: empty string
A read-only session property that indicates the Virtual Router Name of the connected appliance. Used in building appliance endpoint and destination objects such as Queues. Appliance endpoints and destinations created with a virtual router name are valid for use with that appliance, or to address destinations on remote appliances (in a multiple-appliance network) when publishing messages.
Applications requiring the virtual router name need not poll this property every time it is needed, and may cache the name. Applications should query the name once after connecting the session, and again after a reconnect operation reports the VirtualRouterNameChanged session event.When not connected, an empty string is returned.
The name of the Message VPN to attempt to join when connecting to an appliance running SolOS-TR. Default: empty string
A read-only session property that indicates which Message VPN the session is connected to. When not connected, or when not in client mode, an empty string is returned.