SolaceSystems.Solclient.Messaging Namespace



BaseProperties An abstract base class for all properties in the API.
BrowserProperties Used when creating a new Browser instance.
ContextEventArgs Passed as an argument to Context EventHandler delegate.
ContextFactory ContextFactory is a singleton which represents the first point of contact or entry point to the APIs. It has the following responsibilities:
  • Exposes the initialization and cleanup routines. API initialization is required before using any of its components.
  • Acts as a factory of the different components of the API, such as contexts, messages, non-temporary destinations, durable endpoint instances, and subscriptions.
  • Exposes a number of useful statistics at the message and memory pool levels.
  • Exposes logging facilities to enable client applications to receive log events and control the log level.
  • ContextFactoryProperties Defines Context Factory properties.
    ContextProperties Defines Context properties. It is passed in to the ContextFactory's CreateContext method.
    EndpointProperties EndpointProperties is used to specify the attributes of an endpoint resource when it is created on the appliance (explicitly or implicitly).
    FatalErrorException A fatal error exception thrown when a serious and unrecoverable exception is encountered.
    FieldNotFoundException This exception is thrown from various IMessage and SDT container accessors.
    FlowEventArgs An EventArgs instance that is passed through a flow's EventHandler. It represents an event of interest occuring at the flow level.
    FlowProperties Defines Flow properties.
    Helper A Helper Utilities class
    HelperDestination Utilities class for working with IDestination, it includes:
  • Helper method to get the string encoding of a given IDestination.
  • Helper methods to create IQueue and ITopic given their corresponding string encoding.
  • MessageEventArgs Passed as an argument to the message receive EventHandler delegate.
    MessageUserPropertyConstants An interface for constant property values to define user message properties that have a special reserved meaning or behaviour.
    ModifyPropertyFlag Specifies the possible flags which can be used with ModifyClientInfo(SessionPropertiesPROPERTY, Object, Int32, Object)
    OperationErrorException An operation error exception thrown when an API call fails.
    ProvisionFlag Defines the possible flags that can be used in Provision and Deprovision methods in ISession methods.
    ReplayStartLocation This abstract class specifies a message replay start location In includes factory methods for creating a ReplayStartLocation object.
    ReplayStartLocationBeginning The ReplayStartLocationBeginning class represents a Replay Start from the beginning of the Replay Log. for ReplayStartLocation
    ReplayStartLocationDate The ReplayStartLocationDate class represents a Replay Start from a given DateTime. The DateTime is always converted to UTC time. for ReplayStartLocation
    SDKErrorInfo This represents more detailed error information for a failed API call. This is in addition to the return code.
    SessionEventArgs An EventArgs instance that is passed to the session EventHandler.
    SessionProperties Session initialization properties.

    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 sesssion property list passed to CreateSession(SessionProperties, EventHandlerMessageEventArgs, EventHandlerSessionEventArgs)

    The names of the environment variables are based on the native library property names.

    The following environment variables are recognized:

    • SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION GdReconnectFailAction The acceptable strings for this environment variable are also based on the underlying native library:

    SolLogInfo This represents a log info object.
    STDException Standard SDT operation exception.
    SubscribeFlag Defines the possible flags that can be used in the following methods: Subscribe(IEndpoint, ISubscription, Int32, Object) and Subscribe(IEndpoint, ISubscription, Int32, Object)Subscribe(IDispatchTarget, Int32, Object) and Unsubscribe(IDispatchTarget, Int32, Object)
    TimerTask Represents a timer task to be executed in the context of the corresponding IContext thread. To create and start a TimerTask please see Start(IContext, TimerCallback, TimerMode, Int64, Object).
    TopicProperties Used to create Topics with further specialized options.
    TransactedSessionProperties Defines the properties for a ITransactedSession
    XpeProperties Defines Xpe properties; passed into Xpe factory method.


    IBrowser A Browser allows client applications to look at messages spooled on Endpoints without removing them. Messages are browsed from oldest to newest. After being browsed, messages are still available for consumption over normal flows. However, it is possible to selectively remove messages from the persistent store of an Endpoint, in this case, these removed messages will no longer be available for consumption. One typical application is to use browsers to allow message bus administrators to remove “stuck” Guaranteed messages from an endpoint without having to modify or disrupt existing applications. A message can get stuck if: It hass been received by an application, but for some reason, that application has failed to acknowledge it. All active message selectors have failed to match this particular message and therefore the message bus has not delivered it to any client yet. The current release only supports browsing Endpoints of type Queue. Note that the delivery restrictions imposed by the queue’s Access type (exclusive or non-exclusive), do not apply when browsing messages with a Browser.
    ICapability This represents the appliance capability type and value.
    IClientName IClientName represents a remote client. It is used to identify a client currently connected and on behalf of which an application wants to add/remove subscriptions.

    To acquire an IClientName instance, applications must call CreateClientName(String)

    To add or remove subscriptions on behalf of a remote client, applications must call Subscribe(IEndpoint, ISubscription, Int32, Object) and Unsubscribe(IEndpoint, ISubscription, Int32, Object) respectively.

    IContext A context represents a processing context in which session instances are created. It is used to organize communications between an application and a Solace appliance. Contexts act as containers for configuring one or more sessions and handling session-related events.

    A context is an active object that initializes and manages its own thread. The life cycle of the owned thread is bound to the life cycle of the context. A context-owned thread drives I/O and notification events of registered delegates of the context.

    All callbacks (or delegate invocation) from the API to the application, message receive callbacks, event callback, and timer callbacks, run from the context thread. Additionally the context thread must run to detect relief from flow control and unblock waiting application threads. The context thread must run to complete the session connection sequence and unblock applications waiting for connection complete. The context thread must run to unblock applications waiting for confirmation on subscription requests. Consequently, applications must not block in callback/delegate routines. Waiting in callback routines can deadlock the application or at a minimum severely degrade receive performance. Deferring SolClient processing by running for excessively long periods of time in the callback routines prevents the API from unblocking other application threads that might be waiting for confirmation of sent messages, or blocked in flow control situations.

    The API typically detects when the application has re-entered the API from a callback and will never block. Consequently applications can expect to see SOLCLIENT_WOULD_BLOCK return codes when making API calls from a callback routine, even if the function call would be blocking in other threads. Generally if a function could block because of TCP flow control, SOLCLIENT_WOULD_BLOCK is returned when that function is called from a callback, irrespective of the session property SendBlocking. Further if the application explicitly sets WaitForConfirm on a subscription method (subscribe or unsubscribe) API call made from a callback routine, that function call will return SOLCLIENT_FAIL and set the subcode to ParamConflict

    Important: Disposing a context must not be performed in a context callback delegate for the context being disposed. This includes all sessions(ISession), flows(IFlow) and timers (TimerTask) on the context.

    Context instances are created through a factory method in ContextFactory. A context has the following responsibilities: Initialization and management of the context-owned thread. Factory and container of session instances. Note that IContext instances can only be created by the ContextFactory.
    IDestination Represents a Destination messages can be sent to. A destination can be one of the following: {Topic, Queue}
    IDispatchTarget It encapsulates an ISubscription and message callback delegate. This tuple is used as an argument for IMessageDispatcher operations.
    IDurableTopicEndpoint Represents a durable Topic Endpoint. This interface has been made obsolete in favor of ITopicEndpoint.
    IEndpoint Represents an Endpoint one of ITopicEndpoint or IQueue
    IFlow A flow is an API concept that allows the application to receive messages from an endpoint on the appliance (a IQueue or ITopicEndpoint on a Solace appliance running SolOS-TR). Flows are not used by clients that receive Direct messages. Rather, Direct messages are received by clients with matching subscriptions directly from the appliance’s message bus through sessions instead of binding to a specific endpoint on the message bus.

    Disposing a flow must not be performed in the flow callback delegate of the flow being disposed.

    IMessage The super interface of any message sent or received over this messaging API.

    Client applications must dispose of messages (by calling Dispose()) as soon as they are done with them.

    Note: Unless indicated otherwise, mutable IMessage's properties are accessed and assigned by value and not by reference. In other words, the property's getter returns a copy of the IMessage's mutable internal state and its setter takes a copy of the passed in mutable value.


    In the typical scenarios, using Subscribe(ISubscription, Boolean) , CreateFlow(FlowProperties, IEndpoint, ISubscription, EventHandlerMessageEventArgs, EventHandlerFlowEventArgs) or CreateFlow(FlowProperties, IEndpoint, ISubscription, EventHandlerMessageEventArgs, EventHandlerFlowEventArgs, EndpointProperties) client applications can register interest to receive messages with destinations matching the set of added subscription(s). All matching messages are received within the context of the message callback delegate. There's one delegate registered per session or flow.

    IMessageDispatcher is an interface abstraction which enables the API to further demultiplex messages to consumers based on registered subscriptions (within aISession or IFlow). Dispatching/demultiplexing incoming messages based on topics allows different callback delegates to be invoked based on the received message's topic. Full wildcard subscription syntax is supported see ITopic for more details.

    To better illustrate the usage of this feature, consider the following examples: A client application registers interest to receive messages matching 'car/>', it does so by calling the Subscribe method on an ISession instance. All messages matching this wildcard topic are received over the message callback delegate. In this case, the client receives any message matching 'car/>', for example: 'car/gmc' or 'car/toyota' Using the Topic dispatch feature, the client application (as described above) can demultiplex incoming messages to different callback delegates. For example, it can create a couple of IDispatchTarget instances; the first one with 'car/gmc' as topic subscription and the second with 'car/toyota'. Then it can call the ISession's Subscribe(IDispatchTarget...) method to add these subscriptions along with the delegates to invoke when receiving matching messages on 'car/gmc' or 'car/toyota'. Delivered message with destinations outside of these two topic subscriptions, are still received over the default message callback delegate associated with the ISession instance.

    Note: In order to use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.

    IProperties Super interface for all properties. This interface is used in builder/factory design patterns.
    IQueue Represents a Queue.
    IReplayStartLocation Identifies a message replay start location object instance.
    IReplicationGroupMessageId Interface for replication group message ids. Can be used to specify a IReplayStartLocation for the message after this id. The IReplayStartLocation is set in the corresponding flow property ReplayStartLocationEx.
    ISession Represents a messaging API session. When a context is established, one or more sessions can be created within that context. A session (modeled as an interface called ISession) creates a client connection to the Solace appliance for sending and receiving messages. It also provides the following: Connect and disconnect on demand.Factory of IFlow instances.Factory of temporary destinations (see IDestination) .Factory of non-durable endpoints (see IDurableTopicEndpoint and IQueue) .Factory of cache session instances (see ICacheSession) .Ability to make request/replies.Subscribe and unsubscribe.Ability to update and retrieve session properties. Ability to retrieve session statistics (see IStatsAccessible).

    Disposing a session must not be performed in a session callback delegate for the session being disposed. This includes all flows on the session.

    IStatsAccessible Implemented by ISession and IFlow, this interface exposes Transmit and Receive statistics collected by the messaging API.
    ISubscriberEndpoint Deprecated.
    ISubscription Represents a Subscription, one of {IXpe, ITopic}.
    ITopic Represents a Topic.

    Supported Topic Syntax

    Topics are in the form level1/level2/level3. The total length of a topic can be 250 bytes.

    Supported Subscription Syntax

    Subscriptions are in the form level1/level2/level3. The total length of a subscription can be 250 bytes.The '>' character, when alone at the final level of a subscription, means match one or more levels at the end of a received topic. For example, level1/level2/level3/> will match level1/level2/level3/level4 and level1/level2/level3/level4/level5, but not level1/level2/level3. '>' elsewhere in the subscription has no special meaning. For example, level1>/level2 .The '*' character is a wildcard. When alone at a level, it means match any string at that level in a received topic. For example, level1/ * /level3 matches /level1/level2/level3. '*' can also be used to match a level that starts with a specified string. For example level1/lev* /level3 matches /level1/level2/level3. A '*'cannot appear at the beginning or within a string. For example, "lev*1" and "*evel" are not valid.
    ITopicEndpoint Represents a Topic Endpoint (Durable or Non-Durable). This interface obsoletes IDurableTopicEndpoint.
    ITransactedSession ITransactedSession groups a number of Guaranteed Delivery flows into transactions. Once successfully created, an ITransactedSession instance has an in-progress transaction but no subordinate Guarenteed Delivery consumer flows. Consumer flows can be created by calling CreateFlow(). Transacted sessions are not thread-safe and should not be used by mulitple application threads. The legal threading model usage of transacted sessions is limited to:
    • If messages are received over the message dispatcher thread (async), client applications must invoke commit/rollback/sendMsg from the context of that thread (i.e. in the context of the message dispatcher thread CreateMessageDispatcher).
    • If messages are received from an application thread by calling ReceiveMsg(Int32) directly, commit/rollback/sendMsg/receiveMsg functions must be called in the context of the same application thread.
    IVersion The version information for the messaging API.
    IXpe Represents an Xpath expression.


    OnSolLogInfo Log event info delegate.


    AuthenticationSchemes Possible authentication schemes that can be used when connecting and authenticating with the appliance.
    This property specifies the authentication scheme. Default: BASIC.
    BrowserPropertiesPROPERTY Enumeration of public properties.
    CapabilityType Appliance capabilities that can vary depending on the appliance platform.
    EndpointPropertiesEndpointAccessType Defines the access type when provisioning a new IEndpoint on the appliance. This applies only to Endpoints of type durable Queues.
    EndpointPropertiesEndpointDiscardBehavior Defines the endpoint behavior when a message cannot be added to an endpoint (for example, maximum quota exceeded). These options control the action of the appliance towards the publisher.
    EndpointPropertiesEndpointPermission Defines what permissions are granted for sessions initiated by users other than the owner of the Endpoint (all others).
    EndpointPropertiesPROPERTY Enum of public Endpoint properties.
    FlowEvent Flow event enumeration.
    FlowPropertiesPROPERTY An enum list of Flow properties.
    MessageAckMode Defines the possible acknowledgements modes for received Guaranteed Delivery messages.
    MessageCacheStatus The cache status of a received message.
    MessageDeliveryMode The different message delivery modes.
    MessageDump Options to control the message dump utility. Used in Dump(MessageDump).
    MessageLevelStatistic The statistics associated with message memory management at the message level.
    MessageOutcome Represents the type for supported message settlement outcomes. To be used with Settle(Int64, MessageOutcome)
    QuantaLevelStatistic The statistics associated with message memory management at the quanta level.
    ReturnCode The return code from certain API calls.
    SDKErrorSubcode A subcode that gives more detailed error information. The last sub-code is stored on a per-thread basis and can be retrieved by an application thread using GetLastSDKErrorInfo of ContextFactory. Applications can take different actions based on the subcode.
    SessionEvent The session event enumeration; this is returned with session event delegate EventArgs.
    SessionPropertiesAckMode Specifies if Acknowledgement acknowledges a single message or a range of messages. AckEventMode
    SessionPropertiesGuaranteedDeliveryReconnectFailAction 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 state of the previous router. It can also occur if the time to reconnect to the same router exceeds the publisher flow timeout on the router. GdReconnectFailAction
    SessionPropertiesPROPERTY An enum list of Session properties.
    SolLogLevel Log Level
    Stats_Rx An Enumeration of the various receive statistics. Used as a key in the receive stats dictionary. See GetRxStats in IStatsAccessible.
    Stats_Tx An enumeration of the various transmit statistics. This is used as a key in the transmit stats dictionary. See GetTxStats() in IStatsAccessible
    TimerMode Possible modes of TimerTask.
    TransactedSessionPropertiesPROPERTY An enum list of TransactedSessionProperties
    UserCos Defines the possible Class of Service level of a given message.

    The Class of Service has different semantics for direct and guaranteed messages. For direct messaging, it determines the WRR weight for the message. For guaranteed messaging, it indicates the discard eligibility of the message if the endpoint is congested (see LowPriorityMsgCongestion)