Python bindings docs: clarify add_event_class comments
[babeltrace.git] / bindings / python / babeltrace.i.in
index e0f3253c8408a19de96f534c72946a57b0d496f2..b1c4f50bea3ea54454c4ed12aa1cadeb1bb67288 100644 (file)
@@ -114,6 +114,10 @@ const char *_bt_python_ctf_event_class_get_field_name(
                struct bt_ctf_event_class *event_class, size_t index);
 struct bt_ctf_field_type *_bt_python_ctf_event_class_get_field_type(
                struct bt_ctf_event_class *event_class, size_t index);
+int _bt_python_ctf_clock_get_uuid_index(struct bt_ctf_clock *clock,
+               size_t index, unsigned char *OUTPUT);
+int _bt_python_ctf_clock_set_uuid_index(struct bt_ctf_clock *clock,
+               size_t index, unsigned char value);
 
 /* =================================================================
                CONTEXT.H, CONTEXT-INTERNAL.H
@@ -820,7 +824,7 @@ class Event(collections.Mapping):
        def _field_list_with_scope(self, scope):
                fields = []
                scope_ptr = _bt_ctf_get_top_level_scope(self._e, scope)
-               
+
                # Returns a list [list_ptr, count]. If list_ptr is NULL, SWIG will only
                # provide the "count" return value
                count = 0
@@ -1532,11 +1536,15 @@ void bt_ctf_event_put(struct bt_ctf_event *event);
 %rename("_bt_ctf_stream_class_get_event_class_count") bt_ctf_stream_class_get_event_class_count(struct bt_ctf_stream_class *stream_class);
 %rename("_bt_ctf_stream_class_get_event_class") bt_ctf_stream_class_get_event_class(struct bt_ctf_stream_class *stream_class, size_t index);
 %rename("_bt_ctf_stream_class_get_event_class_by_name") bt_ctf_stream_class_get_event_class_by_name(struct bt_ctf_stream_class *stream_class, const char *name);
+%rename("_bt_ctf_stream_class_get_packet_context_type") bt_ctf_stream_class_get_packet_context_type(struct bt_ctf_stream_class *stream_class);
+%rename("_bt_ctf_stream_class_set_packet_context_type") bt_ctf_stream_class_set_packet_context_type(struct bt_ctf_stream_class *stream_class, struct bt_ctf_field_type *packet_context_type);
 %rename("_bt_ctf_stream_class_get") bt_ctf_stream_class_get(struct bt_ctf_stream_class *stream_class);
 %rename("_bt_ctf_stream_class_put") bt_ctf_stream_class_put(struct bt_ctf_stream_class *stream_class);
 %rename("_bt_ctf_stream_get_discarded_events_count") bt_ctf_stream_get_discarded_events_count(struct bt_ctf_stream *stream, uint64_t *count);
 %rename("_bt_ctf_stream_append_discarded_events") bt_ctf_stream_append_discarded_events(struct bt_ctf_stream *stream, uint64_t event_count);
 %rename("_bt_ctf_stream_append_event") bt_ctf_stream_append_event(struct bt_ctf_stream *stream, struct bt_ctf_event *event);
+%rename("_bt_ctf_stream_get_packet_context") bt_ctf_stream_get_packet_context(struct bt_ctf_stream *stream);
+%rename("_bt_ctf_stream_set_packet_context") bt_ctf_stream_set_packet_context(struct bt_ctf_stream *stream, struct bt_ctf_field *packet_context);
 %rename("_bt_ctf_stream_flush") bt_ctf_stream_flush(struct bt_ctf_stream *stream);
 %rename("_bt_ctf_stream_get") bt_ctf_stream_get(struct bt_ctf_stream *stream);
 %rename("_bt_ctf_stream_put") bt_ctf_stream_put(struct bt_ctf_stream *stream);
@@ -1551,11 +1559,15 @@ int bt_ctf_stream_class_add_event_class(struct bt_ctf_stream_class *stream_class
 int64_t bt_ctf_stream_class_get_event_class_count(struct bt_ctf_stream_class *stream_class);
 struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(struct bt_ctf_stream_class *stream_class, size_t index);
 struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(struct bt_ctf_stream_class *stream_class, const char *name);
+struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type(struct bt_ctf_stream_class *stream_class);
+int bt_ctf_stream_class_set_packet_context_type(struct bt_ctf_stream_class *stream_class, struct bt_ctf_field_type *packet_context_type);
 void bt_ctf_stream_class_get(struct bt_ctf_stream_class *stream_class);
 void bt_ctf_stream_class_put(struct bt_ctf_stream_class *stream_class);
 int bt_ctf_stream_get_discarded_events_count(struct bt_ctf_stream *stream, uint64_t *OUTPUT);
 void bt_ctf_stream_append_discarded_events(struct bt_ctf_stream *stream, uint64_t event_count);
 int bt_ctf_stream_append_event(struct bt_ctf_stream *stream, struct bt_ctf_event *event);
+struct bt_ctf_field *bt_ctf_stream_get_packet_context(struct bt_ctf_stream *stream);
+int bt_ctf_stream_set_packet_context(struct bt_ctf_stream *stream, struct bt_ctf_field *packet_context);
 int bt_ctf_stream_flush(struct bt_ctf_stream *stream);
 void bt_ctf_stream_get(struct bt_ctf_stream *stream);
 void bt_ctf_stream_put(struct bt_ctf_stream *stream);
@@ -1586,6 +1598,7 @@ void bt_ctf_writer_get(struct bt_ctf_writer *writer);
 void bt_ctf_writer_put(struct bt_ctf_writer *writer);
 
 %pythoncode %{
+import uuid
 
 class CTFWriter:
        # Used to compare to -1ULL in error checks
@@ -1731,6 +1744,32 @@ class CTFWriter:
                        if ret < 0:
                                raise ValueError("Could not set the clock's absolute attribute.")
 
+               """
+               Get a clock's UUID (an object of type UUID).
+               """
+               @property
+               def uuid(self):
+                       uuid_list = []
+                       for i in range(16):
+                               ret, value = _bt_python_ctf_clock_get_uuid_index(self._c, i)
+                               if ret < 0:
+                                       raise ValueError("Invalid clock instance")
+                               uuid_list.append(value)
+                       return uuid.UUID(bytes=bytes(uuid_list))
+
+               """
+               Set a clock's UUID (an object of type UUID).
+               """
+               @uuid.setter
+               def uuid(self, uuid):
+                       uuid_bytes = uuid.bytes
+                       if len(uuid_bytes) != 16:
+                               raise ValueError("Invalid UUID provided. UUID length must be 16 bytes")
+                       for i in range(len(uuid_bytes)):
+                               ret = _bt_python_ctf_clock_set_uuid_index(self._c, i, uuid_bytes[i])
+                               if ret < 0:
+                                       raise ValueError("Invalid clock instance")
+
                """
                Get the current time in nanoseconds since the clock's origin (offset and
                offset_s attributes).
@@ -2742,7 +2781,8 @@ class CTFWriter:
                """
                Add an event class to a stream class. New events can be added even after a
                stream has been instantiated and events have been appended. However, a stream
-               will not accept events of a class that has not been registered beforehand.
+               will not accept events of a class that has not been added to the stream
+               class beforehand.
                """
                def add_event_class(self, event_class):
                        if not isinstance(event_class, CTFWriter.EventClass):
@@ -2752,6 +2792,29 @@ class CTFWriter:
                        if ret < 0:
                                raise ValueError("Could not add event class.")
 
+               """
+               Get the StreamClass' packet context type (StructureFieldDeclaration)
+               """
+               @property
+               def packet_context_type(self):
+                       field_type_native = _bt_ctf_stream_class_get_packet_context_type(self._sc)
+                       if field_type_native is None:
+                               raise ValueError("Invalid StreamClass")
+                       field_type = CTFWriter.FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
+                       return field_type
+
+               """
+               Set a StreamClass' packet context type. Must be of type
+               StructureFieldDeclaration.
+               """
+               @packet_context_type.setter
+               def packet_context_type(self, field_type):
+                       if not isinstance(field_type, CTFWriter.StructureFieldDeclaration):
+                               raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
+                       ret = _bt_ctf_stream_class_set_packet_context_type(self._sc, field_type._ft)
+                       if ret < 0:
+                               raise ValueError("Failed to set packet context type.")
+
        class Stream:
                """
                Create a stream of the given class.
@@ -2793,6 +2856,27 @@ class CTFWriter:
                        if ret < 0:
                                raise ValueError("Could not append event to stream.")
 
+               """
+               Get a Stream's packet context field (a StructureField).
+               """
+               @property
+               def packet_context(self):
+                       native_field = _bt_ctf_stream_get_packet_context(self._s)
+                       if native_field is None:
+                               raise ValueError("Invalid Stream.")
+                       return CTFWriter.Field._create_field_from_native_instance(native_field)
+
+               """
+               Set a Stream's packet context field (must be a StructureField).
+               """
+               @packet_context.setter
+               def packet_context(self, field):
+                       if not isinstance(field, CTFWriter.StructureField):
+                               raise TypeError("Argument field must be of type StructureField")
+                       ret = _bt_ctf_stream_set_packet_context(self._s, field._f)
+                       if ret < 0:
+                               raise ValueError("Invalid packet context field.")
+
                """
                The stream's current packet's events will be flushed to disk. Events
                subsequently appended to the stream will be added to a new packet.
This page took 0.036485 seconds and 4 git commands to generate.