Click or drag to resize

SolaceSystems.Solclient.Messaging Namespace

version: 10.9.0
SolaceSystems.Solclient.Messaging
Classes
  ClassDescription
Public classBaseProperties
An abstract base class for all properties in the API.
Public classBrowserProperties
Used when creating a new Browser instance.
Public classContextEventArgs
Passed as an argument to Context EventHandler delegate.
Public classContextFactory
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.
  • Public classContextFactoryProperties
    Defines Context Factory properties.
    Public classContextProperties
    Defines Context properties. It is passed in to the ContextFactory's CreateContext method.
    Public classEndpointProperties
    EndpointProperties is used to specify the attributes of an endpoint resource when it is created on the appliance (explicitly or implicitly).
    Public classFatalErrorException
    A fatal error exception thrown when a serious and unrecoverable exception is encountered.
    Public classFieldNotFoundException
    This exception is thrown from various IMessage and SDT container accessors.
    Public classFlowEventArgs
    An EventArgs instance that is passed through a flow's EventHandler. It represents an event of interest occuring at the flow level.
    Public classFlowProperties
    Defines Flow properties.
    Public classHelper
    A Helper Utilities class
    Public classHelperDestination
    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.
  • Public classMessageEventArgs
    Passed as an argument to the message receive EventHandler delegate.
    Public classModifyPropertyFlag
    Public classOperationErrorException
    An operation error exception thrown when an API call fails.
    Public classProvisionFlag
    Defines the possible flags that can be used in Provision and Deprovision methods in ISession methods.
    Public classReplayStartLocation
    This abstract class specifies a message replay start location In includes factory methods for creating a ReplayStartLocation object.
    Public classReplayStartLocationBeginning
    The ReplayStartLocationBeginning class represents a Replay Start from the beginning of the Replay Log. for ReplayStartLocation
    Public classReplayStartLocationDate
    The ReplayStartLocationDate class represents a Replay Start from a given DateTime. The DateTime is always converted to UTC time. for ReplayStartLocation
    Public classSDKErrorInfo
    This represents more detailed error information for a failed API call. This is in addition to the return code.
    Public classSessionEventArgs
    An EventArgs instance that is passed to the session EventHandler.
    Public classSessionProperties
    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_PASSWORD Password
    • SOLCLIENT_SESSION_PROP_HOST Host
    • SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION GdReconnectFailAction The acceptable strings for this environment variable are also based on the underlying native library:
      1. "SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION_AUTO_RETRY" (AUTO_RETRY)
      2. "SOLCLIENT_SESSION_PROP_GD_RECONNECT_FAIL_ACTION_DISCONNECT" (DISCONNECT)

    Public classSolLogInfo
    This represents a log info object.
    Public classSTDException
    Standard SDT operation exception.
    Public classSubscribeFlag
    Public classTimerTask
    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).
    Public classTopicProperties
    Used to create Topics with further specialized options.
    Public classTransactedSessionProperties
    Defines the properties for a ITransactedSession
    Public classXpeProperties
    Defines Xpe properties; passed into Xpe factory method.
    Interfaces
      InterfaceDescription
    Public interfaceIBrowser
    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.
    Public interfaceICapability
    This represents the appliance capability type and value.
    Public interfaceIClientName
    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.

    Public interfaceIContext
    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.
    Public interfaceIDestination
    Represents a Destination messages can be sent to. A destination can be one of the following: {Topic, Queue}
    Public interfaceIDispatchTarget
    It encapsulates an ISubscription and message callback delegate. This tuple is used as an argument for IMessageDispatcher operations.
    Public interfaceIDurableTopicEndpoint Obsolete.
    Represents a durable Topic Endpoint. This interface has been made obsolete in favor of ITopicEndpoint.
    Public interfaceIEndpoint
    Represents an Endpoint one of ITopicEndpoint or IQueue
    Public interfaceIFlow
    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.

    Public interfaceIMessage
    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.

    Public interfaceIMessageDispatcher

    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.

    Public interfaceIProperties
    Super interface for all properties. This interface is used in builder/factory design patterns.
    Public interfaceIQueue
    Represents a Queue.
    Public interfaceISession
    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.

    Public interfaceIStatsAccessible
    Implemented by ISession and IFlow, this interface exposes Transmit and Receive statistics collected by the messaging API.
    Public interfaceISubscriberEndpoint
    Deprecated.
    Public interfaceISubscription
    Represents a Subscription, one of {IXpe, ITopic}.
    Public interfaceITopic
    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.
    Public interfaceITopicEndpoint
    Represents a Topic Endpoint (Durable or Non-Durable). This interface obsoletes IDurableTopicEndpoint.
    Public interfaceITransactedSession
    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.
    Public interfaceIVersion
    The version information for the messaging API.
    Public interfaceIXpe
    Represents an Xpath expression.
    Delegates
      DelegateDescription
    Public delegateOnSolLogInfo
    Log event info delegate.
    Enumerations
      EnumerationDescription
    Public enumerationAuthenticationSchemes
    Possible authentication schemes that can be used when connecting and authenticating with the appliance.
    This property specifies the authentication scheme. Default: ::SOLCLIENT_SESSION_PROP_DEFAULT_AUTHENTICATION_SCHEME.
    Public enumerationBrowserPropertiesPROPERTY
    Enumeration of public properties.
    Public enumerationCapabilityType
    Appliance capabilities that can vary depending on the appliance platform.
    Public enumerationEndpointPropertiesEndpointAccessType
    Defines the access type when provisioning a new IEndpoint on the appliance. This applies only to Endpoints of type durable Queues.
    Public enumerationEndpointPropertiesEndpointDiscardBehavior
    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.
    Public enumerationEndpointPropertiesEndpointPermission
    Defines what permissions are granted for sessions initiated by users other than the owner of the Endpoint (all others).
    Public enumerationEndpointPropertiesPROPERTY
    Enum of public Endpoint properties.
    Public enumerationFlowEvent
    Flow event enumeration.
    Public enumerationFlowPropertiesPROPERTY
    An enum list of Flow properties.
    Public enumerationMessageAckMode
    Defines the possible acknowledgements modes for received Guaranteed Delivery messages.
    Public enumerationMessageCacheStatus
    The cache status of a received message.
    Public enumerationMessageDeliveryMode
    The different message delivery modes.
    Public enumerationMessageDump
    Options to control the message dump utility. Used in Dump(MessageDump).
    Public enumerationMessageLevelStatistic
    The statistics associated with message memory management at the message level.
    Public enumerationQuantaLevelStatistic
    The statistics associated with message memory management at the quanta level.
    Public enumerationReturnCode
    The return code from certain API calls.
    Public enumerationSDKErrorSubcode
    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.
    Public enumerationSessionEvent
    The session event enumeration; this is returned with session event delegate EventArgs.
    Public enumerationSessionPropertiesAckMode
    Specifies if Acknowledgement acknowledges a single message or a range of messages. AckEventMode
    Public enumerationSessionPropertiesGuaranteedDeliveryReconnectFailAction
    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
    Public enumerationSessionPropertiesPROPERTY
    An enum list of Session properties.
    Public enumerationSolLogLevel
    Log Level
    Public enumerationStats_Rx
    An Enumeration of the various receive statistics. Used as a key in the receive stats dictionary. See GetRxStats in IStatsAccessible.
    Public enumerationStats_Tx
    An enumeration of the various transmit statistics. This is used as a key in the transmit stats dictionary. See GetTxStats() in IStatsAccessible
    Public enumerationTimerMode
    Possible modes of TimerTask.
    Public enumerationTransactedSessionPropertiesPROPERTY
    An enum list of TransactedSessionProperties
    Public enumerationUserCos
    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)