X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=29b60980cac2bbb37d9c52058517b27c419ca860;hb=4841ccc167f5f99267a0c129a1e79214b60f553c;hp=03c281bcb21729b6074f3ce73ba7efd03c5e67bc;hpb=ef0c4a15a08fe244291de4ad483e936f1ae60d09;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index 03c281bc..29b60980 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -31,6 +31,7 @@ */ #include +#include #include #ifdef __cplusplus @@ -42,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. * @@ -79,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 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). @@ -91,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). @@ -108,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); @@ -124,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. @@ -154,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_value_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_value * +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_value_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_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. @@ -253,6 +264,28 @@ extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace *trace); 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. * @@ -324,6 +357,8 @@ extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace, * 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