[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 <stddef.h>
#include <stdint.h>
#include <stdio.h>

#include <babeltrace2/babeltrace.h>

#include "common/common.h"

/**
 * @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);
};

/**
 * 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
 */
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
 */
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
 */
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;
};

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

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);

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);

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`.
 */
void ctf_msg_iter_reset(struct ctf_msg_iter *msg_it);

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

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