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