UM .NET API 6.17.1

- Main Page
- Related Pages
- Packages
- Classes

- Class List
- Class Hierarchy
- Class Members

Classes | Public Member Functions | List of all members
com.latencybusters.lbm.LBMMessage Class Reference
Inheritance diagram for com.latencybusters.lbm.LBMMessage:

## Classes
struct | lbm_hf_sequence_number_t
struct | lbm_msg_t
struct | lbm_umq_index_info_t

## Public Member Functions
| LBMMessage ()
| LBMMessage constructor.
byte * | dataPointer ()
| Pointer to the beginning of the unmanaged data buffer for this message. For ZOD, use in conjunction with length() to determine how many bytes in the buffer are actually valid. More...
IntPtr | dataPointerSafe ()
| Return an IntPtr to the beginning of the unmanaged data buffer for this message. For ZOD, use in conjunction with length() to determine how many bytes in the buffer are actually valid. More...
byte[] | data ()
| Message data. Calling this method causes the data to be copied to a new byte array. For better performance, use the dataPointer() method to access the data directly. More...
string | dataString ()
| Message string data. Calling this method converts the data to a string and returns that string. More...
uint | length ()
| Message data length. For ZOD, use this in conjunction with dataPointer(). More...
int | type ()
| LBM message type. More...
long | sequenceNumber ()
| LBM message (or message fragment) sequence number. More...
ulong | hfSequenceNumber64 ()
| Get the 64 bit hot failover sequence number. More...
uint | hfSequenceNumber32 ()
| Get the 32 bit hot failover sequence number. More...
string | source ()
| Message source. More...
char[] | sourceAsCharArray ()
| Message source. More...
int | flags ()
| LBM message flags. More...
string | topicName ()
| Topic on which the current message has been delivered. More...
char[] | topicNameAsCharArray ()
| Topic on which the current message has been delivered. More...
LBMMessageChannelInfo | channelInfo ()
| Holds information about any channel information included with the message. More...
long | firstFragmentSequenceNumber ()
| LBM sequence number of the first fragment of the current message. More...
long | fragmentOffset ()
| Byte offset of the current fragment within the associated message. More...
long | totalMessageLength ()
| Total message size. More...
bool | isFragment ()
| Determine if the current message is a single fragment of a larger, multi-fragment message. More...
UMEDeregistrationSuccessInfo | deregistrationSuccessInfo ()
| Get an extended deregistration success info object from the message (only for LBM.MSG_UME_DEREGISTRATION_SUCCESS_EX messages). More...
UMEDeregistrationCompleteInfo | deregistrationCompleteInfo ()
| Get an extended deregistration complete info object from the message (only for LBM.MSG_UME_DEREGISTRATION_COMPLETE_EX messages). More...
UMERegistrationSuccessInfo | registrationSuccessInfo ()
| Get an extended registration success info object from the message (only for LBM.MSG_UME_REGISTRATION_SUCCESS_EX messages). More...
UMERegistrationCompleteInfo | registrationCompleteInfo ()
| Get an extended registration complete info object from the message (only for LBM.MSG_UME_REGISTRATION_COMPLETE_EX messages). More...
UMQRegistrationCompleteInfo | queueRegistrationCompleteInfo ()
| Get an extended queue registration complete info object from the message (only for LBM.MSG_UMQ_REGISTRATION_COMPLETE_EX messages). More...
UMQDeregistrationCompleteInfo | queueDeregistrationCompleteInfo ()
| Get an extended queue deregistration complete info object from the message (only for LBM.MSG_UMQ_DEREGISTRATION_COMPLETE_EX messages). More...
UMQMessageId | queueMessageId ()
| The message ID assigned by the queue (UMQ only) More...
UMQIndexInfo | queueIndexInfo ()
| Retrieve index information from the message. More...
UMQIndexAssignedInfo | queueIndexAssignedInfo ()
| Get a queue index assigned info object from the message only for LBM.MSG_UMQ_INDEX_ASSIGNED_EX messages). More...
UMQIndexReleasedInfo | queueIndexReleasedInfo ()
| Get a queue index released info object from the message only for LBM.MSG_UMQ_INDEX_RELEASED_EX messages). More...
UMQIndexAssignmentEligibilityStartCompleteInfo | queueIndexAssignmentEligibilityStartCompleteInfo ()
| Get a queue index assignment eligibility start complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX messages). More...
UMQIndexAssignmentEligibilityStopCompleteInfo | queueIndexAssignmentEligibilityStopCompleteInfo ()
| Get a queue index assignment eligibility stop complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX messages). More...
UInt32 | timestampSeconds ()
| Seconds portion of the timestamp indicating when the message was received. More...
UInt32 | timestampMicroseconds ()
| Microsecondseconds portion of the timestamp indicating when the message was received. More...
UInt64 | hrTimestampSeconds ()
| Seconds portion of the high resolution timestamp indicating when the message was received. Note: Supported on Linux only. More...
UInt64 | hrTimestampNanoseconds ()
| Nanosecond portion of the high resolution timestamp indicating when the message was received. Note: Supported on Linux only. More...
LBMMessageProperties | properties ()
| Retrieve the properties associated with this message. More...
void | respond (byte[] data, int dataLength, int flags)
| Send a response for this request message. More...
void | sendExplicitAck ()
| Send a consumption acknowledgement to the persistent Store. More...
bool | canSendExplicitAck ()
| Determine whether an explicit ACK can be used on this message (UME).
void | reassign (int flags)
| Do not acknowledge the given message and instead request that the message be reassigned. More...
long | sourceRegistrationId ()
| The registration ID for the source (UME only). More...
long | receiverRegistrationId ()
| The registration ID for the receiver (UME only). More...
bool | isFromGateway ()
| Whether or not the message arrived via a gateway. More...
long | originalSequenceNumber ()
| Original sequence number (if the message arrived via a gateway). More...
string | originalSource ()
| Original message source (if the message arrived via a gateway). More...
char[] | originalSourceAsCharArray ()
| Original message source (if the message arrived via a gateway) as character array. More...
object | sourceClientObject ()
| Get the source client object for this message's source, as set by an LBMSourceCreationCallback callback delegate. More...
uint | osqn ()
| Get the original message sequence number set by the UM library. More...
UMEMessageAck | extractUMEAck ()
| Retrieves the ack structure from a UME message. More...
void | Dispose ()
| Dispose of this message immediately.
void | dispose ()
| Dispose of memory associated with this message. More...
LBMMessage | promote ()
| Inform UM that the application is going to retain ownership of a UM message object after the receiver callback returns. More...

## Detailed Description

Encapsulates all LBM messages.

Messages are delivered via the receiver callback. It is possible to retain a message for further processing after the receiver callback returns by calling promote() and saving the message. The application must call dispose() for each and every message when processing is completed. See .NET Message Reception.

Access message data via dataBuffer() and dataLength() to preserve "Zero Object Delivery" (ZOD). See Zero Object Delivery.

For older, object-based delivery (non-ZOD), you may access message data via data(), which creates a byte array object that contains the message data. This method has lower performance.

Exceptions

  com.latencybusters.lbm.LBMException | Invalid argument or unexpected operational behavior has been encountered by unmanaged LBM C layer function.

## Member Function Documentation

LBMMessageChannelInfo com.latencybusters.lbm.LBMMessage.channelInfo | ( |  | ) |

Holds information about any channel information included with the message.

Returns
  Channel info object or null if no channel information is present.

References com.latencybusters.lbm.LBM.MSG_FLAG_NUMBERED_CHANNEL.

byte [] com.latencybusters.lbm.LBMMessage.data | ( |  | ) |

Message data. Calling this method causes the data to be copied to a new byte array. For better performance, use the dataPointer() method to access the data directly.

Returns
  byte array containing message data

byte* com.latencybusters.lbm.LBMMessage.dataPointer | ( |  | ) |

Pointer to the beginning of the unmanaged data buffer for this message. For ZOD, use in conjunction with length() to determine how many bytes in the buffer are actually valid.

Returns
  Pointer to the beginning of the unmanaged data buffer for this message.

IntPtr com.latencybusters.lbm.LBMMessage.dataPointerSafe | ( |  | ) |

Return an IntPtr to the beginning of the unmanaged data buffer for this message. For ZOD, use in conjunction with length() to determine how many bytes in the buffer are actually valid.

Returns
  Pointer to the beginning of the unmanaged data buffer for this message.

string com.latencybusters.lbm.LBMMessage.dataString | ( |  | ) |

Message string data. Calling this method converts the data to a string and returns that string.

Returns
  Message data converted to a string

UMEDeregistrationCompleteInfo com.latencybusters.lbm.LBMMessage.deregistrationCompleteInfo | ( |  | ) |

Get an extended deregistration complete info object from the message (only for LBM.MSG_UME_DEREGISTRATION_COMPLETE_EX messages).

Returns
  UMEDeregistrationCompleteInfo object holding extended deregistration complete info.

UMEDeregistrationSuccessInfo com.latencybusters.lbm.LBMMessage.deregistrationSuccessInfo | ( |  | ) |

Get an extended deregistration success info object from the message (only for LBM.MSG_UME_DEREGISTRATION_SUCCESS_EX messages).

Returns
  UMEDeregistrationSuccessInfo object holding extended deregistration success info.

void com.latencybusters.lbm.LBMMessage.dispose | ( |  | ) |

Dispose of memory associated with this message.

Every received message must be disposed after processing is complete. See .NET Message Reception.

If this message is delivered from a persistent receiver, deleting the message might signal consumption of the message, depending on the use case. See Persistence Message Consumption for a full explanation of consumption acknowledgements.

See also
  Dispose

UMEMessageAck com.latencybusters.lbm.LBMMessage.extractUMEAck | ( |  | ) |

Retrieves the ack structure from a UME message.

Exceptions

  com.latencybusters.lbm.LBMException | Message already acked, disposed, or not a UME message

Returns
  UMEMessageAck object that can be used to send explicit acks

References com.latencybusters.lbm.LBM.EINVAL, com.latencybusters.lbm.LBM.errorMessage(), com.latencybusters.lbm.LBM.errorNumber(), com.latencybusters.lbm.LBM.UME_MAX_STORE_STRLEN, com.latencybusters.lbm.LBM.UMQ_MAX_INDEX_LEN, and com.latencybusters.lbm.LBM.UMQ_MAX_QUEUE_STRLEN.

long com.latencybusters.lbm.LBMMessage.firstFragmentSequenceNumber | ( |  | ) |

LBM sequence number of the first fragment of the current message.

Returns
  Sequence number of the first message fragment

int com.latencybusters.lbm.LBMMessage.flags | ( |  | ) |

LBM message flags.

See also
  LBM

Returns
  LBM message flags

long com.latencybusters.lbm.LBMMessage.fragmentOffset | ( |  | ) |

Byte offset of the current fragment within the associated message.

Returns
  Byte offset of the current fragment

uint com.latencybusters.lbm.LBMMessage.hfSequenceNumber32 | ( |  | ) |

Get the 32 bit hot failover sequence number.

Returns
  32 bit hot failover sequence number

ulong com.latencybusters.lbm.LBMMessage.hfSequenceNumber64 | ( |  | ) |

Get the 64 bit hot failover sequence number.

Returns
  64 bit hot failover sequence number

UInt64 com.latencybusters.lbm.LBMMessage.hrTimestampNanoseconds | ( |  | ) |

Nanosecond portion of the high resolution timestamp indicating when the message was received. Note: Supported on Linux only.

Returns
  Linux only: Number of fractional seconds since Midnight, January 1st 1970 UTC. All other platforms: returns 0

UInt64 com.latencybusters.lbm.LBMMessage.hrTimestampSeconds | ( |  | ) |

Seconds portion of the high resolution timestamp indicating when the message was received. Note: Supported on Linux only.

Returns
  Linux only: Number of whole seconds since Midnight, January 1st 1970 UTC. All other platforms: returns 0

bool com.latencybusters.lbm.LBMMessage.isFragment | ( |  | ) |

Determine if the current message is a single fragment of a larger, multi-fragment message.

Note that this method will not return true unless:

- ordered_delivery (receiver) is set to "0" (zero), and
- the application message required UM fragmentation.

Returns
  true if the current object is a message fragment; otherwise, false.

bool com.latencybusters.lbm.LBMMessage.isFromGateway | ( |  | ) |

Whether or not the message arrived via a gateway.

Returns
  boolean indicating if it arrived via a gateway.

uint com.latencybusters.lbm.LBMMessage.length | ( |  | ) |

Message data length. For ZOD, use this in conjunction with dataPointer().

Returns
  LBM message length

long com.latencybusters.lbm.LBMMessage.originalSequenceNumber | ( |  | ) |

Original sequence number (if the message arrived via a gateway).

Returns
  Original sequence number.

string com.latencybusters.lbm.LBMMessage.originalSource | ( |  | ) |

Original message source (if the message arrived via a gateway).

Returns
  Original message source.

char [] com.latencybusters.lbm.LBMMessage.originalSourceAsCharArray | ( |  | ) |

Original message source (if the message arrived via a gateway) as character array.

Returns
  Original message source as character array.

uint com.latencybusters.lbm.LBMMessage.osqn | ( |  | ) |

Get the original message sequence number set by the UM library.

Returns
  Message original sequence number

LBMMessage com.latencybusters.lbm.LBMMessage.promote | ( |  | ) |

Inform UM that the application is going to retain ownership of a UM message object after the receiver callback returns.

This function should be called from inside a receiver callback function to prevent UM from automatically deleting the message when the callback function returns. This allows the message to be passed to a different part of the application, perhaps a different thread, for processing after the receiver callback returns.

Once promoted, the application has the responsibility to dispose of the message when it is finished with it by calling dispose(). See .NET Message Reception.

Note that this creates a new object, so delivery is no longer "zero object".

Note
  the message must be promoted before being made available to the other parts of the application. For example, it would not be legal for a separate thread to start processing the message before the receiver callback called promote.

Warning
  promote() is NOT thread safe; do not call it on the same message from multiple threads at the same time.

Returns
  The promoted message. This will be a new message object, not the message object passed into the receiver callback. was called on.

LBMMessageProperties com.latencybusters.lbm.LBMMessage.properties | ( |  | ) |

Retrieve the properties associated with this message.

Returns
  An LBMMessageProperties object containing all properties associated with this message.

UMQDeregistrationCompleteInfo com.latencybusters.lbm.LBMMessage.queueDeregistrationCompleteInfo | ( |  | ) |

Get an extended queue deregistration complete info object from the message (only for LBM.MSG_UMQ_DEREGISTRATION_COMPLETE_EX messages).

Returns
  UMQDeregistrationCompleteInfo object holding extended queue deregistration complete info.

UMQIndexAssignedInfo com.latencybusters.lbm.LBMMessage.queueIndexAssignedInfo | ( |  | ) |

Get a queue index assigned info object from the message only for LBM.MSG_UMQ_INDEX_ASSIGNED_EX messages).

Returns
  UMQIndexAssignedInfo object holding extended index assignment info.

UMQIndexAssignmentEligibilityStartCompleteInfo com.latencybusters.lbm.LBMMessage.queueIndexAssignmentEligibilityStartCompleteInfo | ( |  | ) |

Get a queue index assignment eligibility start complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX messages).

Returns
  UMQIndexAssignmentEligibilityStartCompleteInfo object holding extended index assignment eligibility start complete info.

UMQIndexAssignmentEligibilityStopCompleteInfo com.latencybusters.lbm.LBMMessage.queueIndexAssignmentEligibilityStopCompleteInfo | ( |  | ) |

Get a queue index assignment eligibility stop complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX messages).

Returns
  UMQIndexAssignmentEligibilityStopCompleteInfo object holding extended index assignment eligibility stop complete info.

UMQIndexInfo com.latencybusters.lbm.LBMMessage.queueIndexInfo | ( |  | ) |

Retrieve index information from the message.

Returns
  UMQIndexInfo object holding queue index information, or null if the message has no queue index information.

References com.latencybusters.lbm.LBM.UMQ_INDEX_FLAG_NUMERIC.

UMQIndexReleasedInfo com.latencybusters.lbm.LBMMessage.queueIndexReleasedInfo | ( |  | ) |

Get a queue index released info object from the message only for LBM.MSG_UMQ_INDEX_RELEASED_EX messages).

Returns
  UMQIndexReleasedInfo object holding extended index release info.

UMQMessageId com.latencybusters.lbm.LBMMessage.queueMessageId | ( |  | ) |

The message ID assigned by the queue (UMQ only)

Returns
  The message ID assigned by the queue

UMQRegistrationCompleteInfo com.latencybusters.lbm.LBMMessage.queueRegistrationCompleteInfo | ( |  | ) |

Get an extended queue registration complete info object from the message (only for LBM.MSG_UMQ_REGISTRATION_COMPLETE_EX messages).

Returns
  UMQRegistrationCompleteInfo object holding extended queue registration complete info.

void com.latencybusters.lbm.LBMMessage.reassign | ( | int | flags | ) |

Do not acknowledge the given message and instead request that the message be reassigned.

Parameters

  flags | Flags indicating various conditions. ORed set of values include: LBM.MSG_UMQ_REASSIGN_FLAG_DISCARD

Exceptions

  com.latencybusters.lbm.LBMException | Invalid argument or unexpected operational behavior has been encountered by unmanaged LBM C layer function.

References com.latencybusters.lbm.LBM.EINVAL, com.latencybusters.lbm.LBM.errorMessage(), and com.latencybusters.lbm.LBM.errorNumber().

long com.latencybusters.lbm.LBMMessage.receiverRegistrationId | ( |  | ) |

The registration ID for the receiver (UME only).

Returns
  The receiver registration ID

UMERegistrationCompleteInfo com.latencybusters.lbm.LBMMessage.registrationCompleteInfo | ( |  | ) |

Get an extended registration complete info object from the message (only for LBM.MSG_UME_REGISTRATION_COMPLETE_EX messages).

Returns
  UMERegistrationCompleteInfo object holding extended registration complete info.

UMERegistrationSuccessInfo com.latencybusters.lbm.LBMMessage.registrationSuccessInfo | ( |  | ) |

Get an extended registration success info object from the message (only for LBM.MSG_UME_REGISTRATION_SUCCESS_EX messages).

Returns
  UMERegistrationSuccessInfo object holding extended registration success info.

void com.latencybusters.lbm.LBMMessage.respond | ( | byte[] | data,
|  | int | dataLength,
|  | int | flags
| ) |  |

Send a response for this request message.

Warning: It is not safe to call this method from a context thread callback.
Warning: You may be required to use GC.KeepAlive on the LBMMessage object after calling respond() in order to prevent premature garbage collection during execution of the respond() function call. Premature garbage collection can occur if there are no references made to the LBMMessage object following the respond() call.
Possible OR'd set of flag value include: LBM.SRC_NONBLOCK and LBM.SRC_BLOCK.

Parameters

  data | Data to send in this response
  dataLength | Number of bytes of data to send in this response
  flags | Flags indicating various conditions

Exceptions

  com.latencybusters.lbm.LBMException | Invalid argument or unexpected operational behavior has been encountered by unmanaged LBM C layer function.

References com.latencybusters.lbm.LBM.EINVAL, com.latencybusters.lbm.LBM.errorMessage(), com.latencybusters.lbm.LBM.errorNumber(), and com.latencybusters.lbm.LBM.MSG_REQUEST.

void com.latencybusters.lbm.LBMMessage.sendExplicitAck | ( |  | ) |

Send a consumption acknowledgement to the persistent Store.

This function is used in the Explicit Acknowledgments use case to signal consumption of the supplied message, and all unacknowledged messages sent before it. ume_explicit_ack_only (receiver) must be set to 1.

Warning
  If explicit ACKs are used, the application must ensure that messages are ACKed in the order received. See ACK Ordering.

See Persistence Message Consumption for a full explanation of consumption acknowledgements.

Exceptions

  com.latencybusters.lbm.LBMException | Invalid argument or unexpected operational behavior has been encountered by unmanaged LBM C layer function.

References com.latencybusters.lbm.LBM.EINVAL, com.latencybusters.lbm.LBM.errorMessage(), and com.latencybusters.lbm.LBM.errorNumber().

long com.latencybusters.lbm.LBMMessage.sequenceNumber | ( |  | ) |

LBM message (or message fragment) sequence number.

The sequence number of an LBM message is 32 bits. This field is a C#-style long int (64 bits). Therefore, LBM only recognizes the lower 32 bits of this field. When using hot-failover, this will be the hot failover sequence number when using 32 bit and be zero when using 64 bit. To get the original sequence number when using hot-failover, use the osqn() method.

See also
  osqn()

Returns
  LBM message (or message fragment) sequence number

string com.latencybusters.lbm.LBMMessage.source | ( |  | ) |

Message source.

Returns
  Message source string

char [] com.latencybusters.lbm.LBMMessage.sourceAsCharArray | ( |  | ) |

Message source.

Returns
  Message source char []

object com.latencybusters.lbm.LBMMessage.sourceClientObject | ( |  | ) |

Get the source client object for this message's source, as set by an LBMSourceCreationCallback callback delegate.

Returns
  Source client object.

long com.latencybusters.lbm.LBMMessage.sourceRegistrationId | ( |  | ) |

The registration ID for the source (UME only).

Returns
  The source registration ID

UInt32 com.latencybusters.lbm.LBMMessage.timestampMicroseconds | ( |  | ) |

Microsecondseconds portion of the timestamp indicating when the message was received.

Returns
  Number of fractional seconds since Midnight, January 1st 1970 UTC, represented as an integer number of microseconds.

UInt32 com.latencybusters.lbm.LBMMessage.timestampSeconds | ( |  | ) |

Seconds portion of the timestamp indicating when the message was received.

Returns
  Number of whole seconds since Midnight, January 1st 1970 UTC.

string com.latencybusters.lbm.LBMMessage.topicName | ( |  | ) |

Topic on which the current message has been delivered.

Returns
  Topic name string

char [] com.latencybusters.lbm.LBMMessage.topicNameAsCharArray | ( |  | ) |

Topic on which the current message has been delivered.

Returns
  Topic name char []

long com.latencybusters.lbm.LBMMessage.totalMessageLength | ( |  | ) |

Total message size.

This value may be larger than the length of the data byte array, if the current object represents a message fragment.

Returns
  Total size (in bytes) of the current message

int com.latencybusters.lbm.LBMMessage.type | ( |  | ) |

LBM message type.

See also
  LBM

Returns
  LBM message type

The documentation for this class was generated from the following file:

- LBMMessage.cs