X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fevent.h;h=4c90a2eb5759c6bb2952de67bbe38dbcb03df4c2;hb=de3dd40e6fcad56e227f5fc8a8290fbaa88b4e07;hp=30b790035456eefbd4ffff13a3fe45e09522b7c0;hpb=54fca895efe7eb95563b5ad9ac1355106415f116;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/event.h b/include/babeltrace/ctf-ir/event.h index 30b79003..4c90a2eb 100644 --- a/include/babeltrace/ctf-ir/event.h +++ b/include/babeltrace/ctf-ir/event.h @@ -32,6 +32,7 @@ #include #include +#include #ifdef __cplusplus extern "C" { @@ -91,6 +92,96 @@ extern int64_t bt_ctf_event_class_get_id( extern int bt_ctf_event_class_set_id( struct bt_ctf_event_class *event_class, uint32_t id); +/* + * bt_ctf_event_class_set_attribute: sets an attribute to the event + * class. + * + * Sets an attribute to the event class. The name parameter is copied, + * whereas the value parameter's reference count is incremented + * (if the function succeeds). + * + * If an attribute exists in the event class for the specified name, it + * is replaced by the new value. + * + * Valid attributes and object types are: + * + * - "id": integer object with a value >= 0 + * - "name": string object + * - "loglevel": integer object with a value >= 0 + * - "model.emf.uri": string object + * + * @param event_class Event class. + * @param name Name of the attribute (will be copied). + * @param value Value of the attribute. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_event_class_set_attribute( + struct bt_ctf_event_class *event_class, const char *name, + struct bt_object *value); + +/* + * bt_ctf_event_class_get_attribute_count: get the number of attributes + * in this event class. + * + * Get the event class' attribute count. + * + * @param event_class Event class. + * + * Returns the attribute count, a negative value on error. + */ +extern int bt_ctf_event_class_get_attribute_count( + struct bt_ctf_event_class *event_class); + +/* + * bt_ctf_event_class_get_attribute_name: get attribute name. + * + * Get an attribute's name. The string's ownership is not + * transferred to the caller. The string data is valid as long as + * this event class' attributes are not modified. + * + * @param event_class Event class. + * @param index Index of the attribute. + * + * Returns the attribute's name, NULL on error. + */ +extern const char * +bt_ctf_event_class_get_attribute_name( + struct bt_ctf_event_class *event_class, int index); + +/* + * bt_ctf_event_class_get_attribute_value: get attribute value (an object). + * + * Get an attribute'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 event_class Event class. + * @param index Index of the attribute. + * + * Returns the attribute's object value, NULL on error. + */ +extern struct bt_object * +bt_ctf_event_class_get_attribute_value(struct bt_ctf_event_class *event_class, + int index); + +/* + * bt_ctf_event_class_get_attribute_value_by_name: get attribute + * value (an object) by name. + * + * Get an attribute's value (an object) by its name. The returned object's + * reference count is incremented. When done with the object, the caller + * must call bt_object_put() on it. + * + * @param event_class Event class. + * @param name Attribute's name + * + * Returns the attribute's object value, NULL on error. + */ +extern struct bt_object * +bt_ctf_event_class_get_attribute_value_by_name( + struct bt_ctf_event_class *event_class, const char *name); + /* * bt_ctf_event_class_get_stream_class: Get an event class' stream class. * @@ -102,6 +193,32 @@ extern int bt_ctf_event_class_set_id( extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class( struct bt_ctf_event_class *event_class); +/* + * bt_ctf_event_class_get_payload_type: get an event class' payload. + * + * Get an event class' payload type. + * + * @param event_class Event class. + * + * Returns the event class' payload, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_event_class_get_payload_type( + struct bt_ctf_event_class *event_class); + +/* + * bt_ctf_event_class_set_payload_type: set an event class' payload. + * + * Set an event class' payload type. + * + * @param event_class Event class. + * @param payload The payload's type (must be a structure). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_event_class_set_payload_type( + struct bt_ctf_event_class *event_class, + struct bt_ctf_field_type *payload); + /* * bt_ctf_event_class_add_field: add a field to an event class. * @@ -114,6 +231,8 @@ extern struct bt_ctf_stream_class *bt_ctf_event_class_get_stream_class( * @param name Name of the new field. * * Returns 0 on success, a negative value on error. + * + * Note: Returns an error if the payload is not a structure. */ extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class, struct bt_ctf_field_type *type, @@ -125,6 +244,8 @@ extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class, * @param event_class Event class. * * Returns the event class' field count, a negative value on error. + * + * Note: Returns an error if the payload is not a structure. */ extern int bt_ctf_event_class_get_field_count( struct bt_ctf_event_class *event_class); @@ -140,6 +261,8 @@ extern int bt_ctf_event_class_get_field_count( * @param index Index of field. * * Returns 0 on success, a negative error on value. + * + * Note: Returns an error if the payload is not a structure. */ extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class, const char **field_name, struct bt_ctf_field_type **field_type, @@ -152,6 +275,8 @@ extern int bt_ctf_event_class_get_field(struct bt_ctf_event_class *event_class, * @param name Name of the field. * * Returns a field type on success, NULL on error. + * + * Note: Returns an error if the payload is not a structure. */ extern struct bt_ctf_field_type *bt_ctf_event_class_get_field_by_name( struct bt_ctf_event_class *event_class, const char *name); @@ -182,6 +307,8 @@ extern int bt_ctf_event_class_set_context_type( * bt_ctf_event_class_get and bt_ctf_event_class_put: increment and decrement * the event class' reference count. * + * You may also use bt_ctf_get() and bt_ctf_put() with event class objects. + * * These functions ensure that the event class 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 @@ -222,6 +349,16 @@ extern struct bt_ctf_event *bt_ctf_event_create( extern struct bt_ctf_event_class *bt_ctf_event_get_class( struct bt_ctf_event *event); +/* + * bt_ctf_event_get_stream: get an event's associated stream. + * + * @param event Event. + * + * Returns the event's associated stream, NULL on error. + */ +extern struct bt_ctf_stream *bt_ctf_event_get_stream( + struct bt_ctf_event *event); + /* * bt_ctf_event_get_clock: get an event's associated clock. * @@ -232,6 +369,27 @@ extern struct bt_ctf_event_class *bt_ctf_event_get_class( extern struct bt_ctf_clock *bt_ctf_event_get_clock( struct bt_ctf_event *event); +/* + * bt_ctf_event_get_payload_field: get an event's payload. + * + * @param event Event instance. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_event_get_payload_field( + struct bt_ctf_event *event); + +/* + * bt_ctf_event_set_payload_field: set an event's payload. + * + * @param event Event instance. + * @param payload Field instance (must be a structure). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event, + struct bt_ctf_field *payload); + /* * bt_ctf_event_get_payload: get an event's field. * @@ -239,9 +397,13 @@ extern struct bt_ctf_clock *bt_ctf_event_get_clock( * returned value. * * @param event Event instance. - * @param name Event field name. + * @param name Event field name, see notes. * * Returns a field instance on success, NULL on error. + * + * Note: Passing a name will cause the function to perform a look-up by + * name assuming the event's payload is a structure. This will return + * the raw payload instance if name is NULL. */ extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event, const char *name); @@ -254,10 +416,14 @@ extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event, * bt_ctf_field_put() must be called on the returned value. * * @param event Event instance. - * @param name Event field name. + * @param name Event field name, see notes. * @param value Instance of a field whose type corresponds to the event's field. * * Returns 0 on success, a negative value on error. + * + * Note: The function will return an error if a name is provided and the payload + * type is not a structure. If name is NULL, the payload field will be set + * directly and must match the event class' payload's type. */ extern int bt_ctf_event_set_payload(struct bt_ctf_event *event, const char *name, @@ -274,6 +440,8 @@ extern int bt_ctf_event_set_payload(struct bt_ctf_event *event, * @param index Index of field. * * Returns the event's field, NULL on error. + * + * Note: Will return an error if the payload's type is not a structure. */ extern struct bt_ctf_field *bt_ctf_event_get_payload_by_index( struct bt_ctf_event *event, int index); @@ -329,10 +497,25 @@ extern struct bt_ctf_field *bt_ctf_event_get_event_context( extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event, struct bt_ctf_field *context); +/* + * bt_ctf_event_copy: Deep-copy an event. + * + * Get an event's deep copy. + * + * On success, the returned copy has its reference count set to 1. + * + * @param event Event to copy. + * + * Returns the deep-copied event on success, NULL on error. + */ +extern struct bt_ctf_event *bt_ctf_event_copy(struct bt_ctf_event *event); + /* * bt_ctf_event_get and bt_ctf_event_put: increment and decrement * the event's reference count. * + * You may also use bt_ctf_get() and bt_ctf_put() with event objects. + * * These functions ensure that the event 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