X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=e6a3bc47f779799be7ccc54cc8f81195860a0715;hb=c55a9f585da53ea54ac458155fac3cdec1779d47;hp=4286df93c24a43dc68a590bb977df2730eb15a45;hpb=9ac68eb139149d2768848dae5e263cc5a755d439;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index 4286df93..e6a3bc47 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -34,6 +34,7 @@ #include #include #include +#include #include #ifdef __cplusplus @@ -62,10 +63,11 @@ You can obtain a trace class in two different modes: A trace class has the following properties: - A \b name. -- A default byte order: all the +- A native byte order: all the \link ctfirfieldtypes field types\endlink eventually part of the trace class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this "real" byte order. +- A \b UUID. - An \b environment, which is a custom key-value mapping. Keys are strings and values can be strings or integers. @@ -123,11 +125,6 @@ except for: - Adding a CTF IR clock class to it with bt_ctf_trace_add_clock_class(). - \link refs Reference counting\endlink. -You can add a custom listener with bt_ctf_trace_add_listener() to get -notified if anything changes in a trace class, that is, if an event -class is added to one of its stream class, if a stream class is added, -or if a clock class is added. - @sa ctfirstreamclass @sa ctfireventclass @sa ctfirclockclass @@ -159,24 +156,21 @@ struct bt_ctf_clock_class; @brief Creates a default CTF IR trace class. On success, the trace packet header field type of the created trace -class has the following fields: - -- magic: a 32-bit unsigned integer field type. -- uuid: an array field type of 16 8-bit unsigned integer - field types. -- stream_id: a 32-bit unsigned integer field type. - -You can modify this default trace packet header field type after the -trace class is created with bt_ctf_trace_set_packet_header_type(). +class is an empty structure field type. You can modify this default +trace packet header field type after the trace class is created with +bt_ctf_trace_get_packet_header_type() and +bt_ctf_trace_set_packet_header_type(). The created trace class has the following initial properties: - Name: none. You can set a name with bt_ctf_trace_set_name(). -- Default byte order: #BT_CTF_BYTE_ORDER_NATIVE. You - can set a default byte order with bt_ctf_trace_set_native_byte_order(). +- UUID: none. You can set a UUID with + bt_ctf_trace_set_uuid(). +- Native byte order: #BT_CTF_BYTE_ORDER_NATIVE. You + can set a native byte order with bt_ctf_trace_set_native_byte_order(). - Note that you \em must set the default byte order if any field type + Note that you \em must set the native byte order if any field type contained in the created trace class, in its stream classes, or in its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE. - Environment: empty. You can add environment entries @@ -235,25 +229,25 @@ extern int bt_ctf_trace_set_name(struct bt_ctf_trace *trace_class, const char *name); /** -@brief Returns the default byte order of the CTF IR trace class +@brief Returns the native byte order of the CTF IR trace class \p trace_class. @param[in] trace_class Trace class of which to get the default byte order. -@returns Default byte order of trace class - \p trace_class, or #BT_CTF_BYTE_ORDER_UNKNOWN - on error. +@returns Native byte order of \p trace_class, + or #BT_CTF_BYTE_ORDER_UNKNOWN on error. @prenotnull{trace_class} @postrefcountsame{trace_class} -@sa bt_ctf_trace_set_name(): Sets the name of a given trace class. +@sa bt_ctf_trace_set_native_byte_order(): Sets the native byte order of + a given trace class. */ -extern enum bt_ctf_byte_order bt_ctf_trace_get_byte_order( +extern enum bt_ctf_byte_order bt_ctf_trace_get_native_byte_order( struct bt_ctf_trace *trace_class); /** -@brief Sets the default byte order of the CTF IR trace class +@brief Sets the native byte order of the CTF IR trace class \p trace_class to \p native_byte_order. \p native_byte_order \em must be one of: @@ -262,24 +256,63 @@ extern enum bt_ctf_byte_order bt_ctf_trace_get_byte_order( - #BT_CTF_BYTE_ORDER_BIG_ENDIAN - #BT_CTF_BYTE_ORDER_NETWORK -@param[in] trace_class Trace class of which to set the default byte +@param[in] trace_class Trace class of which to set the native byte order. -@param[in] native_byte_order Default byte order of the trace class. +@param[in] native_byte_order Native byte order of the trace class. @returns 0 on success, or a negative value on error. @prenotnull{trace_class} -@prenotnull{name} @prehot{trace_class} @pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or #BT_CTF_BYTE_ORDER_NETWORK. @postrefcountsame{trace_class} -@sa bt_ctf_trace_get_name(): Returns the name of a given trace class. +@sa bt_ctf_trace_get_native_byte_order(): Returns the native byte order of a + given trace class. */ extern int bt_ctf_trace_set_native_byte_order(struct bt_ctf_trace *trace_class, enum bt_ctf_byte_order native_byte_order); +/** +@brief Returns the UUID of the CTF IR trace class \p trace_class. + +On success, the return value is an array of 16 bytes. + +@param[in] trace_class Trace class of which to get the UUID. +@returns UUID of trace class \p trace_class, or + \c NULL if \p trace_class has no UUID or on error. + +@prenotnull{trace_class} +@postrefcountsame{trace_class} + +@sa bt_ctf_trace_set_uuid(): Sets the UUID of a given trace class. +*/ +extern const unsigned char *bt_ctf_trace_get_uuid( + struct bt_ctf_trace *trace_class); + +/** +@brief Sets the UUID of the CTF IR trace class \p trace_class to + \p uuid. + +\p uuid \em must be an array of 16 bytes. + +@param[in] trace_class Trace class of which to set the UUID. +@param[in] uuid UUID of the \p trace_class (copied on + success). +@returns 0 on success, or a negative value on error. + +@prenotnull{trace_class} +@prenotnull{uuid} +@prehot{trace_class} +@pre \p uuid is an array of 16 bytes. +@postrefcountsame{trace_class} + +@sa bt_ctf_trace_get_uuid(): Returns the UUID of a given trace class. +*/ +extern int bt_ctf_trace_set_uuid(struct bt_ctf_trace *trace_class, + const unsigned char *uuid); + /** @brief Returns the number of entries contained in the environment of the CTF IR trace class \p trace_class. @@ -779,15 +812,15 @@ It is guaranteed that a static trace class will never contain new streams, stream classes, or clock classes. A static class is always frozen. -This function returns \c true if bt_ctf_trace_set_is_static() was +This function returns #BT_TRUE if bt_ctf_trace_set_is_static() was previously called on it. @param[in] trace_class Trace class to check. -@returns \c true if \p trace_class is static, +@returns #BT_TRUE if \p trace_class is static, @sa bt_ctf_trace_set_is_static(): Makes a trace class static. */ -extern bool bt_ctf_trace_is_static(struct bt_ctf_trace *trace_class); +extern bt_bool bt_ctf_trace_is_static(struct bt_ctf_trace *trace_class); /** @brief Makes the CTF IR trace class \p trace_class static. @@ -838,18 +871,6 @@ extern int bt_ctf_trace_visit(struct bt_ctf_trace *trace_class, /** @} */ -/* - * bt_ctf_trace_get_metadata_string: get metadata string. - * - * Get the trace's TSDL metadata. The caller assumes the ownership of the - * returned string. - * - * @param trace Trace instance. - * - * Returns the metadata string on success, NULL on error. - */ -extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace); - #ifdef __cplusplus } #endif