[babeltrace.git] / src / plugins / ctf / common / msg-iter / msg-iter.hpp

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
 *
 * Babeltrace - CTF message iterator
 */

#ifndef CTF_MSG_ITER_H
#define CTF_MSG_ITER_H

#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stddef.h>
#include <babeltrace2/babeltrace.h>
#include "common/macros.h"

#include "../metadata/ctf-meta.hpp"

/**
 * @file ctf-msg-iter.h
 *
 * CTF message iterator
 *
 * This is a common internal API used by CTF source plugins. It allows
 * one to get messages from a user-provided medium.
 */

/**
 * Medium operations status codes.  These use the same values as
 * libbabeltrace2.
 */
enum ctf_msg_iter_medium_status
{
    /**
     * End of file.
     *
     * The medium function called by the message iterator
     * function reached the end of the file.
     */
    CTF_MSG_ITER_MEDIUM_STATUS_EOF = 1,

    /**
     * There is no data available right now, try again later.
     */
    CTF_MSG_ITER_MEDIUM_STATUS_AGAIN = 11,

    /** General error. */
    CTF_MSG_ITER_MEDIUM_STATUS_ERROR = -1,

    /** Memory error. */
    CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR = -12,

    /** Everything okay. */
    CTF_MSG_ITER_MEDIUM_STATUS_OK = 0,
};

/**
 * CTF message iterator API status code.
 */
enum ctf_msg_iter_status
{
    /**
     * End of file.
     *
     * The medium function called by the message iterator
     * function reached the end of the file.
     */
    CTF_MSG_ITER_STATUS_EOF = CTF_MSG_ITER_MEDIUM_STATUS_EOF,

    /**
     * There is no data available right now, try again later.
     *
     * Some condition resulted in the
     * ctf_msg_iter_medium_ops::request_bytes() user function not
     * having access to any data now. You should retry calling the
     * last called message iterator function once the situation
     * is resolved.
     */
    CTF_MSG_ITER_STATUS_AGAIN = CTF_MSG_ITER_MEDIUM_STATUS_AGAIN,

    /** General error. */
    CTF_MSG_ITER_STATUS_ERROR = CTF_MSG_ITER_MEDIUM_STATUS_ERROR,

    /** Memory error. */
    CTF_MSG_ITER_STATUS_MEMORY_ERROR = CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR,

    /** Everything okay. */
    CTF_MSG_ITER_STATUS_OK = CTF_MSG_ITER_MEDIUM_STATUS_OK,
};

/**
 * Medium operations.
 *
 * Those user functions are called by the message iterator
 * functions to request medium actions.
 */
struct ctf_msg_iter_medium_ops
{
    /**
     * Returns the next byte buffer to be used by the binary file
     * reader to deserialize binary data.
     *
     * This function \em must be defined.
     *
     * The purpose of this function is to return a buffer of bytes
     * to the message iterator, of a maximum of \p request_sz
     * bytes. If this function cannot return a buffer of at least
     * \p request_sz bytes, it may return a smaller buffer. In
     * either cases, \p buffer_sz must be set to the returned buffer
     * size (in bytes).
     *
     * The returned buffer's ownership remains the medium, in that
     * it won't be freed by the message iterator functions. The
     * returned buffer won't be modified by the message
     * iterator functions either.
     *
     * When this function is called for the first time for a given
     * file, the offset within the file is considered to be 0. The
     * next times this function is called, the returned buffer's
     * byte offset within the complete file must be the previous
     * offset plus the last returned value of \p buffer_sz by this
     * medium.
     *
     * This function must return one of the following statuses:
     *
     *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_OK</b>: Everything
     *     is okay, i.e. \p buffer_sz is set to a positive value
     *     reflecting the number of available bytes in the buffer
     *     starting at the address written in \p buffer_addr.
     *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_AGAIN</b>: No data is
     *     available right now. In this case, the message
     *     iterator function called by the user returns
     *     #CTF_MSG_ITER_STATUS_AGAIN, and it is the user's
     *     responsibility to make sure enough data becomes available
     *     before calling the \em same message iterator
     *     function again to continue the decoding process.
     *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_EOF</b>: The end of
     *     the file was reached, and no more data will ever be
     *     available for this file. In this case, the message
     *     iterator function called by the user returns
     *     #CTF_MSG_ITER_STATUS_EOF. This must \em not be
     *     returned when returning at least one byte of data to the
     *     caller, i.e. this must be returned when there's
     *     absolutely nothing left; should the request size be
     *     larger than what's left in the file, this function must
     *     return what's left, setting \p buffer_sz to the number of
     *     remaining bytes, and return
     *     #CTF_MSG_ITER_MEDIUM_STATUS_EOF on the \em following
     *     call.
     *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_ERROR</b>: A fatal
     *     error occurred during this operation. In this case, the
     *     message iterator function called by the user returns
     *     #CTF_MSG_ITER_STATUS_ERROR.
     *
     * If #CTF_MSG_ITER_MEDIUM_STATUS_OK is not returned, the
     * values of \p buffer_sz and \p buffer_addr are \em ignored by
     * the caller.
     *
     * @param request_sz	Requested buffer size (bytes)
     * @param buffer_addr	Returned buffer address
     * @param buffer_sz	Returned buffer's size (bytes)
     * @param data		User data
     * @returns		Status code (see description above)
     */
    enum ctf_msg_iter_medium_status (*request_bytes)(size_t request_sz, uint8_t **buffer_addr,
                                                     size_t *buffer_sz, void *data);

    /**
     * Repositions the underlying stream's position.
     *
     * This *optional* method repositions the underlying stream
     * to a given absolute position in the medium.
     *
     * @param offset	Offset to use for the given directive
     * @param data		User data
     * @returns		One of #ctf_msg_iter_medium_status values
     */
    enum ctf_msg_iter_medium_status (*seek)(off_t offset, void *data);

    /**
     * Called when the message iterator wishes to inform the medium that it
     * is about to start a new packet.
     *
     * After the iterator has called switch_packet, the following call to
     * request_bytes must return the content at the start of the next
     * packet.	 */
    enum ctf_msg_iter_medium_status (*switch_packet)(void *data);

    /**
     * Returns a stream instance (weak reference) for the given
     * stream class.
     *
     * This is called after a packet header is read, and the
     * corresponding stream class is found by the message
     * iterator.
     *
     * @param stream_class	Stream class of the stream to get
     * @param stream_id	Stream (instance) ID of the stream
     *			to get (-1ULL if not available)
     * @param data		User data
     * @returns		Stream instance (weak reference) or
     *			\c NULL on error
     */
    bt_stream *(*borrow_stream)(bt_stream_class *stream_class, int64_t stream_id, void *data);
};

/** CTF message iterator. */
struct ctf_msg_iter;

/**
 * Creates a CTF message iterator.
 *
 * Upon successful completion, the reference count of \p trace is
 * incremented.
 *
 * @param trace			Trace to read
 * @param max_request_sz	Maximum buffer size, in bytes, to
 *				request to
 *				ctf_msg_iter_medium_ops::request_bytes()
 * 				at a time
 * @param medops		Medium operations
 * @param medops_data		User data (passed to medium operations)
 * @returns			New CTF message iterator on
 *				success, or \c NULL on error
 */
BT_HIDDEN
struct ctf_msg_iter *ctf_msg_iter_create(struct ctf_trace_class *tc, size_t max_request_sz,
                                         struct ctf_msg_iter_medium_ops medops, void *medops_data,
                                         bt_logging_level log_level, bt_self_component *self_comp,
                                         bt_self_message_iterator *self_msg_iter);

/**
 * Destroys a CTF message iterator, freeing all internal resources.
 *
 * The registered trace's reference count is decremented.
 *
 * @param msg_iter		CTF message iterator
 */
BT_HIDDEN
void ctf_msg_iter_destroy(struct ctf_msg_iter *msg_iter);

/**
 * Returns the next message from a CTF message iterator.
 *
 * Upon successful completion, #CTF_MSG_ITER_STATUS_OK is
 * returned, and the next message is written to \p msg.
 * In this case, the caller is responsible for calling
 * bt_message_put() on the returned message.
 *
 * If this function returns #CTF_MSG_ITER_STATUS_AGAIN, the caller
 * should make sure that data becomes available to its medium, and
 * call this function again, until another status is returned.
 *
 * @param msg_iter		CTF message iterator
 * @param message		Returned message if the function's
 *				return value is #CTF_MSG_ITER_STATUS_OK
 * @returns			One of #ctf_msg_iter_status values
 */
BT_HIDDEN
enum ctf_msg_iter_status ctf_msg_iter_get_next_message(struct ctf_msg_iter *msg_it,
                                                       const bt_message **message);

struct ctf_msg_iter_packet_properties
{
    int64_t exp_packet_total_size;
    int64_t exp_packet_content_size;
    uint64_t stream_class_id;
    int64_t data_stream_id;

    struct
    {
        uint64_t discarded_events;
        uint64_t packets;
        uint64_t beginning_clock;
        uint64_t end_clock;
    } snapshots;
};

BT_HIDDEN
enum ctf_msg_iter_status
ctf_msg_iter_get_packet_properties(struct ctf_msg_iter *msg_it,
                                   struct ctf_msg_iter_packet_properties *props);

BT_HIDDEN
enum ctf_msg_iter_status
ctf_msg_iter_curr_packet_first_event_clock_snapshot(struct ctf_msg_iter *msg_it,
                                                    uint64_t *first_event_cs);

BT_HIDDEN
enum ctf_msg_iter_status
ctf_msg_iter_curr_packet_last_event_clock_snapshot(struct ctf_msg_iter *msg_it,
                                                   uint64_t *last_event_cs);

BT_HIDDEN
enum ctf_msg_iter_status ctf_msg_iter_seek(struct ctf_msg_iter *msg_it, off_t offset);

/*
 * Resets the iterator so that the next requested medium bytes are
 * assumed to be the first bytes of a new stream. Depending on
 * ctf_msg_iter_set_emit_stream_beginning_message(), the first message
 * which this iterator emits after calling ctf_msg_iter_reset() is of
 * type `CTF_MESSAGE_TYPE_STREAM_BEGINNING`.
 */
BT_HIDDEN
void ctf_msg_iter_reset(struct ctf_msg_iter *msg_it);

/*
 * Like ctf_msg_iter_reset(), but preserves stream-dependent state.
 */
BT_HIDDEN
void ctf_msg_iter_reset_for_next_stream_file(struct ctf_msg_iter *msg_it);

BT_HIDDEN
void ctf_msg_iter_set_dry_run(struct ctf_msg_iter *msg_it, bool val);

static inline const char *ctf_msg_iter_medium_status_string(enum ctf_msg_iter_medium_status status)
{
    switch (status) {
    case CTF_MSG_ITER_MEDIUM_STATUS_EOF:
        return "EOF";
    case CTF_MSG_ITER_MEDIUM_STATUS_AGAIN:
        return "AGAIN";
    case CTF_MSG_ITER_MEDIUM_STATUS_ERROR:
        return "ERROR";
    case CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR:
        return "MEMORY_ERROR";
    case CTF_MSG_ITER_MEDIUM_STATUS_OK:
        return "OK";
    }

    bt_common_abort();
}

static inline const char *ctf_msg_iter_status_string(enum ctf_msg_iter_status status)
{
    switch (status) {
    case CTF_MSG_ITER_STATUS_EOF:
        return "EOF";
    case CTF_MSG_ITER_STATUS_AGAIN:
        return "AGAIN";
    case CTF_MSG_ITER_STATUS_ERROR:
        return "ERROR";
    case CTF_MSG_ITER_STATUS_MEMORY_ERROR:
        return "MEMORY_ERROR";
    case CTF_MSG_ITER_STATUS_OK:
        return "OK";
    }

    bt_common_abort();
}

#endif /* CTF_MSG_ITER_H */
Commit	Line	Data
e98a2d6e	1	/*
0235b0db	2	* SPDX-License-Identifier: MIT
fc917f65	3	*
e98a2d6e PP	4	* Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
	5	* Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
	6	*
0235b0db	7	* Babeltrace - CTF message iterator
e98a2d6e PP	8	*/
e98a2d6e PP	9
0235b0db MJ	10	#ifndef CTF_MSG_ITER_H
	11	#define CTF_MSG_ITER_H
	12
c4f23e30	13	#include <stdbool.h>
e98a2d6e PP	14	#include <stdint.h>
	15	#include <stdio.h>
	16	#include <stddef.h>
3fadfbc0	17	#include <babeltrace2/babeltrace.h>
91d81473	18	#include "common/macros.h"
e98a2d6e	19
087cd0f5	20	#include "../metadata/ctf-meta.hpp"
44c440bc	21
e98a2d6e	22	/**
d6e69534	23	* @file ctf-msg-iter.h
e98a2d6e	24	*
d6e69534	25	* CTF message iterator
fc917f65	26	*
e98a2d6e	27	* This is a common internal API used by CTF source plugins. It allows
d6e69534	28	* one to get messages from a user-provided medium.
e98a2d6e PP	29	*/
	30
	31	/**
f6e68e70 SM	32	* Medium operations status codes. These use the same values as
f6e68e70 SM	33	* libbabeltrace2.
e98a2d6e	34	*/
4164020e SM	35	enum ctf_msg_iter_medium_status
	36	{
	37	/**
	38	* End of file.
	39	*
	40	* The medium function called by the message iterator
	41	* function reached the end of the file.
	42	*/
	43	CTF_MSG_ITER_MEDIUM_STATUS_EOF = 1,
	44
	45	/**
	46	* There is no data available right now, try again later.
	47	*/
	48	CTF_MSG_ITER_MEDIUM_STATUS_AGAIN = 11,
	49
	50	/** General error. */
	51	CTF_MSG_ITER_MEDIUM_STATUS_ERROR = -1,
	52
	53	/** Memory error. */
	54	CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR = -12,
	55
	56	/** Everything okay. */
	57	CTF_MSG_ITER_MEDIUM_STATUS_OK = 0,
e98a2d6e PP	58	};
	59
	60	/**
d6e69534	61	* CTF message iterator API status code.
e98a2d6e	62	*/
4164020e SM	63	enum ctf_msg_iter_status
	64	{
	65	/**
	66	* End of file.
	67	*
	68	* The medium function called by the message iterator
	69	* function reached the end of the file.
	70	*/
	71	CTF_MSG_ITER_STATUS_EOF = CTF_MSG_ITER_MEDIUM_STATUS_EOF,
	72
	73	/**
	74	* There is no data available right now, try again later.
	75	*
	76	* Some condition resulted in the
	77	* ctf_msg_iter_medium_ops::request_bytes() user function not
	78	* having access to any data now. You should retry calling the
	79	* last called message iterator function once the situation
	80	* is resolved.
	81	*/
	82	CTF_MSG_ITER_STATUS_AGAIN = CTF_MSG_ITER_MEDIUM_STATUS_AGAIN,
	83
	84	/** General error. */
	85	CTF_MSG_ITER_STATUS_ERROR = CTF_MSG_ITER_MEDIUM_STATUS_ERROR,
	86
	87	/** Memory error. */
	88	CTF_MSG_ITER_STATUS_MEMORY_ERROR = CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR,
	89
	90	/** Everything okay. */
	91	CTF_MSG_ITER_STATUS_OK = CTF_MSG_ITER_MEDIUM_STATUS_OK,
e98a2d6e PP	92	};
	93
	94	/**
	95	* Medium operations.
	96	*
d6e69534	97	* Those user functions are called by the message iterator
e98a2d6e PP	98	* functions to request medium actions.
e98a2d6e PP	99	*/
4164020e SM	100	struct ctf_msg_iter_medium_ops
	101	{
	102	/**
	103	* Returns the next byte buffer to be used by the binary file
	104	* reader to deserialize binary data.
	105	*
	106	* This function \em must be defined.
	107	*
	108	* The purpose of this function is to return a buffer of bytes
	109	* to the message iterator, of a maximum of \p request_sz
	110	* bytes. If this function cannot return a buffer of at least
	111	* \p request_sz bytes, it may return a smaller buffer. In
	112	* either cases, \p buffer_sz must be set to the returned buffer
	113	* size (in bytes).
	114	*
	115	* The returned buffer's ownership remains the medium, in that
	116	* it won't be freed by the message iterator functions. The
	117	* returned buffer won't be modified by the message
	118	* iterator functions either.
	119	*
	120	* When this function is called for the first time for a given
	121	* file, the offset within the file is considered to be 0. The
	122	* next times this function is called, the returned buffer's
	123	* byte offset within the complete file must be the previous
	124	* offset plus the last returned value of \p buffer_sz by this
	125	* medium.
	126	*
	127	* This function must return one of the following statuses:
	128	*
	129	* - <b>#CTF_MSG_ITER_MEDIUM_STATUS_OK</b>: Everything
	130	* is okay, i.e. \p buffer_sz is set to a positive value
	131	* reflecting the number of available bytes in the buffer
	132	* starting at the address written in \p buffer_addr.
	133	* - <b>#CTF_MSG_ITER_MEDIUM_STATUS_AGAIN</b>: No data is
	134	* available right now. In this case, the message
	135	* iterator function called by the user returns
	136	* #CTF_MSG_ITER_STATUS_AGAIN, and it is the user's
	137	* responsibility to make sure enough data becomes available
	138	* before calling the \em same message iterator
	139	* function again to continue the decoding process.
	140	* - <b>#CTF_MSG_ITER_MEDIUM_STATUS_EOF</b>: The end of
	141	* the file was reached, and no more data will ever be
	142	* available for this file. In this case, the message
	143	* iterator function called by the user returns
	144	* #CTF_MSG_ITER_STATUS_EOF. This must \em not be
	145	* returned when returning at least one byte of data to the
	146	* caller, i.e. this must be returned when there's
	147	* absolutely nothing left; should the request size be
	148	* larger than what's left in the file, this function must
	149	* return what's left, setting \p buffer_sz to the number of
	150	* remaining bytes, and return
	151	* #CTF_MSG_ITER_MEDIUM_STATUS_EOF on the \em following
	152	* call.
	153	* - <b>#CTF_MSG_ITER_MEDIUM_STATUS_ERROR</b>: A fatal
	154	* error occurred during this operation. In this case, the
	155	* message iterator function called by the user returns
	156	* #CTF_MSG_ITER_STATUS_ERROR.
	157	*
	158	* If #CTF_MSG_ITER_MEDIUM_STATUS_OK is not returned, the
	159	* values of \p buffer_sz and \p buffer_addr are \em ignored by
	160	* the caller.
	161	*
	162	* @param request_sz Requested buffer size (bytes)
	163	* @param buffer_addr Returned buffer address
164	* @param buffer_sz Returned buffer's size (bytes)
165	* @param data User data
166	* @returns Status code (see description above)
167	*/
168	enum ctf_msg_iter_medium_status (request_bytes)(size_t request_sz, uint8_t *buffer_addr,
169	size_t buffer_sz, void data);
170
171	/**
172	* Repositions the underlying stream's position.
173	*
174	* This optional method repositions the underlying stream
175	* to a given absolute position in the medium.
176	*
177	* @param offset Offset to use for the given directive
178	* @param data User data
179	* @returns One of #ctf_msg_iter_medium_status values
180	*/
181	enum ctf_msg_iter_medium_status (seek)(off_t offset, void data);
182
183	/**
184	* Called when the message iterator wishes to inform the medium that it
185	* is about to start a new packet.
186	*
187	* After the iterator has called switch_packet, the following call to
188	* request_bytes must return the content at the start of the next
189	* packet. */
190	enum ctf_msg_iter_medium_status (switch_packet)(void data);
191
192	/**
193	* Returns a stream instance (weak reference) for the given
194	* stream class.
195	*
196	* This is called after a packet header is read, and the
197	* corresponding stream class is found by the message
198	* iterator.
199	*
200	* @param stream_class Stream class of the stream to get
201	* @param stream_id Stream (instance) ID of the stream
202	* to get (-1ULL if not available)
203	* @param data User data
204	* @returns Stream instance (weak reference) or
205	* \c NULL on error
206	*/
207	bt_stream (borrow_stream)(bt_stream_class stream_class, int64_t stream_id, void data);
e98a2d6e PP	208	};
e98a2d6e PP	209
d6e69534	210	/** CTF message iterator. */
18a1979b	211	struct ctf_msg_iter;
e98a2d6e	212
e98a2d6e	213	/**
d6e69534	214	* Creates a CTF message iterator.
e98a2d6e PP	215	*
	216	* Upon successful completion, the reference count of \p trace is
	217	* incremented.
	218	*
	219	* @param trace Trace to read
	220	* @param max_request_sz Maximum buffer size, in bytes, to
	221	* request to
18a1979b	222	* ctf_msg_iter_medium_ops::request_bytes()
e98a2d6e PP	223	* at a time
	224	* @param medops Medium operations
	225	* @param medops_data User data (passed to medium operations)
d6e69534	226	* @returns New CTF message iterator on
e98a2d6e PP	227	* success, or \c NULL on error
e98a2d6e PP	228	*/
2cf1d51e	229	BT_HIDDEN
4164020e SM	230	struct ctf_msg_iter ctf_msg_iter_create(struct ctf_trace_class tc, size_t max_request_sz,
	231	struct ctf_msg_iter_medium_ops medops, void *medops_data,
	232	bt_logging_level log_level, bt_self_component *self_comp,
	233	bt_self_message_iterator *self_msg_iter);
e98a2d6e PP	234
e98a2d6e PP	235	/**
d6e69534	236	* Destroys a CTF message iterator, freeing all internal resources.
e98a2d6e PP	237	*
	238	* The registered trace's reference count is decremented.
	239	*
d6e69534	240	* @param msg_iter CTF message iterator
e98a2d6e	241	*/
2cf1d51e	242	BT_HIDDEN
18a1979b	243	void ctf_msg_iter_destroy(struct ctf_msg_iter *msg_iter);
e98a2d6e	244
e98a2d6e	245	/**
d6e69534	246	* Returns the next message from a CTF message iterator.
e98a2d6e	247	*
18a1979b	248	* Upon successful completion, #CTF_MSG_ITER_STATUS_OK is
d6e69534	249	* returned, and the next message is written to \p msg.
e98a2d6e	250	* In this case, the caller is responsible for calling
d6e69534	251	* bt_message_put() on the returned message.
e98a2d6e	252	*
18a1979b	253	* If this function returns #CTF_MSG_ITER_STATUS_AGAIN, the caller
e98a2d6e PP	254	* should make sure that data becomes available to its medium, and
	255	* call this function again, until another status is returned.
	256	*
d6e69534 PP	257	* @param msg_iter CTF message iterator
d6e69534 PP	258	* @param message Returned message if the function's
18a1979b SM	259	* return value is #CTF_MSG_ITER_STATUS_OK
18a1979b SM	260	* @returns One of #ctf_msg_iter_status values
e98a2d6e	261	*/
2cf1d51e	262	BT_HIDDEN
4164020e SM	263	enum ctf_msg_iter_status ctf_msg_iter_get_next_message(struct ctf_msg_iter *msg_it,
	264	const bt_message **message);
	265
	266	struct ctf_msg_iter_packet_properties
	267	{
	268	int64_t exp_packet_total_size;
	269	int64_t exp_packet_content_size;
	270	uint64_t stream_class_id;
	271	int64_t data_stream_id;
	272
	273	struct
	274	{
	275	uint64_t discarded_events;
	276	uint64_t packets;
	277	uint64_t beginning_clock;
	278	uint64_t end_clock;
	279	} snapshots;
44c440bc PP	280	};
	281
	282	BT_HIDDEN
4164020e SM	283	enum ctf_msg_iter_status
	284	ctf_msg_iter_get_packet_properties(struct ctf_msg_iter *msg_it,
	285	struct ctf_msg_iter_packet_properties *props);
44c440bc	286
27f26617	287	BT_HIDDEN
4164020e SM	288	enum ctf_msg_iter_status
	289	ctf_msg_iter_curr_packet_first_event_clock_snapshot(struct ctf_msg_iter *msg_it,
	290	uint64_t *first_event_cs);
27f26617 FD	291
27f26617 FD	292	BT_HIDDEN
4164020e SM	293	enum ctf_msg_iter_status
	294	ctf_msg_iter_curr_packet_last_event_clock_snapshot(struct ctf_msg_iter *msg_it,
	295	uint64_t *last_event_cs);
27f26617	296
9e0c8dbb	297	BT_HIDDEN
4164020e	298	enum ctf_msg_iter_status ctf_msg_iter_seek(struct ctf_msg_iter *msg_it, off_t offset);
9e0c8dbb	299
f42867e2 PP	300	/*
f42867e2 PP	301	* Resets the iterator so that the next requested medium bytes are
fc917f65	302	* assumed to be the first bytes of a new stream. Depending on
18a1979b SM	303	* ctf_msg_iter_set_emit_stream_beginning_message(), the first message
	304	* which this iterator emits after calling ctf_msg_iter_reset() is of
	305	* type `CTF_MESSAGE_TYPE_STREAM_BEGINNING`.
f42867e2 PP	306	*/
f42867e2 PP	307	BT_HIDDEN
18a1979b	308	void ctf_msg_iter_reset(struct ctf_msg_iter *msg_it);
f42867e2	309
495490c5	310	/*
18a1979b	311	* Like ctf_msg_iter_reset(), but preserves stream-dependent state.
495490c5 PP	312	*/
495490c5 PP	313	BT_HIDDEN
18a1979b	314	void ctf_msg_iter_reset_for_next_stream_file(struct ctf_msg_iter *msg_it);
495490c5	315
de24a43f	316	BT_HIDDEN
4164020e	317	void ctf_msg_iter_set_dry_run(struct ctf_msg_iter *msg_it, bool val);
de24a43f	318
4164020e	319	static inline const char *ctf_msg_iter_medium_status_string(enum ctf_msg_iter_medium_status status)
fdf0e7a0	320	{
4164020e SM	321	switch (status) {
	322	case CTF_MSG_ITER_MEDIUM_STATUS_EOF:
	323	return "EOF";
	324	case CTF_MSG_ITER_MEDIUM_STATUS_AGAIN:
	325	return "AGAIN";
	326	case CTF_MSG_ITER_MEDIUM_STATUS_ERROR:
	327	return "ERROR";
	328	case CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR:
	329	return "MEMORY_ERROR";
	330	case CTF_MSG_ITER_MEDIUM_STATUS_OK:
	331	return "OK";
	332	}
	333
	334	bt_common_abort();
fdf0e7a0 PP	335	}
fdf0e7a0 PP	336
4164020e	337	static inline const char *ctf_msg_iter_status_string(enum ctf_msg_iter_status status)
fdf0e7a0	338	{
4164020e SM	339	switch (status) {
	340	case CTF_MSG_ITER_STATUS_EOF:
	341	return "EOF";
	342	case CTF_MSG_ITER_STATUS_AGAIN:
	343	return "AGAIN";
	344	case CTF_MSG_ITER_STATUS_ERROR:
	345	return "ERROR";
	346	case CTF_MSG_ITER_STATUS_MEMORY_ERROR:
	347	return "MEMORY_ERROR";
	348	case CTF_MSG_ITER_STATUS_OK:
	349	return "OK";
	350	}
	351
	352	bt_common_abort();
fdf0e7a0 PP	353	}
fdf0e7a0 PP	354
d6e69534	355	#endif /* CTF_MSG_ITER_H */