X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=953810342b10896b4c85364bb8d1e589be8ce6f0;hb=a7c415355d7e6def65028b131c8cb2d5586cd2a0;hp=cf14dcffdd9ec54fb20eae26c7f79f1338c8dcda;hpb=e6fa216001c0b8a91868c1982bae990c1304965c;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index cf14dcff..95381034 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" { @@ -41,12 +43,6 @@ struct bt_ctf_stream; struct bt_ctf_stream_class; struct bt_ctf_clock; -enum bt_environment_field_type { - BT_ENVIRONMENT_FIELD_TYPE_UNKNOWN = -1, - BT_ENVIRONMENT_FIELD_TYPE_STRING = 0, - BT_ENVIRONMENT_FIELD_TYPE_INTEGER = 1, -}; - /* * bt_ctf_trace_create: create a trace instance. * @@ -78,11 +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 a string environment field to the + * bt_ctf_trace_set_environment_field: sets an environment field to the * trace. * - * Add a string environment field to the trace. The name and value parameters - * are copied. + * 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). + * + * 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 object or a + * string 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_object *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). @@ -90,16 +111,17 @@ 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_add_environment_field_integer: add an integer environment + * bt_ctf_trace_set_environment_field_integer: sets an integer environment * field to the trace. * - * Add an integer environment field to the trace. The name parameter is - * copied. + * 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). @@ -107,7 +129,7 @@ extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace, * * Returns 0 on success, a negative value on error. */ -extern int bt_ctf_trace_add_environment_field_integer( +extern int bt_ctf_trace_set_environment_field_integer( struct bt_ctf_trace *trace, const char *name, int64_t value); @@ -123,25 +145,12 @@ extern int bt_ctf_trace_add_environment_field_integer( extern int bt_ctf_trace_get_environment_field_count( struct bt_ctf_trace *trace); -/* - * bt_ctf_trace_get_environment_field_type: get environment field type. - * - * Get an environment field's type. - * - * @param trace Trace instance. - * @param index Index of the environment field. - * - * Returns the environment field count, a negative value on error. - */ -extern enum bt_environment_field_type -bt_ctf_trace_get_environment_field_type(struct bt_ctf_trace *trace, - int index); - /* * 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. + * 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. @@ -153,35 +162,38 @@ bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace *trace, int index); /* - * bt_ctf_trace_get_environment_field_value_string: get environment field - * string value. + * bt_ctf_trace_get_environment_field_value: get environment + * field value (an object). * - * Get an environment field's string value. The string's ownership is not - * transferred to the caller. + * 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_object_put() on it. * * @param trace Trace instance. * @param index Index of the environment field. * - * Returns the environment field's string value, NULL on error. + * Returns the environment field's object value, NULL on error. */ -extern const char * -bt_ctf_trace_get_environment_field_value_string(struct bt_ctf_trace *trace, +extern struct bt_object * +bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace *trace, int index); /* - * bt_ctf_trace_get_environment_field_value_integer: get environment field - * integer value. + * bt_ctf_trace_get_environment_field_value_by_name: get environment + * field value (an object) by name. * - * Get an environment field's integer value. + * 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_object_put() on it. * * @param trace Trace instance. - * @param index Index of the environment field. + * @param name Environment field's name * - * Returns the environment field's integer value, a negative value on error. + * Returns the environment field's object value, NULL on error. */ -extern int -bt_ctf_trace_get_environment_field_value_integer(struct bt_ctf_trace *trace, - int index, int64_t *value); +extern struct bt_object * +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. @@ -199,7 +211,7 @@ extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace, /* * bt_ctf_trace_get_clock_count: get the number of clocks - * associated to the trace. + * associated with the trace. * * @param trace Trace instance. * @@ -218,6 +230,51 @@ extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace); 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_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. * @@ -231,7 +288,19 @@ extern struct bt_ctf_clock *bt_ctf_trace_get_clock( 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. + * + * 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. *