IMessage Interface
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.
Definition
Assembly: SolaceSystems.Solclient.Messaging (in SolaceSystems.Solclient.Messaging.dll) Version: 10.27.0
public interface IMessage : IDisposable- Implements
- IDisposable
Properties
| 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. The message ID is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the message ID. Messages are acknowledged by calling Ack(Int64) If not available 0 is returned. |
| ApplicationMessageId | Gets/sets the ApplicationMessageId. Returns null if not present. |
| ApplicationMessageType | Gets/sets the ApplicationMessageType. 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 | Gets/sets the CorrelationId. 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. Obsolete. |
| DeliveryCount |
Gives the message delivery count.
Throws OperationErrorException when delivery count is not support on the delivery of the message. Note messages from browser flows will have the delivery of the next consumer delivery not the current message delivery count from the endpoint. |
| 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). |
| Priority | 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. |
| 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. |
| ReplicationGroupMessageId | Represents the Replication Group Message ID (RGMID) of the message for guaranteed message set by the router can be null. |
| ReplyTo | Represents the reply-to destination. Returns null if not present. |
| SenderId | Gets/sets the SenderId. 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 | Gets/sets the SequenceNumber. 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. |
| XmlContent | The XML content part of the message. Returns null if not present. |
Methods
| 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. |