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