X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=29b60980cac2bbb37d9c52058517b27c419ca860;hb=4841ccc167f5f99267a0c129a1e79214b60f553c;hp=1be85cfdeb4d197246ce6fe7324c56b20fa0f2ab;hpb=bc37ae52aa6face901440bf7eb2171104b5343d8;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index 1be85cfd..29b60980 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -31,6 +31,8 @@ */ #include +#include +#include #ifdef __cplusplus extern "C" { @@ -44,7 +46,13 @@ struct bt_ctf_clock; /* * bt_ctf_trace_create: create a trace instance. * - * Allocate a new trace + * Allocate a new trace. + * + * A trace's default packet header is a structure initialized with the following + * fields: + * - uint32_t magic + * - uint8_t uuid[16] + * - uint32_t stream_id * * Returns a new trace on success, NULL on error. */ @@ -66,10 +74,36 @@ extern struct bt_ctf_stream *bt_ctf_trace_create_stream( struct bt_ctf_stream_class *stream_class); /* - * bt_ctf_trace_add_environment_field: add an environment field to the trace. + * bt_ctf_trace_set_environment_field: sets an environment field to the + * trace. + * + * Sets an environment field to the trace. The name parameter is + * copied, whereas the value parameter's reference count is incremented + * (if the function succeeds). * - * Add an environment field to the trace. The name and value parameters are - * copied. + * If a value exists in the environment for the specified name, it is + * replaced by the new value. + * + * The value parameter _must_ be either an integer value object or a + * string value object. Other object types are not supported. + * + * @param trace Trace instance. + * @param name Name of the environment field (will be copied). + * @param value Value of the environment field. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_trace_set_environment_field( + struct bt_ctf_trace *trace, const char *name, + struct bt_value *value); + +/* + * bt_ctf_trace_set_environment_field_string: sets a string environment + * field to the trace. + * + * Sets a string environment field to the trace. This is a helper + * function which corresponds to calling + * bt_ctf_trace_set_environment_field() with a string object. * * @param trace Trace instance. * @param name Name of the environment field (will be copied). @@ -77,10 +111,90 @@ extern struct bt_ctf_stream *bt_ctf_trace_create_stream( * * Returns 0 on success, a negative value on error. */ -extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace, - const char *name, +extern int bt_ctf_trace_set_environment_field_string( + struct bt_ctf_trace *trace, const char *name, const char *value); +/* + * bt_ctf_trace_set_environment_field_integer: sets an integer environment + * field to the trace. + * + * Sets an integer environment field to the trace. This is a helper + * function which corresponds to calling + * bt_ctf_trace_set_environment_field() with an integer object. + * + * @param trace Trace instance. + * @param name Name of the environment field (will be copied). + * @param value Value of the environment field. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_trace_set_environment_field_integer( + struct bt_ctf_trace *trace, const char *name, + int64_t value); + +/* + * bt_ctf_trace_get_environment_field_count: get environment field count. + * + * Get the trace's environment field count. + * + * @param trace Trace instance. + * + * Returns the environment field count, a negative value on error. + */ +extern int bt_ctf_trace_get_environment_field_count( + struct bt_ctf_trace *trace); + +/* + * bt_ctf_trace_get_environment_field_name: get environment field name. + * + * Get an environment field's name. The string's ownership is not + * transferred to the caller. The string data is valid as long as + * this trace's environment is not modified. + * + * @param trace Trace instance. + * @param index Index of the environment field. + * + * Returns the environment field's name, NULL on error. + */ +extern const char * +bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace *trace, + int index); + +/* + * bt_ctf_trace_get_environment_field_value: get environment + * field value (an object). + * + * Get an environment field's value (an object). The returned object's + * reference count is incremented. When done with the object, the caller + * must call bt_value_put() on it. + * + * @param trace Trace instance. + * @param index Index of the environment field. + * + * Returns the environment field's object value, NULL on error. + */ +extern struct bt_value * +bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace *trace, + int index); + +/* + * bt_ctf_trace_get_environment_field_value_by_name: get environment + * field value (an object) by name. + * + * Get an environment field's value (an object) by its field name. The + * returned object's reference count is incremented. When done with the + * object, the caller must call bt_value_put() on it. + * + * @param trace Trace instance. + * @param name Environment field's name + * + * Returns the environment field's object value, NULL on error. + */ +extern struct bt_value * +bt_ctf_trace_get_environment_field_value_by_name(struct bt_ctf_trace *trace, + const char *name); + /* * bt_ctf_trace_add_clock: add a clock to the trace. * @@ -95,6 +209,83 @@ extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace, extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace, struct bt_ctf_clock *clock); +/* + * bt_ctf_trace_get_clock_count: get the number of clocks + * associated with the trace. + * + * @param trace Trace instance. + * + * Returns the clock count on success, a negative value on error. + */ +extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace); + +/* + * bt_ctf_trace_get_clock: get a trace's clock at index. + * + * @param trace Trace instance. + * @param index Index of the clock in the given trace. + * + * Return a clock instance on success, NULL on error. + */ +extern struct bt_ctf_clock *bt_ctf_trace_get_clock( + struct bt_ctf_trace *trace, int index); + +/* + * bt_ctf_trace_add_stream_class: add a stream_class to the trace. + * + * Add a stream class to the trace. + * + * @param trace Trace instance. + * @param stream_class Stream class to add to the trace. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace, + struct bt_ctf_stream_class *stream_class); + +/* + * bt_ctf_trace_get_stream_class_count: get the number of stream classes + * associated with the trace. + * + * @param trace Trace instance. + * + * Returns the stream class count on success, a negative value on error. + */ +extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace *trace); + +/* + * bt_ctf_trace_get_stream_class: get a trace's stream class at index. + * + * @param trace Trace instance. + * @param index Index of the stream class in the given trace. + * + * Return a stream class on success, NULL on error. + */ +extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class( + struct bt_ctf_trace *trace, int index); + +/* + * bt_ctf_trace_get_stream_class_by_id: get a trace's stream class by ID. + * + * @param trace Trace instance. + * @param index ID of the stream class in the given trace. + * + * Return a stream class on success, NULL on error. + */ +extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id( + struct bt_ctf_trace *trace, uint32_t id); + +/* + * bt_ctf_trace_get_clock_by_name: get a trace's clock by name + * + * @param trace Trace instance. + * @param name Name of the clock in the given trace. + * + * Return a clock instance on success, NULL on error. + */ +extern struct bt_ctf_clock *bt_ctf_trace_get_clock_by_name( + struct bt_ctf_trace *trace, const char *name); + /* * bt_ctf_trace_get_metadata_string: get metadata string. * @@ -108,23 +299,66 @@ extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace, extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace); /* - * bt_ctf_trace_set_byte_order: set a field type's byte order. + * bt_ctf_trace_get_byte_order: get a trace's byte order. * - * Set the trace's byte order. Defaults to BT_CTF_BYTE_ORDER_NATIVE, - * the host machine's endianness. + * Get the trace's byte order. + * + * @param trace Trace instance. + * + * Returns the trace's endianness, BT_CTF_BYTE_ORDER_UNKNOWN on error. + */ +extern enum bt_ctf_byte_order bt_ctf_trace_get_byte_order( + struct bt_ctf_trace *trace); + +/* + * bt_ctf_trace_set_byte_order: set a trace's byte order. + * + * Set the trace's byte order. Defaults to the current host's endianness. * * @param trace Trace instance. * @param byte_order Trace's byte order. * * Returns 0 on success, a negative value on error. + * + * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according + * to the CTF specification, is defined as "the byte order described in the + * trace description". */ extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace, enum bt_ctf_byte_order byte_order); +/* + * bt_ctf_trace_get_packet_header_type: get a trace's packet header type. + * + * Get the trace's packet header type. + * + * @param trace Trace instance. + * + * Returns the trace's packet header type (a structure) on success, NULL on + * error. + */ +extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type( + struct bt_ctf_trace *trace); + +/* + * bt_ctf_trace_set_packet_header_type: set a trace's packet header type. + * + * Set the trace's packet header type. + * + * @param trace Trace instance. + * @param packet_header_type Packet header field type (must be a structure). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace, + struct bt_ctf_field_type *packet_header_type); + /* * bt_ctf_trace_get and bt_ctf_trace_put: increment and decrement the * trace's reference count. * + * You may also use bt_ctf_get() and bt_ctf_put() with trace objects. + * * These functions ensure that the trace won't be destroyed while it * is in use. The same number of get and put (plus one extra put to * release the initial reference done at creation) have to be done to