Add sequence numbers to message info structure

rmw/include/rmw/types.h

@@ -515,11 +515,66 @@ typedef struct RMW_PUBLIC_TYPE rmw_gid_s
   uint8_t data[RMW_GID_STORAGE_SIZE];
 } rmw_gid_t;
 
+#define RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED INT64_MAX
+
 /// Information describing an rmw message
 typedef struct RMW_PUBLIC_TYPE rmw_message_info_s
 {
+  /// Time when the message was published by the publisher.
+  /**
+   * The exact point at which the timestamp is taken is not specified, but
+   * it should be taken consistently at the same point in the
+   * publishing process each time.
+   */
   rmw_time_point_value_t source_timestamp;
+  /// Time when the message was received by the subscription.
+  /**
+   * The exact point at which the timestamp is taken is not specified, but
+   * it should be taken consistently at the same point in the
+   * process of receiving a message each time.
+   */
   rmw_time_point_value_t received_timestamp;
+  /// Sequence number of the received message set by the publisher.
+  /**
+   * This sequence number is set by the publisher and therefore uniquely identifies
+   * a message when combined with the publisher GID.
+   * For long running applications, the sequence number might wrap around at some point.
+   *
+   * If the rmw implementation doesn't support sequence numbers, its value will be
+   * RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED.
+   *
+   * Requirements:
+   *
+   * If `psn1` and `psn2` are the publication sequence numbers obtained by
+   * calls to `rmw_take*()`, where `psn1` was obtained in a call that happened before `psn2` and both
+   * sequence numbers are from the same publisher (i.e. also same publisher gid), then:
+   *
+   * - psn2 > psn1 (except in the case of a wrap around)
+   * - `psn2 - psn1 - 1` is the number of messages the publisher sent in the middle of both
+   *   received messages.
+   *   Those might have already been taken by other `rmw_take*()` calls that happened in between or lost.
+   *   `psn2 - psn1 - 1 = 0` if and only if the messages were sent by the publisher consecutively.
+   */
+  int64_t publication_sequence_number;
+  /// Sequence number of the received message set by the subscription.
+  /**
+   * This sequence number is set by the subscription regardless of which
+   * publisher sent the message.
+   * For long running applications, the sequence number might wrap around at some point.
+   *
+   * If the rmw implementation doesn't support sequence numbers, its value will be
+   * RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED.
+   *
+   * Requirements:
+   *
+   * If `rsn1` and `rsn2` are the reception sequence numbers obtained by
+   * calls to `rmw_take*()`, where `rsn1` was obtained in a call that happened before `rsn2`, then:
+   *
+   * - rsn2 > rsn1 (except in the case of a wrap around)
+   * - `rsn2 = rsn1 + 1` if and only if both `rmw_take*()` calls happened consecutively.
+   */
+  int64_t reception_sequence_number;
+  /// Global unique identifier of the publisher that sent the message.
   rmw_gid_t publisher_gid;
 
   /// Whether this message is from intra_process communication or not

rmw/src/types.c

@@ -19,6 +19,9 @@ RMW_WARN_UNUSED
 rmw_message_info_t
 rmw_get_zero_initialized_message_info(void)
 {
-  rmw_message_info_t zero_initialized_message_info = {0, 0, {NULL, {0}}, false};
+  rmw_message_info_t zero_initialized_message_info = {
+    0, 0, RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED,
+    RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED, {NULL, {0}}, false
+  };
   return zero_initialized_message_info;
 }