| SessionProperties Properties |
The SessionProperties type exposes the following members.
Properties
| Name | Description | |
|---|---|---|
|
AckEventMode |
Specifies if an Acknowledgement session event acknowledges a single message
(PER_MSG) or a range of messages (WINDOWED).
Setting this property to WINDOWED will not affect RejectedMessageError events, they will still be emitted on a per message basis. Default: PER_MSG |
|
|
ADPublishAckTimerInMsecs |
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 |
|
|
ADPublishWindowSize |
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.
|
|
|
AuthenticationScheme |
Specifies the authentication scheme to be used by the corresponding ISession. For more information about the
types of authentication schemes that can be set, see AuthenticationSchemes.
Default: BASIC |
|
|
BindIP |
(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
|
|
|
BlockingWriteTimeoutInMsecs |
The timeout period (in milliseconds) for blocking write operation. The valid range is > 0.
Default: 100000 |
|
|
BlockWhileConnecting |
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
|
|
|
CalculateMessageExpiration |
When this property is set to true and the message's TimeToLive is set (has a non-zero value), the API updates the
message's Expiration property with the sum of message's Time-To-Live and the UTC timestamp value after it has been sent or received.
Default: false
|
|
|
ClientDescription |
A string that describes the application instance. This string is available from SolAdmin or CLI.
|
|
|
ClientMode | Obsolete.
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.
|
|
|
ClientName |
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
|
|
|
CompressionLevel |
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)
|
|
|
ConnectBlocking |
Use true to enable blocking connection operation.
Default: true
|
|
|
ConnectRetries |
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 |
|
|
ConnectRetriesPerHost |
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. |
|
|
ConnectTimeoutInMsecs |
The timeout period (in milliseconds) for a connect operation. The valid range is > 0.
Default: 30000 |
|
|
Count |
Returns the count of properties.
(Inherited from BaseProperties.) |
|
|
GdReconnectFailAction |
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 |
|
|
GenerateReceiveTimestamps |
When enabled, a receive timestamp is recorded for each message and passed
back as a property of IMessage.
Default: false
|
|
|
GenerateSendTimestamps |
When enabled, a send timestamp is automatically generated as a message property for each message sent.
Default: false
|
|
|
GenerateSequenceNumber |
When enabled, a sequence number is automatically included in the Solace-defined fields for each message sent.
Default: false
|
|
|
Host |
The IP 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 entryHost 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:]Host[:Port][%ProxyService] Protocol is the protocol used for the transport channel. The valid values are:
Host is the IP address (or host name) to connect to for a connection. 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: [ProxyProtocol]://[username:password@]proxyHost[:proxyPort]
If authentication is required for the proxy server, the username and password may be optionally specified before the proxy host. proxyHost is the IP 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 FailoverSome 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 |
|
|
IgnoreDuplicateSubscriptionError |
Set to true ignore errors for duplicate subscription/topic on subscribe or unsubscribe.
Default: true
|
|
|
IncludeSenderId |
When enabled, a sender ID is automatically included in the Solace-defined fields for each message sent.
Default: false
|
|
|
KeepAliveIntervalInMsecs |
Use 0 to disable keep-alive. If not zero, the minimum valid value is 50.
Default: 3000.
|
|
|
KeepAliveIntervalsLimit |
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.
|
|
|
KRBServiceName |
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.
|
|
|
MaxFlowsPerSession | Obsolete.
The maximum number of flows supported on this session. Default: 100.
|
|
|
ModifyPropertyTimeoutInMsecs |
Maximum amount of time (in milliseconds) to wait for session property modification.
Default: 100000 (10 seconds)
|
|
|
NoLocal |
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
|
|
|
P2PInboxInUse |
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.
|
|
|
Password |
The password required for authentication.
May be set as an environment variable. (see SessionProperties) Default: empty string |
|
|
Port | Obsolete. 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). |
|
|
ProvisionTimeoutInMsecs |
The timeout (in milliseconds) for an endpoint provision or deprovision confirmation.
The valid range is >= 1000.
Default: 3000 |
|
|
ReapplySubscriptions |
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 |
|
|
ReconnectRetries |
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 |
|
|
ReconnectRetriesWaitInMsecs |
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 |
|
|
SdkBufferSize |
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 /// |
|
|
SendBlocking |
Set to true to enable blocking send operation.
Default: true |
|
|
SocketReceiveBufferSizeInBytes |
The socket receive buffer size value. 0 indicates do not set and leave at operating system default. The
valid range is 0 or >= 1024.
Default: 150000 |
|
|
SocketSendBufferSizeInBytes |
The socket send buffer size value. 0 indicates do not set and leave at operating system default. The
valid range is 0 or >= 1024.
Default: 90000 |
|
|
SSLCipherSuites |
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'.
Default: "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" |
|
|
SSLClientCertificateFile |
The filename of the client certificate file. Required when AuthenticationScheme
is set to CLIENT_CERTIFICATE. When specified,
a value of "" (or empty string) will cause a ParamOutOfRange failure when
connecting the session.
Default: null |
|
|
SSLClientPrivateKeyFile |
The filename of the client's private key. Required when AuthenticationScheme
is set to CLIENT_CERTIFICATE. When specified,
a value of "" (or empty string) will cause a ParamOutOfRange failure when
connecting the session.
Default: null |
|
|
SSLClientPrivateKeyFilePassword |
The password to decrypt and read the SSLClientPrivateKeyFile.
This property is optional. When specified,
a value of "" (or empty string) will cause a ParamOutOfRange failure when
connecting the session.
Default: null |
|
|
SSLConnectionDowngradeTo |
Specifies a transport protocol that SSL connection will be downgraded to after client authentication. Allowed transport protocol is "PLAIN_TEXT"
Default: null |
|
|
SSLExcludedProtocols |
Specifies a comma separated list of excluded SSL protocol(s).
Valid protocols are 'SSLv3', 'TLSv1', 'TLSv1.1', 'TLSv1.2'.
Default: "" |
|
|
SSLProtocol | Obsolete.
This property is deprecated.
|
|
|
SSLTrustedCommonNameList |
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.
If the application does not provide any common names, there is no common name verification.
Default: empty string |
|
|
SSLTrustStoreDir |
Specifies the directory where the trusted certificates are. A maximum of 32 certificates will be loaded.
The maximum depth for the certificate chain verification that shall be allowed is 3.
Default: null |
|
|
SSLValidateCertificate |
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 :
Default: true |
|
|
SSLValidateCertificateDate |
Indicates if the session connection should fail when a certificate with an invalid date is received.
Default: true |
|
|
SubscribeBlocking |
Set to true to enable blocking subscribe/unsubscribe operation.
Default: true |
|
|
SubscribeConfirmTimeoutInMsecs |
The timeout (in milliseconds) for an add or remove subscription confirmation.
The valid range is >= 1000.
Default: 10000
|
|
|
SubscriberLocalPriority |
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 |
|
|
SubscriberNetworkPriority |
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 |
|
|
TcpNoDelay |
Set to true to enable TCP No Delay on the underlying TCP connection.
Default: true |
|
|
TopicDispatch |
Set to true to have the API dispatch messages based on topic. For more details see the
IMessageDispatcher documentation.
Default: false
|
|
|
UserIdentification |
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.
|
|
|
UserName |
The username required for authentication.
Default: empty string
|
|
|
VirtualRouterName |
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. |
|
|
VPNName |
The name of the Message VPN to attempt to join when connecting to an appliance running SolOS-TR.
Default: empty string
|
|
|
VPNNameInUse |
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.
|
See Also