Click or drag to resize

IMessage Interface

version: 10.9.0
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: 10.9.0
Syntax
public interface IMessage : IDisposable

The IMessage type exposes the following members.

Properties
  NameDescription
Public propertyAckImmediately
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
Public propertyADMessageId
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.
Public propertyApplicationMessageId
Gets/sets the application messageId. Returns null if not present.
Public propertyApplicationMessageType
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.
Public propertyBinaryAttachment
The binary attachment part of the message. If not present, null is returned to the user.
Public propertyCacheRequestId
Returns the request ID set in the cache request. Always null if CacheStatus is MessageCacheStatus.Live If not present -1 is returned
Public propertyCacheStatus
Returns the MessageCacheStatus.
Public propertyConsumerIdList
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.
Public propertyCorrelationId
The correlation id is used for correlating a request to a reply. If not present, null is returned.
Public propertyCorrelationKey
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.
Public propertyDeliverToOne Obsolete.
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.

Public propertyDeliveryMode
A setter/getter for MessageDeliveryMode.
Public propertyDestination
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).
Public propertyDiscardIndication
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.
Public propertyDMQEligible
Expired messages with this property set to true are moved to a Dead Message Queue when one is provisioned on the appliance. Default: false
Public propertyElidingEligible
Setting this property to true indicates that this message should be eligible for eliding.
Public propertyExpiration
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.

Public propertyHttpContentEncoding
The HTTP Content Encoding. If not present, null is returned.
Public propertyHttpContentType
The HTTP Content Type. If not present, null is returned.
Public propertyIsReplyMessage
Returns true if it is a reply message (reply to a request).
Public propertyPriority
Represents the message priority. The valid value range is 0-255 with 0 as the lowest priority and 255 as the highest. Returns null if not present.
Public propertyReceiverTimestamp
Gets the receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC). Returns -1 if not present.
Public propertyRedelivered
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.
Public propertyReplyTo
Represents the reply-to destination. Returns null if not present.
Public propertySenderId
Represents the sender id. Returns null if not present.
Public propertySenderTimestamp
Gets the sender timestamp (in milliseconds, from midnight, January 1, 1970 UTC). Returns -1 if not present or set.
Public propertySequenceNumber
Represents the message sequence number. The set operation overrides the sequence number automatically generated by the session (if set). Returns null if not present.
Public propertyTimeToLive
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.

Public propertyTopicSequenceNumber
Represents the Topic Sequence Number assigned by the appliance or the peer. Returns null if none is present
Public propertyUserCos
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)

Public propertyUserData
The user data part of the message (maximum: 36 bytes). Returns null if not present.
Public propertyUserPropertyMap
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:
IMessage msg = ContextFactory.Instance.CreateMessage();
msg.CreateUserPropertyMap();
msg.UserPropertyMap.AddString("message", "5");
Public propertyXmlContent
The XML content part of the message. Returns null if not present.
Top
Methods
  NameDescription
Public methodCreateUserPropertyMap
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

Public methodDispose
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
(Inherited from IDisposable.)
Public methodDump
Returns a string representation of the contents of a message in human-readable form.
Public methodDump(MessageDump)
Returns a string representation of the contents of a message in human-readable form. Dump(MessageDump.Full) is equivalent to calling Dump().
Public methodGetBinaryAttachment
Gets the binary attachment part of the message. If not present, null is returned to the user.
Public methodGetDestinationTopicSuffix
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.
Public methodGetUserData
Gets the user data part of the message. Returns null if not present.
Public methodGetXmlContent
Gets the XML content part of the message. Returns null if not present.
Public methodReset
Release all memory associated with this message, returning it to its original state, as if it has just been created.
Public methodSetAsReplyMessage
Sets the reply attribute of the message.
Public methodSetBinaryAttachment
Sets the binary attachment part of the message.
Public methodSetReplyToSuffix
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.
Public methodSetUserData
Sets the user data part of the message.
Public methodSetXmlContent
Sets the XML content part of the message.
Top
See Also