IMessage Interface

Solclient

IMessage Interface

version: 7.2.1.27

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.

Namespace: SolaceSystems.Solclient.Messaging
Assembly: SolaceSystems.Solclient.Messaging (in SolaceSystems.Solclient.Messaging.dll) Version: 7.2.1.27 (7.2.1.27)

Syntax

C++

Copy

public interface IMessage : IDisposable

Public Interface IMessage
	Inherits IDisposable

public interface class IMessage : IDisposable

The IMessage type exposes the following members.

Methods

	Name	Description
	CreateUserPropertyMap	Creates a user property map (of type IMapContainer) in the meta header of a message. Any existing user property map is overwritten. After adding user properties to this map, it must be closed; if not, it is automatically closed after the associated message is disposed IDisposable. Whether it is explicitly closed by the client application, or implicitly by the API, any attempt to use this map results in an OperationErrorException with ParamNullReference
	Dispose	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
	Dump	Returns a string representation of the contents of a message in human-readable form.
	Dump(MessageDump)	Returns a string representation of the contents of a message in human-readable form. Dump(MessageDump.Full) is equivalent to calling Dump().
	GetBinaryAttachment	Gets the binary attachment part of the message. If not present, null is returned to the user.
	GetDestinationTopicSuffix	A getter for the suffix of the topic string. If the received message contains a topic destination and the topic begins with the session's topic prefix, this method returns the string following the '/' delimiter that terminates the topic prefix. Returns null if not present.
	GetUserData	Gets the user data part of the message. Returns null if not present.
	GetXmlContent	Gets the XML content part of the message. Returns null if not present.
	Reset	Release all memory associated with this message, returning it to its original state, as if it has just been created.
	SetAsReplyMessage	Sets the reply attribute of the message.
	SetBinaryAttachment	Sets the binary attachment part of the message.
	SetReplyToSuffix	Appends an application-specific suffix to the default topic destination for the session. When the session is established, a unique topic destination is created for the session. This topic is generated by the appliance, and the API subscribes to a wildcard extended topic that is derived by appending './>' to the unique topic destination.
	SetUserData	Sets the user data part of the message.
	SetXmlContent	Sets the XML content part of the message.

Top

Properties

	Name	Description
	AckImmediately	When the ACKImmediately property is set to true on an outgoing Guaranteed Delivery message, it indicates that the appliance should ACK this message immediately upon receipt. This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not rely on this property being present. Setting this property on an outgoing direct message or on a received message has no effect. Default: false
	ADMessageId	Applies to received messages only with DeliveryMode MessageDeliveryMode.PERSISTENT or MessageDeliveryMode.NON_PERSISTENT. Represents the message Id of a Guaranteed message and can be used when acknowledging such a message. If not available 0 is returned.
	ApplicationMessageId	Gets/sets the application messageId. Returns null if not present.
	ApplicationMessageType	Gets/sets the application message type. This value is used by applications only and is passed through the API untouched. If not present, null is returned.
	BinaryAttachment	The binary attachment part of the message. If not present, null is returned to the user.
	CacheRequestId	Returns the request ID set in the cache request. Always null if CacheStatus is MessageCacheStatus.Live If not present -1 is returned
	CacheStatus	Returns the MessageCacheStatus.
	ConsumerIdList	Applies to received messages only. Returns the Conusmer Id list, null if the received message has none. Consumer IDs are only used with XML content subscriptions, not with topic subscriptions. When XML subscriptions are applied with consumer IDs, received messages contain a list of the consumer IDs of all XML subscriptions that were a match to that received message. This allows the application to know which of its XML subscriptions were a match to the received message. If not present, null is returned.
	CorrelationId	The correlation id is used for correlating a request to a reply. If not present, null is returned.
	CorrelationKey	Applies to Guaranteed messages (where DeliveryMode is Persistent or Non-persistent). When set on a message, the correlation key is returned in a message acknowledgment event. If not present, null is returned. CorrelationKey is local to the current application, it is not transmitted on the wire.
	DeliverToOne	A setter/getter for the Deliver-To-One (DTO) property on a message with a Delivery mode of Direct. When a message has the DTO property set, it can to be delivered only to one client. For a Guaranteed Delivery message (see DeliveryMode), this behavior only applies to the "demoted" direct copy of this message. This property is only supported by appliances running SolOS-TR.
	DeliveryMode	A setter/getter for MessageDeliveryMode.
	Destination	The Destination to send to or receive on. For SolOS-Topic Routing (TR) it must be ITopic or IQueue (null is not a valid value when sending the message).
	DiscardIndication	Returns true if one or more messages have been discarded prior to the current message, otherwise it returns false. Indicates congestion discards only and is not affected by message eliding.
	DMQEligible	Expired messages with this property set to true are moved to a Dead Message Queue when one is provisioned on the appliance. Default: false
	ElidingEligible	Setting this property to true indicates that this message should be eligible for eliding.
	Expiration	The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is to expire. The expiration time is carried in the message when set to a non-zero value. Expiration time is not included when this value is set to zero. Setting this property has no effect if the TimeToLive is set in the same message. The message expiration time is carried to clients that receive the message unmodified and does not affect the life cycle of the message. Set TimeToLive to a positive value to enforce message expiry in the network. When TimeToLive has a positive value, the Expiration is never carried in the message (defaulting to zero). However, it may be calculated and retrieved if the session property CalculateMessageExpiration is set to true. if message Expiration time is not set in the message and the session property CalculateMessageExpiration is set to true, the Expiration time is calculated based on the message's TimeToLive. When enabled, the Expiration time retrieved will be the UTC time when the message is sent plus the message's TimeToLive. The Expiration time for received messages will be the UTC time when the message was received plus the TimeToLive of the message at the time it was received.
	HttpContentEncoding	The HTTP Content Encoding. If not present, null is returned.
	HttpContentType	The HTTP Content Type. If not present, null is returned.
	IsReplyMessage	Returns true if it is a reply message (reply to a request).
	ReceiverTimestamp	Gets the receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC). Returns -1 if not present.
	Redelivered	Applies only when DeliveryMode is MessageDeliveryMode.PERSISTENT or MessageDeliveryMode.NON_PERSISTENT. Indicates if the message has been delivered by the appliance to the API before.
	ReplyTo	Represents the reply-to destination. Returns null if not present.
	SenderId	Represents the sender id. Returns null if not present.
	SenderTimestamp	Gets the sender timestamp (in milliseconds, from midnight, January 1, 1970 UTC). Returns -1 if not present or set.
	SequenceNumber	Represents the message sequence number. The set operation overrides the sequence number automatically generated by the session (if set). Returns null if not present.
	TimeToLive	The number of milliseconds before the message is discarded or moved to a Dead Message Queue. A value of 0 means the message never expires. The default value is zero. Note that this property is only valid for Guaranteed Delivery messages (Persistent and Non-Persistent). It has no effect when used in conjunction with other message types unless the message is promoted by the appliance to a Guaranteed Delivery message.
	TopicSequenceNumber	Represents the Topic Sequence Number assigned by the appliance or the peer. Returns null if none is present
	UserCos	A setter/getter for User Class of service. 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)
	UserData	The user data part of the message (maximum: 36 bytes). Returns null if not present.
	UserPropertyMap	Returns the user property map from the message's meta header. If no user property map is present in the message, this property is null. To create a new user property map use CreateUserPropertyMap instead. After adding properties to this map, it must be closed; if not, it is automatically closed after the associated message is sent, or disposed IDisposable. Whether it is explicitly closed by the client application, or implicitly by the API, any attempt to use this map results in an OperationErrorException with ParamNullReference error subcode. As a consequence to the above note, when caching the reference to this map (to avoid creating a new temporary object with each access), client applications should not use this reference after the associated message has been sent or disposed. At that point the cached user property map reference is invalid, and a new user map reference is required by calling IMessage.UserPropertyMap to access the user property map again. Remarks Do not set this value to the result of CreateUserPropertyMap. Doing so will cause the underlying structure to be disposed. Instead, access the map this way: Copy IMessage msg = ContextFactory.Instance.CreateMessage(); msg.CreateUserPropertyMap(); msg.UserPropertyMap.AddString("message", "5");
	XmlContent	The XML content part of the message. Returns null if not present.

Top

Reference

SolaceSystems.Solclient.Messaging Namespace

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use and copy the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

UNLESS STATED ELSEWHERE BETWEEN YOU AND SOLACE SYSTEMS, INC., THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Send comments on this topic to [email protected]

previous page start next page