+/*!
+@defgroup api-msg-iter-cls Message iterator class
+@ingroup api-comp-cls-dev
+
+@brief
+ \bt_c_msg_iter class.
+
+A <strong><em>message iterator class</em></strong> is the class of a
+\bt_msg_iter.
+
+@image html msg-iter-cls.png
+
+\bt_cp_src_comp_cls and \bt_p_flt_comp_cls contain a message iterator
+class. For such a component class, its message iterator class is the
+class of any message iterator created for any \bt_oport of the
+component class's instances (\bt_p_comp).
+
+Therefore, the only thing you can do with a message iterator class is to
+pass it to bt_component_class_source_create() or
+bt_component_class_filter_create() to set it as the created component
+class's message iterator class.
+
+A message iterator class has <em>methods</em>. This module essentially
+offers:
+
+- Message iterator class method type definitions.
+
+- A message iterator class creation function, to which you must pass
+ the mandatory \link api-msg-iter-cls-meth-next "next" method\endlink.
+
+- Functions to set optional message iterator class methods.
+
+A message iterator class method is a user function. All message iterator
+class methods operate on an instance (a \bt_msg_iter). The type of the
+method's first parameter is #bt_self_message_iterator. This is similar
+to an instance method in Python (where the instance object name is
+generally <code>self</code>) or a member function in C++ (where the
+instance pointer is named <code>this</code>), for example.
+
+See \ref api-msg-iter-cls-methods "Methods" to learn more about the
+different types of message iterator class methods.
+
+A message iterator class is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_message_iterator_class_get_ref() and put an existing reference with
+bt_message_iterator_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" message iterator
+classes on success. The documentation of those functions indicate this
+postcondition.
+
+The type of a message iterator class is #bt_message_iterator_class.
+
+Create a message iterator class with bt_message_iterator_class_create().
+When you call this function, you must pass the message iterator
+class's mandatory
+\link api-msg-iter-cls-meth-next "next" method\endlink.
+
+<h1>\anchor api-msg-iter-cls-methods Methods</h1>
+
+To learn when exactly the methods below are called, see
+\ref api-graph-lc "Trace processing graph life cycle" and
+\ref api-msg-iter.
+
+The available message iterator class methods to implement are:
+
+<table>
+ <tr>
+ <th>Name
+ <th>Requirement
+ <th>C type
+ <tr>
+ <td>Can seek beginning?
+ <td>Optional
+ <td>#bt_message_iterator_class_can_seek_beginning_method
+ <tr>
+ <td>Can seek ns from origin?
+ <td>Optional
+ <td>#bt_message_iterator_class_can_seek_ns_from_origin_method
+ <tr>
+ <td>Finalize
+ <td>Optional
+ <td>#bt_message_iterator_class_finalize_method
+ <tr>
+ <td>Initialize
+ <td>Optional
+ <td>#bt_message_iterator_class_initialize_method
+ <tr>
+ <td>Next
+ <td>Mandatory
+ <td>#bt_message_iterator_class_next_method
+ <tr>
+ <td>Seek beginning
+ <td>Optional
+ <td>#bt_message_iterator_class_seek_beginning_method
+ <tr>
+ <td>Seek ns from origin
+ <td>Optional
+ <td>#bt_message_iterator_class_seek_ns_from_origin_method
+</table>
+
+<dl>
+ <dt>
+ \anchor api-msg-iter-cls-meth-can-seek-beg
+ Can seek beginning?
+ </dt>
+ <dd>
+ Called to check whether or not your \bt_msg_iter can currently
+ seek its beginning (the very first message of its
+ \ref api-msg-seq "sequence").
+
+ There are some use cases in which a message iterator cannot always
+ seek its beginning, depending on its state.
+
+ If you don't implement this method, then, if you implement the
+ \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method, the
+ library assumes that your message iterator can always seek its
+ beginning.
+
+ The message iterator of a \bt_flt_comp will typically consider
+ the beginning seeking capability of its own upstream message
+ iterator(s) (with bt_message_iterator_can_seek_beginning()) in this
+ method's implementation.
+
+ If you need to block the thread to compute whether or not your
+ message iterator can seek its beginning, you can instead report to
+ try again later to the caller by returning
+ #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
+
+ Set this optional method with the \bt_p{can_seek_method} parameter
+ of bt_message_iterator_class_set_seek_beginning_methods().
+ </dd>
+
+ <dt>
+ \anchor api-msg-iter-cls-meth-can-seek-ns
+ Can seek ns from origin?
+ </dt>
+ <dd>
+ Called to check whether or not your \bt_msg_iter can currently
+ seek a message occuring at or after a specific time given in
+ nanoseconds from its
+ \ref api-tir-clock-cls-origin "clock class origin".
+
+ There are some use cases in which a message iterator cannot always
+ seek some specific time, depending on its state.
+
+ Within this method, your receive the specific time to seek as the
+ \bt_p{ns_from_origin} parameter. You don't receive any
+ \bt_clock_cls: the method operates at the nanosecond from some
+ origin level and it is left to the implementation to decide whether
+ or not the message iterator can seek this point in time.
+
+ If you don't implement this method, then, if you implement the
+ \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method, the
+ library assumes that your message iterator can always seek any
+ message occuring at or after any time.
+
+ The message iterator of a \bt_flt_comp will typically consider
+ the time seeking capability of its own upstream message
+ iterator(s) (with bt_message_iterator_can_seek_ns_from_origin()) in
+ this method's implementation.
+
+ If you need to block the thread to compute whether or not your
+ message iterator can seek a message occuring at or after a given
+ time, you can instead report to try again later to the caller by
+ returning
+ #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
+
+ Set this optional method with the \bt_p{can_seek_method} parameter
+ of bt_message_iterator_class_set_seek_ns_from_origin_methods().
+ </dd>
+
+ <dt>
+ \anchor api-msg-iter-cls-meth-fini
+ Finalize
+ </dt>
+ <dd>
+ Called to finalize your \bt_msg_iter, that is, to let you
+ destroy/free/finalize any user data you have (retrieved with
+ bt_self_message_iterator_get_data()).
+
+ The \bt_name library does not specify exactly when this method is
+ called, but guarantees that it's called before the message iterator
+ is destroyed.
+
+ The library guarantees that all message iterators are destroyed
+ before their component is destroyed.
+
+ This method is \em not called if the message iterator's
+ \ref api-msg-iter-cls-meth-init "initialization method"
+ previously returned an error status code.
+
+ Set this optional method with
+ bt_message_iterator_class_set_finalize_method().
+ </dd>
+
+ <dt>
+ \anchor api-msg-iter-cls-meth-init
+ Initialize
+ </dt>
+ <dd>
+ Called within bt_message_iterator_create_from_message_iterator()
+ or bt_message_iterator_create_from_sink_component() to initialize
+ your \bt_msg_iter.
+
+ Within this method, you can access your \bt_comp's user data
+ by first borrowing it with
+ bt_self_message_iterator_borrow_component() and then using
+ bt_self_component_get_data().
+
+ For the message iterator of a \bt_flt_comp, this method is
+ typically where you create an upstream \bt_msg_iter
+ with bt_message_iterator_create_from_message_iterator().
+
+ You can create user data and set it as the \bt_self_msg_iter's user
+ data with bt_self_message_iterator_set_data().
+
+ If you return #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
+ from this method, then your message iterator's
+ \ref api-msg-iter-cls-meth-fini "finalization method" will be
+ called, if it exists, when your message iterator is finalized.
+
+ This method receives a message iterator configuration object
+ (#bt_self_message_iterator_configuration type). As of
+ \bt_name_version_min_maj, you can use
+ bt_self_message_iterator_configuration_set_can_seek_forward()
+ during, and only during, this method's execution to set whether or
+ not your message iterator can <em>seek forward</em>.
+
+ For a message iterator to be able to seek forward, all the \bt_p_msg
+ of its message sequence must have some \bt_cs.
+ bt_message_iterator_seek_ns_from_origin() uses this configuration
+ option and the beginning seeking capability of a message iterator
+ (bt_message_iterator_can_seek_beginning())
+ to make it seek a message occuring at or after a specific time even
+ when the message iterator does not implement the
+ \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
+
+ Set this optional method with
+ bt_message_iterator_class_set_initialize_method().
+ </dd>
+
+ <dt>
+ \anchor api-msg-iter-cls-meth-next
+ "Next" (get next messages)
+ </dt>
+ <dd>
+ Called within bt_message_iterator_next()
+ to "advance" your \bt_msg_iter, that is, to get its next
+ messages.
+
+ Within this method, you receive:
+
+ - An array of \bt_p_msg to fill (\bt_p{messages} parameter)
+ with your message iterator's next messages, if any.
+
+ Note that this array needs its own message
+ \ref api-fund-shared-object "references". In other
+ words, if you have a message reference and you put this message
+ into the array without calling bt_message_get_ref(), then you just
+ \em moved the message reference to the array (the array owns the
+ message now).
+
+ - The capacity of the message array (\bt_p{capacity} parameter),
+ that is, the maximum number of messages you can put in it.
+
+ - A message count output parameter (\bt_p{count}) which, on success,
+ you must set to the number of messages you put in the message
+ array.
+
+ If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
+ from this method, then you must put at least one message in the
+ message array. In other words, \bt_p{*count} must be greater than
+ zero.
+
+ You must honour the \ref api-msg-seq "message sequence rules" when
+ you put new or existing messages in the message array.
+
+ If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
+ then all the messages of the message array become
+ \ref api-fund-freezing "frozen".
+
+ This method typically:
+
+ <dl>
+ <dt>For a \bt_src_comp's message iterator</dt>
+ <dd>
+ Creates brand new \bt_p_msg to represent one or more input
+ traces.
+ </dd>
+
+ <dt>For a \bt_flt_comp's message iterator</dt>
+ <dd>
+ Gets \em one message batch from one (or more) upstream
+ \bt_msg_iter and filters them.
+ </dd>
+ </dl>
+
+ For a source component's message iterator, you are free to create
+ as many as \bt_p{capacity} messages. For a filter component's
+ message iterator, you are free to get more than one batch of
+ messages from upstream message iterators if needed. However, in both
+ cases, keep in mind that the \bt_name project recommends that this
+ method executes fast enough so as not to block an interactive
+ application running on the same thread.
+
+ During what you consider to be a long, blocking operation, the
+ project recommends that you periodically check whether or not you
+ are interrupted with bt_self_message_iterator_is_interrupted(). When
+ you are, you can return either
+ #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN or
+ #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR, depending on
+ your capability to continue the current operation later.
+
+ If you need to block the thread to insert messages into the message
+ array, you can instead report to try again later to the caller by
+ returning #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN.
+ When you return this status code, you must \em not put any message
+ into the message array.
+
+ If your message iterator's iteration process is done (you have no
+ more messages to emit), then return
+ #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END. When you return
+ this status code, you must \em not put any message into the message
+ array.
+
+ Set this mandatory method at message iterator class creation time
+ with bt_message_iterator_class_create().
+ </dd>
+
+ <dt>
+ \anchor api-msg-iter-cls-meth-seek-beg
+ Seek beginning
+ </dt>
+ <dd>
+ Called within bt_message_iterator_seek_beginning() to make
+ your message iterator seek its beginning, that is, the very first
+ message of its \ref api-msg-seq "sequence".
+
+ The sequence of messages of a given message iterator must always be
+ the same, in that, if your message iterator emitted the messages A,
+ B, C, D, and E, and then this "seek beginning" method is called
+ successfully
+ (it returns
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK),
+ then your message iterator's next messages (the next time your
+ \link api-msg-iter-cls-meth-next "next" method\endlink
+ is called) must be A, B, C, D, and E.
+
+ The \bt_name project recommends that this method executes fast
+ enough so as not to block an interactive application running on the
+ same thread.
+
+ During what you consider to be a long, blocking operation, the
+ project recommends that you periodically check whether or not you
+ are interrupted with bt_self_message_iterator_is_interrupted(). When
+ you are, you can return either
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN or
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR,
+ depending on your capability to continue the current operation
+ later.
+
+ If you need to block the thread to make your message iterator seek
+ its beginning, you can instead report to try again later to the
+ caller by returning
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
+
+ The optional
+ \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
+ method can indicate whether or not your message iterator can
+ currently seek its beginning. If you implement it, the library
+ guarantees that it is called and returns #BT_TRUE before this "seek
+ beginning" is called, without any other message iterator methods
+ being called in between.
+
+ Set this optional method with the \bt_p{seek_method} parameter
+ of bt_message_iterator_class_set_seek_beginning_methods().
+ </dd>
+
+ <dt>
+ \anchor api-msg-iter-cls-meth-seek-ns
+ Seek ns from origin
+ </dt>
+ <dd>
+ Called within bt_message_iterator_seek_ns_from_origin() to make
+ your message iterator seek a message occuring at or after a specific
+ time given in nanoseconds from its
+ \ref api-tir-clock-cls-origin "clock class origin".
+
+ Within this method, your receive the specific time to seek as the
+ \bt_p{ns_from_origin} parameter. You don't receive any
+ \bt_clock_cls: the method operates at the nanosecond from some
+ origin level and it is left to the implementation to seek a message
+ having at least this time while still honouring the
+ \ref api-msg-seq "message sequence rules" the next time your
+ \link api-msg-iter-cls-meth-next "next" method\endlink is called.
+
+ If you return
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK from
+ this method, then the next time your
+ \link api-msg-iter-cls-meth-next "next" method\endlink is called:
+
+ - For each "active" \bt_stream at the seeked time point, you must
+ emit a \bt_sb_msg for this stream before you emit any other
+ message for this stream.
+
+ The stream beginning message must have a
+ \ref api-msg-sb-prop-cs "default clock snapshot" which corresponds
+ to the seeked time point.
+
+ - For each "active" \bt_pkt at the seeked time point, you must
+ emit a \bt_pb_msg for this packet before you emit any other
+ message for this packet.
+
+ The packet beginning message must have a
+ \ref api-msg-pb-prop-cs "default clock snapshot" which corresponds
+ to the seeked time point.
+
+ The \bt_name project recommends that this method executes fast
+ enough so as not to block an interactive application running on the
+ same thread.
+
+ During what you consider to be a long, blocking operation, the
+ project recommends that you periodically check whether or not you
+ are interrupted with bt_self_message_iterator_is_interrupted(). When
+ you are, you can return either
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
+ or
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR,
+ depending on your capability to continue the current operation
+ later.
+
+ If you need to block the thread to make your message iterator seek a
+ message occuring at or after a given time, you can instead report to
+ try again later to the caller by returning
+ #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
+
+ The optional
+ \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+ method can indicate whether or not your message iterator can
+ currently seek a specific time. If you implement it, the library
+ guarantees that it is called and returns #BT_TRUE before this "seek
+ ns from origin" is called, without any other message iterator
+ methods being called in between.
+
+ Set this optional method with the \bt_p{seek_method} parameter
+ of bt_message_iterator_class_set_seek_ns_from_origin_methods().
+ </dd>
+</dl>
+
+Within any method, you can access the \bt_msg_iter's \bt_comp's
+configured \ref #bt_logging_level "logging level" by first upcasting the
+\bt_self_comp to the #bt_component type with
+bt_self_component_as_component(), and then with
+bt_component_get_logging_level().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_message_iterator_class bt_message_iterator_class;
+
+@brief
+ Message iterator class.
+
+@}
+*/
+
+/*!
+@name Method types
+@{
+*/
+
+/*!
+@brief
+ Status codes for #bt_message_iterator_class_can_seek_beginning_method.
+*/
+typedef enum bt_message_iterator_class_can_seek_beginning_method_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Try again.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ User error.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_class_can_seek_beginning_method_status;
+
+/*!
+@brief
+ \bt_c_msg_iter "can seek beginning?" method.
+
+See the \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
+method.
+
+@param[in] self_message_iterator
+ Message iterator instance.
+@param[out] can_seek_beginning
+ <strong>On success</strong>, \bt_p{*can_seek_beginning} is
+ #BT_TRUE if \bt_p{self_message_iterator} can currently seek its
+ beginning.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR
+ User error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{can_seek_beginning}
+
+@post
+ <strong>On success</strong>, \bt_p{*can_seek_beginning} is set.
+
+@sa bt_message_iterator_class_set_seek_beginning_methods() —
+ Sets the "seek beginning" and "can seek beginning?" methods of a
+ message iterator class.
+*/
+typedef bt_message_iterator_class_can_seek_beginning_method_status
+(*bt_message_iterator_class_can_seek_beginning_method)(
+ bt_self_message_iterator *self_message_iterator,
+ bt_bool *can_seek_beginning);
+
+/*!
+@brief
+ Status codes for #bt_message_iterator_class_can_seek_ns_from_origin_method.
+*/
+typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Try again.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ User error.
+ */
+ BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_class_can_seek_ns_from_origin_method_status;
+
+/*!
+@brief
+ \bt_c_msg_iter "can seek ns from origin?" method.
+
+See the \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+method.
+
+@param[in] self_message_iterator
+ Message iterator instance.
+@param[in] ns_from_origin
+ Requested time point to seek.
+@param[out] can_seek_ns_from_origin
+ <strong>On success</strong>, set \bt_p{*can_seek_ns_from_origin} to
+ #BT_TRUE if \bt_p{self_message_iterator} can currently seek a
+ message occuring at or after \bt_p{ns_from_origin} nanoseconds from
+ its \ref api-tir-clock-cls-origin "clock class origin".
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
+ User error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{can_seek_ns_from_origin}
+
+@post
+ <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is set.
+
+@sa bt_message_iterator_class_set_seek_ns_from_origin_methods() —
+ Sets the "seek ns from origin" and "can seek ns from origin?"
+ methods of a message iterator class.
+*/
+typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status
+(*bt_message_iterator_class_can_seek_ns_from_origin_method)(
+ bt_self_message_iterator *self_message_iterator,
+ int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
+
+/*!
+@brief
+ \bt_c_msg_iter finalization method.
+
+See the \ref api-msg-iter-cls-meth-fini "finalize" method.
+
+@param[in] self_message_iterator
+ Message iterator instance.
+
+@bt_pre_not_null{self_message_iterator}
+
+@bt_post_no_error
+
+@sa bt_message_iterator_class_set_finalize_method() —
+ Sets the finalization method of a message iterator class.
+*/
+typedef void
+(*bt_message_iterator_class_finalize_method)(
+ bt_self_message_iterator *self_message_iterator);
+
+/*!
+@brief
+ Status codes for #bt_message_iterator_class_initialize_method.
+*/