X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=84b9b7a92258027db94db571b2891a5aab0d9bb5;hb=56e18c4ce186892c36d7f2cb5078087425e60134;hp=ba8a5fdf7a374b7e3b85613fc2f0023a5e91caea;hpb=7f800dc7c2a13dc895a4c609150c231b6745317c;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index ba8a5fdf..84b9b7a9 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -1,372 +1,2 @@ -#ifndef BABELTRACE_CTF_IR_TRACE_H -#define BABELTRACE_CTF_IR_TRACE_H - -/* - * BabelTrace - CTF IR: Trace - * - * Copyright 2014 Jérémie Galarneau - * - * Author: Jérémie Galarneau - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - * - * The Common Trace Format (CTF) Specification is available at - * http://www.efficios.com/ctf - */ - -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -struct bt_ctf_trace; -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. - * - * 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. - */ -extern struct bt_ctf_trace *bt_ctf_trace_create(void); - -/* - * bt_ctf_trace_create_stream: create a stream instance. - * - * Allocate a new stream instance and register it to the trace. The creation of - * a stream sets its reference count to 1. - * - * @param trace Trace instance. - * @param stream_class Stream class to instantiate. - * - * Returns a new stream on success, NULL on error. - */ -extern struct bt_ctf_stream *bt_ctf_trace_create_stream( - struct bt_ctf_trace *trace, - struct bt_ctf_stream_class *stream_class); - -/* - * 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). - * - * 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). - * @param value Value of the environment field (will be copied). - * - * Returns 0 on success, a negative value on error. - */ -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_object_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_object * -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_object_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_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. - * - * Add a clock to the trace. Clocks assigned to stream classes must be - * added to the trace beforehand. - * - * @param trace Trace instance. - * @param clock Clock to add to the trace. - * - * Returns 0 on success, a negative value on error. - */ -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_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. - * - * 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); - -/* - * 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. - * - * @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. - * - * 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 - * destroy a trace. - * - * When the trace's reference count is decremented to 0 by a - * bt_ctf_trace_put, the trace is freed. - * - * @param trace Trace instance. - */ -extern void bt_ctf_trace_get(struct bt_ctf_trace *trace); -extern void bt_ctf_trace_put(struct bt_ctf_trace *trace); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE_CTF_IR_TRACE_H */ +/* Pre-2.0 CTF writer backward compatibility */ +#include