bindings/python/babeltrace.i.in

   1 /*
   2  * babeltrace.i.in
   3  *
   4  * Babeltrace Python Module interface file
   5  *
   6  * Copyright 2012 EfficiOS Inc.
   7  *
   8  * Author: Danny Serres <danny.serres@efficios.com>
   9  *
  10  * Permission is hereby granted, free of charge, to any person obtaining a copy
  11  * of this software and associated documentation files (the "Software"), to deal
  12  * in the Software without restriction, including without limitation the rights
  13  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  14  * copies of the Software, and to permit persons to whom the Software is
  15  * furnished to do so, subject to the following conditions:
  16  *
  17  * The above copyright notice and this permission notice shall be included in
  18  * all copies or substantial portions of the Software.
  19  */
  20
  21
  22 %define DOCSTRING
  23 "BABELTRACE_VERSION_STR
  24
  25 Babeltrace  is a trace viewer and converter reading and writing the
  26 Common Trace Format (CTF). Its main use is to pretty-print CTF
  27 traces into a human-readable text output.
  28
  29 To use this module, the first step is to create a Context and add a
  30 trace to it."
  31 %enddef
  32
  33 %module(docstring=DOCSTRING) babeltrace
  34
  35 %include "typemaps.i"
  36 %{
  37 #define SWIG_FILE_WITH_INIT
  38 #include <babeltrace/babeltrace.h>
  39 #include <babeltrace/babeltrace-internal.h>
  40 #include <babeltrace/trace-handle.h>
  41 #include <babeltrace/trace-handle-internal.h>
  42 #include <babeltrace/context.h>
  43 #include <babeltrace/context-internal.h>
  44 #include <babeltrace/iterator.h>
  45 #include <babeltrace/iterator-internal.h>
  46 #include <babeltrace/format.h>
  47 #include <babeltrace/list.h>
  48 #include <babeltrace/types.h>
  49 #include <babeltrace/ctf/iterator.h>
  50 #include "python-complements.h"
  51 %}
  52
  53 typedef unsigned long long uint64_t;
  54 typedef long long int64_t;
  55 typedef int bt_intern_str;
  56
  57 /* =================================================================
  58                 PYTHON-COMPLEMENTS.H
  59                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  60 */
  61
  62 FILE *_bt_file_open(char *file_path, char *mode);
  63 void _bt_file_close(FILE *fp);
  64 struct bt_definition **_bt_python_field_listcaller(
  65                 const struct bt_ctf_event *ctf_event,
  66                 const struct bt_definition *scope,
  67                 unsigned int *OUTPUT);
  68 struct bt_definition *_bt_python_field_one_from_list(
  69                 struct bt_definition **list, int index);
  70 struct bt_ctf_event_decl **_bt_python_event_decl_listcaller(
  71                 int handle_id,
  72                 struct bt_context *ctx,
  73                 unsigned int *OUTPUT);
  74 struct bt_ctf_event_decl *_bt_python_decl_one_from_list(
  75                 struct bt_ctf_event_decl **list, int index);
  76 struct bt_ctf_field_decl **_by_python_field_decl_listcaller(
  77                 struct bt_ctf_event_decl *event_decl,
  78                 enum bt_ctf_scope scope,
  79                 unsigned int *OUTPUT);
  80 struct bt_ctf_field_decl *_bt_python_field_decl_one_from_list(
  81                 struct bt_ctf_field_decl **list, int index);
  82 struct definition_array *_bt_python_get_array_from_def(
  83                 struct bt_definition *field);
  84 struct definition_sequence *_bt_python_get_sequence_from_def(
  85                 struct bt_definition *field);
  86
  87 /* =================================================================
  88                 CONTEXT.H, CONTEXT-INTERNAL.H
  89                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  90 */
  91
  92 %rename("_bt_context_create") bt_context_create(void);
  93 %rename("_bt_context_add_trace") bt_context_add_trace(
  94                 struct bt_context *ctx, const char *path, const char *format,
  95                 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
  96                 struct bt_mmap_stream_list *stream_list, FILE *metadata);
  97 %rename("_bt_context_remove_trace") bt_context_remove_trace(
  98                 struct bt_context *ctx, int trace_id);
  99 %rename("_bt_context_get") bt_context_get(struct bt_context *ctx);
 100 %rename("_bt_context_put") bt_context_put(struct bt_context *ctx);
 101 %rename("_bt_ctf_event_get_context") bt_ctf_event_get_context(
 102                 const struct bt_ctf_event *event);
 103
 104 struct bt_context *bt_context_create(void);
 105 int bt_context_add_trace(struct bt_context *ctx, const char *path, const char *format,
 106                 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
 107                 struct bt_mmap_stream_list *stream_list, FILE *metadata);
 108 void bt_context_remove_trace(struct bt_context *ctx, int trace_id);
 109 void bt_context_get(struct bt_context *ctx);
 110 void bt_context_put(struct bt_context *ctx);
 111 struct bt_context *bt_ctf_event_get_context(const struct bt_ctf_event *event);
 112
 113 // class Context to prevent direct access to struct bt_context
 114 %pythoncode%{
 115 class Context:
 116         """
 117         The context represents the object in which a trace_collection is
 118         open. As long as this structure is allocated, the trace_collection
 119         is open and the traces it contains can be read and seeked by the
 120         iterators and callbacks.
 121         """
 122
 123         def __init__(self):
 124                 self._c = _bt_context_create()
 125
 126         def __del__(self):
 127                 _bt_context_put(self._c)
 128
 129         def add_trace(self, path, format_str,
 130                         packet_seek=None, stream_list=None, metadata=None):
 131                 """
 132                 Add a trace by path to the context.
 133
 134                 Open a trace.
 135
 136                 path is the path to the trace, it is not recursive.
 137                 If "path" is None, stream_list is used instead as a list
 138                 of mmap streams to open for the trace.
 139
 140                 format is a string containing the format name in which the trace was
 141                 produced.
 142
 143                 packet_seek is not implemented for Python.  Should be left None to
 144                 use the default packet_seek handler provided by the trace format.
 145
 146                 stream_list is a linked list of streams, it is used to open a trace
 147                 where the trace data is located in memory mapped areas instead of
 148                 trace files, this argument should be None when path is not None.
 149
 150                 The metadata parameter acts as a metadata override when not None,
 151                 otherwise the format handles the metadata opening.
 152
 153                 Return: the corresponding TraceHandle on success or None on error.
 154                 """
 155                 if metadata is not None:
 156                         metadata = metadata._file
 157
 158                 ret = _bt_context_add_trace(self._c, path, format_str, packet_seek,
 159                         stream_list, metadata)
 160                 if ret < 0:
 161                         return None
 162
 163                 th = TraceHandle.__new__(TraceHandle)
 164                 th._id = ret
 165                 return th
 166
 167         def add_traces_recursive(self, path, format_str):
 168                 """
 169                 Open a trace recursively.
 170
 171                 Find each trace present in the subdirectory starting from the given
 172                 path, and add them to the context.
 173
 174                 Return a dict of TraceHandle instances (the full path is the key).
 175                 Return None on error.
 176                 """
 177
 178                 import os
 179
 180                 trace_handles = {}
 181
 182                 noTrace = True
 183                 error = False
 184
 185                 for fullpath, dirs, files in os.walk(path):
 186                         if "metadata" in files:
 187                                 trace_handle = self.add_trace(fullpath, format_str)
 188                                 if trace_handle is None:
 189                                         error = True
 190                                         continue
 191
 192                                 trace_handles[fullpath] = trace_handle
 193                                 noTrace = False
 194
 195                 if noTrace and error:
 196                         return None
 197                 return trace_handles
 198
 199         def remove_trace(self, trace_handle):
 200                 """
 201                 Remove a trace from the context.
 202                 Effectively closing the trace.
 203                 """
 204                 try:
 205                         _bt_context_remove_trace(self._c, trace_handle._id)
 206                 except AttributeError:
 207                         raise TypeError("in remove_trace, "
 208                                 "argument 2 must be a TraceHandle instance")
 209 %}
 210
 211
 212
 213 /* =================================================================
 214                 FORMAT.H, REGISTRY
 215                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 216 */
 217
 218 %rename("lookup_format") bt_lookup_format(bt_intern_str qname);
 219 %rename("_bt_print_format_list") bt_fprintf_format_list(FILE *fp);
 220 %rename("register_format") bt_register_format(struct format *format);
 221 %rename("unregister_format") bt_unregister_format(struct bt_format *format);
 222
 223 extern struct format *bt_lookup_format(bt_intern_str qname);
 224 extern void bt_fprintf_format_list(FILE *fp);
 225 extern int bt_register_format(struct bt_format *format);
 226 extern void bt_unregister_format(struct bt_format *format);
 227
 228 %pythoncode %{
 229
 230 def print_format_list(babeltrace_file):
 231         """
 232         Print a list of available formats to file.
 233
 234         babeltrace_file must be a File instance opened in write mode.
 235         """
 236         try:
 237                 if babeltrace_file._file is not None:
 238                         _bt_print_format_list(babeltrace_file._file)
 239         except AttributeError:
 240                 raise TypeError("in print_format_list, "
 241                         "argument 1 must be a File instance")
 242
 243 %}
 244
 245
 246 /* =================================================================
 247                 ITERATOR.H, ITERATOR-INTERNAL.H
 248                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 249 */
 250
 251 %rename("_bt_iter_create") bt_iter_create(struct bt_context *ctx,
 252                 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
 253 %rename("_bt_iter_destroy") bt_iter_destroy(struct bt_iter *iter);
 254 %rename("_bt_iter_next") bt_iter_next(struct bt_iter *iter);
 255 %rename("_bt_iter_get_pos") bt_iter_get_pos(struct bt_iter *iter);
 256 %rename("_bt_iter_free_pos") bt_iter_free_pos(struct bt_iter_pos *pos);
 257 %rename("_bt_iter_set_pos") bt_iter_set_pos(struct bt_iter *iter,
 258                 const struct bt_iter_pos *pos);
 259 %rename("_bt_iter_create_time_pos") bt_iter_create_time_pos(struct bt_iter *iter,
 260                 uint64_t timestamp);
 261
 262 struct bt_iter *bt_iter_create(struct bt_context *ctx,
 263                 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
 264 void bt_iter_destroy(struct bt_iter *iter);
 265 int bt_iter_next(struct bt_iter *iter);
 266 struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
 267 void bt_iter_free_pos(struct bt_iter_pos *pos);
 268 int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
 269 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter, uint64_t timestamp);
 270
 271 %rename("_bt_iter_pos") bt_iter_pos;
 272 %rename("SEEK_TIME") BT_SEEK_TIME;
 273 %rename("SEEK_RESTORE") BT_SEEK_RESTORE;
 274 %rename("SEEK_CUR") BT_SEEK_CUR;
 275 %rename("SEEK_BEGIN") BT_SEEK_BEGIN;
 276 %rename("SEEK_LAST") BT_SEEK_LAST;
 277
 278 // This struct is taken from iterator.h
 279 // All changes to the struct must also be made here
 280 struct bt_iter_pos {
 281         enum {
 282                 BT_SEEK_TIME,           /* uses u.seek_time */
 283                 BT_SEEK_RESTORE,        /* uses u.restore */
 284                 BT_SEEK_CUR,
 285                 BT_SEEK_BEGIN,
 286                 BT_SEEK_LAST
 287         } type;
 288         union {
 289                 uint64_t seek_time;
 290                 struct bt_saved_pos *restore;
 291         } u;
 292 };
 293
 294
 295 %pythoncode%{
 296
 297 class IterPos:
 298         """This class represents the position where to set an iterator."""
 299
 300         __can_access = False
 301
 302         def __init__(self, seek_type, seek_time = None):
 303                 """
 304                 seek_type represents the type of seek to use.
 305                 seek_time is the timestamp to seek to when using SEEK_TIME, it
 306                 is expressed in nanoseconds
 307                 Only use SEEK_RESTORE on IterPos obtained from the get_pos function
 308                 in Iter class.
 309                 """
 310
 311                 self._pos = _bt_iter_pos()
 312                 self._pos.type = seek_type
 313                 if seek_time and seek_type == SEEK_TIME:
 314                         self._pos.u.seek_time = seek_time
 315                 self.__can_access = True
 316
 317         def __del__(self):
 318                 if not self.__can_access:
 319                         _bt_iter_free_pos(self._pos)
 320
 321         def _get_type(self):
 322                 if not __can_access:
 323                         raise AttributeError("seek_type is not available")
 324                 return self._pos.type
 325
 326         def _set_type(self, seek_type):
 327                 if not __can_access:
 328                         raise AttributeError("seek_type is not available")
 329                 self._pos.type = seek_type
 330
 331         def _get_time(self):
 332                 if not __can_access:
 333                         raise AttributeError("seek_time is not available")
 334
 335                 elif self._pos.type is not SEEK_TIME:
 336                         raise TypeError("seek_type is not SEEK_TIME")
 337
 338                 return self._pos.u.seek_time
 339
 340         def _set_time(self, time):
 341                 if not __can_access:
 342                         raise AttributeError("seek_time is not available")
 343
 344                 elif self._pos.type is not SEEK_TIME:
 345                         raise TypeError("seek_type is not SEEK_TIME")
 346
 347                 self._pos.u.seek_time = time
 348
 349         def _get_pos(self):
 350                 return self._pos
 351
 352
 353         seek_type = property(_get_type, _set_type)
 354         seek_time = property(_get_time, _set_time)
 355
 356
 357 class Iterator:
 358
 359         __with_init = False
 360
 361         def __init__(self, context, begin_pos = None, end_pos = None, _no_init = None):
 362                 """
 363                 Allocate a trace collection iterator.
 364
 365                 begin_pos and end_pos are optional parameters to specify the
 366                 position at which the trace collection should be seeked upon
 367                 iterator creation, and the position  at which iteration will
 368                 start returning "EOF".
 369
 370                 By default, if begin_pos is None, a BT_SEEK_CUR is performed at
 371                 creation. By default, if end_pos is None, a BT_SEEK_END (end of
 372                 trace) is the EOF criterion.
 373                 """
 374                 if _no_init is None:
 375                         if begin_pos is None:
 376                                 bp = None
 377                         else:
 378                                 try:
 379                                         bp = begin_pos._pos
 380                                 except AttributeError:
 381                                         raise TypeError("in __init__, "
 382                                                 "argument 3 must be a IterPos instance")
 383
 384                         if end_pos is None:
 385                                 ep = None
 386                         else:
 387                                 try:
 388                                         ep = end_pos._pos
 389                                 except AttributeError:
 390                                         raise TypeError("in __init__, "
 391                                                 "argument 4 must be a IterPos instance")
 392
 393                         try:
 394                                 self._bi = _bt_iter_create(context._c, bp, ep)
 395                         except AttributeError:
 396                                 raise TypeError("in __init__, "
 397                                         "argument 2 must be a Context instance")
 398
 399                         self.__with_init = True
 400
 401                 else:
 402                         self._bi = _no_init
 403
 404         def __del__(self):
 405                 if self.__with_init:
 406                         _bt_iter_destroy(self._bi)
 407
 408         def next(self):
 409                 """
 410                 Move trace collection position to the next event.
 411                 Returns 0 on success, a negative value on error.
 412                 """
 413                 return _bt_iter_next(self._bi)
 414
 415         def get_pos(self):
 416                 """Return a IterPos class of the current iterator position."""
 417                 ret = IterPos(0)
 418                 ret.__can_access = False
 419                 ret._pos = _bt_iter_get_pos(self._bi)
 420                 return ret
 421
 422         def set_pos(self, pos):
 423                 """
 424                 Move the iterator to a given position.
 425
 426                 On error, the stream_heap is reinitialized and returned empty.
 427                 Return 0 for success.
 428                 Return EOF if the position requested is after the last event of the
 429                 trace collection.
 430                 Return -EINVAL when called with invalid parameter.
 431                 Return -ENOMEM if the stream_heap could not be properly initialized.
 432                 """
 433                 try:
 434                         return _bt_iter_set_pos(self._bi, pos._pos)
 435                 except AttributeError:
 436                         raise TypeError("in set_pos, "
 437                                 "argument 2 must be a IterPos instance")
 438
 439         def create_time_pos(self, timestamp):
 440                 """
 441                 Create a position based on time
 442                 This function allocates and returns a new IterPos to be able to
 443                 restore an iterator position based on a timestamp.
 444                 """
 445
 446                 if timestamp < 0:
 447                         raise TypeError("timestamp must be an unsigned int")
 448
 449                 ret = IterPos(0)
 450                 ret.__can_access = False
 451                 ret._pos = _bt_iter_create_time_pos(self._bi, timestamp)
 452                 return ret
 453 %}
 454
 455
 456 /* =================================================================
 457                 CLOCK-TYPE.H
 458                 ¯¯¯¯¯¯¯¯¯¯¯¯
 459         *** Enum copied from clock-type.h
 460                 All changes must also be made here
 461 */
 462 %rename("CLOCK_CYCLES") BT_CLOCK_CYCLES;
 463 %rename("CLOCK_REAL") BT_CLOCK_REAL;
 464
 465 enum bt_clock_type {
 466         BT_CLOCK_CYCLES = 0,
 467         BT_CLOCK_REAL
 468 };
 469
 470 /* =================================================================
 471                 TRACE-HANDLE.H, TRACE-HANDLE-INTERNAL.H
 472                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 473 */
 474
 475 %rename("_bt_trace_handle_create") bt_trace_handle_create(struct bt_context *ctx);
 476 %rename("_bt_trace_handle_destroy") bt_trace_handle_destroy(struct bt_trace_handle *bt);
 477 struct bt_trace_handle *bt_trace_handle_create(struct bt_context *ctx);
 478 void bt_trace_handle_destroy(struct bt_trace_handle *bt);
 479
 480 %rename("_bt_trace_handle_get_path") bt_trace_handle_get_path(struct bt_context *ctx,
 481                 int handle_id);
 482 %rename("_bt_trace_handle_get_timestamp_begin") bt_trace_handle_get_timestamp_begin(
 483                 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
 484 %rename("_bt_trace_handle_get_timestamp_end") bt_trace_handle_get_timestamp_end(
 485                 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
 486 const char *bt_trace_handle_get_path(struct bt_context *ctx, int handle_id);
 487 uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, int handle_id,
 488                 enum bt_clock_type type);
 489 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, int handle_id,
 490                 enum bt_clock_type type);
 491
 492 %rename("_bt_ctf_event_get_handle_id") bt_ctf_event_get_handle_id(
 493                 const struct bt_ctf_event *event);
 494 int bt_ctf_event_get_handle_id(const struct bt_ctf_event *event);
 495
 496
 497 %pythoncode%{
 498
 499 class TraceHandle(object):
 500         """
 501         The TraceHandle allows the user to manipulate a trace file directly.
 502         It is a unique identifier representing a trace file.
 503         Do not instantiate.
 504         """
 505
 506         def __init__(self):
 507                 raise NotImplementedError("TraceHandle cannot be instantiated")
 508
 509         def __repr__(self):
 510                 return "Babeltrace TraceHandle: trace_id('{0}')".format(self._id)
 511
 512         def get_id(self):
 513                 """Return the TraceHandle id."""
 514                 return self._id
 515
 516         def get_path(self, context):
 517                 """Return the path of a TraceHandle."""
 518                 try:
 519                         return _bt_trace_handle_get_path(context._c, self._id)
 520                 except AttributeError:
 521                         raise TypeError("in get_path, "
 522                                 "argument 2 must be a Context instance")
 523
 524         def get_timestamp_begin(self, context, clock_type):
 525                 """Return the creation time of the buffers of a trace."""
 526                 try:
 527                         return _bt_trace_handle_get_timestamp_begin(
 528                                 context._c, self._id,clock_type)
 529                 except AttributeError:
 530                         raise TypeError("in get_timestamp_begin, "
 531                                 "argument 2 must be a Context instance")
 532
 533         def get_timestamp_end(self, context, clock_type):
 534                 """Return the destruction timestamp of the buffers of a trace."""
 535                 try:
 536                         return _bt_trace_handle_get_timestamp_end(
 537                                 context._c, self._id, clock_type)
 538                 except AttributeError:
 539                         raise TypeError("in get_timestamp_end, "
 540                                 "argument 2 must be a Context instance")
 541
 542 %}
 543
 544
 545
 546 // =================================================================
 547 //                              CTF
 548 // =================================================================
 549
 550 /* =================================================================
 551                 ITERATOR.H, EVENTS.H
 552                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 553 */
 554
 555 //Iterator
 556 %rename("_bt_ctf_iter_create") bt_ctf_iter_create(struct bt_context *ctx,
 557                 const struct bt_iter_pos *begin_pos,
 558                 const struct bt_iter_pos *end_pos);
 559 %rename("_bt_ctf_get_iter") bt_ctf_get_iter(struct bt_ctf_iter *iter);
 560 %rename("_bt_ctf_iter_destroy") bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
 561 %rename("_bt_ctf_iter_read_event") bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
 562
 563 struct bt_ctf_iter *bt_ctf_iter_create(struct bt_context *ctx,
 564                 const struct bt_iter_pos *begin_pos,
 565                 const struct bt_iter_pos *end_pos);
 566 struct bt_iter *bt_ctf_get_iter(struct bt_ctf_iter *iter);
 567 void bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
 568 struct bt_ctf_event *bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
 569
 570
 571 //Events
 572
 573 %rename("_bt_ctf_get_top_level_scope") bt_ctf_get_top_level_scope(const struct
 574                 bt_ctf_event *event, enum bt_ctf_scope scope);
 575 %rename("_bt_ctf_event_name") bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
 576 %rename("_bt_ctf_get_timestamp") bt_ctf_get_timestamp(
 577                 const struct bt_ctf_event *ctf_event);
 578 %rename("_bt_ctf_get_cycles") bt_ctf_get_cycles(
 579                 const struct bt_ctf_event *ctf_event);
 580
 581 %rename("_bt_ctf_get_field") bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
 582                 const struct bt_definition *scope,      const char *field);
 583 %rename("_bt_ctf_get_index") bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
 584                 const struct bt_definition *field,      unsigned int index);
 585 %rename("_bt_ctf_field_name") bt_ctf_field_name(const struct bt_definition *field);
 586 %rename("_bt_ctf_field_type") bt_ctf_field_type(const struct bt_declaration *field);
 587 %rename("_bt_ctf_get_int_signedness") bt_ctf_get_int_signedness(
 588                 const struct bt_declaration *field);
 589 %rename("_bt_ctf_get_int_base") bt_ctf_get_int_base(const struct bt_declaration *field);
 590 %rename("_bt_ctf_get_int_byte_order") bt_ctf_get_int_byte_order(
 591                 const struct bt_declaration *field);
 592 %rename("_bt_ctf_get_int_len") bt_ctf_get_int_len(const struct bt_declaration *field);
 593 %rename("_bt_ctf_get_enum_int") bt_ctf_get_enum_int(const struct bt_definition *field);
 594 %rename("_bt_ctf_get_enum_str") bt_ctf_get_enum_str(const struct bt_definition *field);
 595 %rename("_bt_ctf_get_encoding") bt_ctf_get_encoding(const struct bt_declaration *field);
 596 %rename("_bt_ctf_get_array_len") bt_ctf_get_array_len(const struct bt_declaration *field);
 597 %rename("_bt_ctf_get_uint64") bt_ctf_get_uint64(const struct bt_definition *field);
 598 %rename("_bt_ctf_get_int64") bt_ctf_get_int64(const struct bt_definition *field);
 599 %rename("_bt_ctf_get_char_array") bt_ctf_get_char_array(const struct bt_definition *field);
 600 %rename("_bt_ctf_get_string") bt_ctf_get_string(const struct bt_definition *field);
 601 %rename("_bt_ctf_get_float") bt_ctf_get_float(const struct bt_definition *field);
 602 %rename("_bt_ctf_get_variant") bt_ctf_get_variant(const struct bt_definition *field);
 603 %rename("_bt_ctf_field_get_error") bt_ctf_field_get_error(void);
 604 %rename("_bt_ctf_get_decl_event_name") bt_ctf_get_decl_event_name(const struct
 605                 bt_ctf_event_decl *event);
 606 %rename("_bt_ctf_get_decl_field_name") bt_ctf_get_decl_field_name(
 607                 const struct bt_ctf_field_decl *field);
 608 %rename("_bt_ctf_get_decl_from_def") bt_ctf_get_decl_from_def(
 609                 const struct bt_definition *field);
 610 %rename("_bt_array_index") bt_array_index(struct definition_array *array, uint64_t i);
 611 %rename("_bt_sequence_len")  bt_sequence_len(struct definition_sequence *sequence);
 612 %rename("_bt_sequence_index") bt_sequence_index(struct definition_sequence *sequence, uint64_t i);
 613 %rename("_bt_ctf_get_struct_field_count") bt_ctf_get_struct_field_count(const struct bt_definition *structure);
 614 %rename("_bt_ctf_get_struct_field_index") bt_ctf_get_struct_field_index(const struct bt_definition *structure, uint64_t i);
 615
 616 const struct bt_definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *ctf_event,
 617                 enum bt_ctf_scope scope);
 618 const char *bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
 619 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *ctf_event);
 620 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *ctf_event);
 621 const struct bt_definition *bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
 622                 const struct bt_definition *scope,
 623                 const char *field);
 624 const struct bt_definition *bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
 625                 const struct bt_definition *field,
 626                 unsigned int index);
 627 const char *bt_ctf_field_name(const struct bt_definition *field);
 628 enum ctf_type_id bt_ctf_field_type(const struct bt_declaration *field);
 629 int bt_ctf_get_int_signedness(const struct bt_declaration *field);
 630 int bt_ctf_get_int_base(const struct bt_declaration *field);
 631 int bt_ctf_get_int_byte_order(const struct bt_declaration *field);
 632 ssize_t bt_ctf_get_int_len(const struct bt_declaration *field);
 633 const struct bt_definition *bt_ctf_get_enum_int(const struct bt_definition *field);
 634 const char *bt_ctf_get_enum_str(const struct bt_definition *field);
 635 enum ctf_string_encoding bt_ctf_get_encoding(const struct bt_declaration *field);
 636 int bt_ctf_get_array_len(const struct bt_declaration *field);
 637 struct bt_definition *bt_array_index(struct definition_array *array, uint64_t i);
 638 uint64_t bt_ctf_get_uint64(const struct bt_definition *field);
 639 int64_t bt_ctf_get_int64(const struct bt_definition *field);
 640 char *bt_ctf_get_char_array(const struct bt_definition *field);
 641 char *bt_ctf_get_string(const struct bt_definition *field);
 642 double bt_ctf_get_float(const struct bt_definition *field);
 643 const struct bt_definition *bt_ctf_get_variant(const struct bt_definition *field);
 644 int bt_ctf_field_get_error(void);
 645 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
 646 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
 647 const struct bt_declaration *bt_ctf_get_decl_from_def(const struct bt_definition *field);
 648 uint64_t bt_sequence_len(struct definition_sequence *sequence);
 649 struct bt_definition *bt_sequence_index(struct definition_sequence *sequence, uint64_t i);
 650 uint64_t bt_ctf_get_struct_field_count(const struct bt_definition *structure);
 651 const struct bt_definition *bt_ctf_get_struct_field_index(const struct bt_definition *structure, uint64_t i);
 652
 653 %pythoncode%{
 654
 655 class CTFStringEncoding:
 656         NONE = 0
 657         UTF8 = 1
 658         ASCII = 2
 659         UNKNOWN = 3
 660
 661 #enum equivalent, accessible constants
 662 #These are taken directly from ctf/events.h
 663 #All changes to enums must also be made here
 664 class CTFTypeId:
 665         UNKNOWN = 0
 666         INTEGER = 1
 667         FLOAT = 2
 668         ENUM = 3
 669         STRING = 4
 670         STRUCT = 5
 671         UNTAGGED_VARIANT = 6
 672         VARIANT = 7
 673         ARRAY = 8
 674         SEQUENCE = 9
 675         NR_CTF_TYPES = 10
 676
 677         def get_type_name(id):
 678                 name = "UNKNOWN"
 679                 constants = [attr for attr in dir(CTFTypeId) if not callable(getattr(CTFTypeId, attr)) and not attr.startswith("__")]
 680                 for attr in constants:
 681                         if getattr(CTFTypeId, attr) == id:
 682                                 name = attr
 683                                 break
 684                 return name
 685
 686 class CTFReader:
 687         class scope:
 688                 TRACE_PACKET_HEADER = 0
 689                 STREAM_PACKET_CONTEXT = 1
 690                 STREAM_EVENT_HEADER = 2
 691                 STREAM_EVENT_CONTEXT = 3
 692                 EVENT_CONTEXT = 4
 693                 EVENT_FIELDS = 5
 694
 695         class string_encoding:
 696                 NONE = 0
 697                 UTF8 = 1
 698                 ASCII = 2
 699                 UNKNOWN = 3
 700
 701         class Iterator(Iterator, object):
 702                 """
 703                 Allocate a CTF trace collection iterator.
 704
 705                 begin_pos and end_pos are optional parameters to specify the
 706                 position at which the trace collection should be seeked upon
 707                 iterator creation, and the position at which iteration will
 708                 start returning "EOF".
 709
 710                 By default, if begin_pos is None, a SEEK_CUR is performed at
 711                 creation. By default, if end_pos is None, a SEEK_END (end of
 712                 trace) is the EOF criterion.
 713
 714                 Only one iterator can be created against a context. If more than one
 715                 iterator is being created for the same context, the second creation
 716                 will return None. The previous iterator must be destroyed before
 717                 creation of the new iterator for this function to succeed.
 718                 """
 719
 720                 def __new__(cls, context, begin_pos = None, end_pos = None):
 721                         # __new__ is used to control the return value
 722                         # as the CTFReader.Iterator class should return None
 723                         # if bt_ctf_iter_create returns NULL
 724
 725                         if begin_pos is None:
 726                                 bp = None
 727                         else:
 728                                 bp = begin_pos._pos
 729                         if end_pos is None:
 730                                 ep = None
 731                         else:
 732                                 ep = end_pos._pos
 733                         try:
 734                                 it = _bt_ctf_iter_create(context._c, bp, ep)
 735                         except AttributeError:
 736                                 raise TypeError("in __init__, "
 737                                         "argument 2 must be a Context instance")
 738                         if it is None:
 739                                 return None
 740
 741                         ret_class = super(CTFReader.Iterator, cls).__new__(cls)
 742                         ret_class._i = it
 743                         return ret_class
 744
 745                 def __init__(self, context, begin_pos = None, end_pos = None):
 746                         Iterator.__init__(self, None, None, None,
 747                                 _bt_ctf_get_iter(self._i))
 748
 749                 def __del__(self):
 750                         _bt_ctf_iter_destroy(self._i)
 751
 752                 def read_event(self):
 753                         """
 754                         Read the iterator's current event data.
 755                         Return current event on success, None on end of trace.
 756                         """
 757                         ret = _bt_ctf_iter_read_event(self._i)
 758                         if ret is None:
 759                                 return ret
 760                         ev = CTFReader.Event.__new__(CTFReader.Event)
 761                         ev._e = ret
 762                         return ev
 763
 764
 765         class Event(object):
 766                 """
 767                 This class represents an event from the trace.
 768                 It is obtained with read_event() from CTFReader.Iterator.
 769                 Do not instantiate.
 770                 """
 771
 772                 def __init__(self):
 773                         raise NotImplementedError("CTFReader.Event cannot be instantiated")
 774
 775                 def get_top_level_scope(self, scope):
 776                         """
 777                         Return a definition of the top-level scope
 778                         Top-level scopes are defined in CTFReader.scope.
 779                         In order to get a field or a field list, the user needs to pass a
 780                         scope as argument, this scope can be a top-level scope or a scope
 781                         relative to an arbitrary field. This function provides the mapping
 782                         between the scope and the actual definition of top-level scopes.
 783                         On error return None.
 784                         """
 785                         evDef = CTFReader.Definition.__new__(CTFReader.Definition)
 786                         evDef._d = _bt_ctf_get_top_level_scope(self._e, scope)
 787                         if evDef._d is None:
 788                                 return None
 789                         return evDef
 790
 791                 def get_name(self):
 792                         """Return the name of the event or None on error."""
 793                         return _bt_ctf_event_name(self._e)
 794
 795                 def get_cycles(self):
 796                         """
 797                         Return the timestamp of the event as written in
 798                         the packet (in cycles) or -1ULL on error.
 799                         """
 800                         return _bt_ctf_get_cycles(self._e)
 801
 802                 def get_timestamp(self):
 803                         """
 804                         Return the timestamp of the event offsetted with the
 805                         system clock source or -1ULL on error.
 806                         """
 807                         return _bt_ctf_get_timestamp(self._e)
 808
 809                 def get_field_with_scope(self, scope, field):
 810                         """
 811                         Return the definition of a specific field.
 812                         Return None on error.
 813                         """
 814                         evDef = CTFReader.Definition.__new__(CTFReader.Definition)
 815                         try:
 816                                 evDef._d = _bt_ctf_get_field(self._e, scope._d, field)
 817                         except AttributeError:
 818                                 raise TypeError("in get_field, argument 2 must be a "
 819                                         "Definition (scope) instance")
 820                         if evDef._d is None:
 821                                 return None
 822                         evDef._s = scope
 823                         return evDef
 824
 825                 def get_field(self, field):
 826                         """
 827                         Return the definition of fields by a name
 828                         Return None on error
 829                         """
 830                         eventScope = self.get_top_level_scope(CTFReader.scope.EVENT_FIELDS)
 831                         streamScope = self.get_top_level_scope(CTFReader.scope.STREAM_EVENT_CONTEXT)
 832                         fields_by_name = []
 833
 834                         if eventScope is not None:
 835                                 evDef = self.get_field_with_scope(eventScope, field)
 836                                 if evDef is not None:
 837                                         fields_by_name.append(evDef)
 838
 839                         if streamScope is not None:
 840                                 evDef = self.get_field_with_scope(streamScope, field)
 841                                 if evDef is not None:
 842                                         fields_by_name.append(evDef);
 843
 844                         if not fields_by_name:
 845                                 return None
 846                         return fields_by_name
 847
 848                 def get_field_list_with_scope(self, scope):
 849                         """
 850                         Return a list of Definitions associated with the scope
 851                         Return None on error.
 852                         """
 853                         try:
 854                                 field_lc, count = _bt_python_field_listcaller(self._e, scope._d)
 855                         except AttributeError:
 856                                 raise TypeError("in get_field_list, argument 2 must be a "
 857                                         "Definition (scope) instance")
 858
 859                         if field_lc is None:
 860                                 return None
 861
 862                         def_list = []
 863                         for i in range(count):
 864                                 tmp = CTFReader.Definition.__new__(CTFReader.Definition)
 865                                 tmp._d = _bt_python_field_one_from_list(field_lc, i)
 866                                 tmp._s = scope
 867                                 def_list.append(tmp)
 868
 869                         return def_list
 870
 871                 def get_field_list(self):
 872                         """Return a list of Definitions or None on error."""
 873                         eventScope = self.get_top_level_scope(CTFReader.scope.EVENT_FIELDS)
 874                         streamScope = self.get_top_level_scope(CTFReader.scope.STREAM_EVENT_CONTEXT)
 875
 876                         def_list = []
 877                         if eventScope is not None:
 878                                 event_field_list = self.get_field_list_with_scope(eventScope)
 879                                 if event_field_list is not None:
 880                                         def_list = event_field_list
 881
 882                         if streamScope is not None:
 883                                 event_field_list = self.get_field_list_with_scope(streamScope)
 884                                 if event_field_list is not None:
 885                                         def_list.extend(event_field_list)
 886
 887                         if not def_list:
 888                                 return None
 889                         return def_list
 890
 891                 def get_index(self, field, index):
 892                         """
 893                         If the field is an array or a sequence, return the element
 894                         at position index, otherwise return None
 895                         """
 896                         evDef = CTFReader.Definition.__new__(CTFReader.Definition)
 897                         try:
 898                                 evDef._d = _bt_ctf_get_index(self._e, field._d, index)
 899                         except AttributeError:
 900                                 raise TypeError("in get_index, argument 2 must be a "
 901                                         "Definition (field) instance")
 902
 903                         if evDef._d is None:
 904                                 return None
 905                         return evDef
 906
 907                 def get_handle(self):
 908                         """
 909                         Get the TraceHandle associated with an event
 910                         Return None on error
 911                         """
 912                         ret = _bt_ctf_event_get_handle_id(self._e)
 913                         if ret < 0:
 914                                 return None
 915
 916                         th = TraceHandle.__new__(TraceHandle)
 917                         th._id = ret
 918                         return th
 919
 920                 def get_context(self):
 921                         """
 922                         Get the context associated with an event.
 923                         Return None on error.
 924                         """
 925                         ctx = Context()
 926                         ctx._c = _bt_ctf_event_get_context(self._e);
 927                         if ctx._c is None:
 928                                 return None
 929                         else:
 930                                 return ctx
 931
 932         class FieldError(Exception):
 933                 def __init__(self, value):
 934                         self.value = value
 935
 936                 def __str__(self):
 937                         return repr(self.value)
 938
 939         class Definition(object):
 940                 """Definition class.  Do not instantiate."""
 941
 942                 def __init__(self):
 943                         raise NotImplementedError("CTFReader.Definition cannot be instantiated")
 944
 945                 def __repr__(self):
 946                         return "Babeltrace Definition: name('{0}'), type({1})".format(
 947                                 self.field_name(), self.field_type())
 948
 949                 def field_name(self):
 950                         """Return the name of a field or None on error."""
 951                         return _bt_ctf_field_name(self._d)
 952
 953                 def field_type(self):
 954                         """Return the type of a field or -1 if unknown."""
 955                         return _bt_ctf_field_type(_bt_ctf_get_decl_from_def(self._d))
 956
 957                 def get_int_signedness(self):
 958                         """
 959                         Return the signedness of an integer:
 960                         0 if unsigned; 1 if signed; -1 on error.
 961                         """
 962                         return _bt_ctf_get_int_signedness(_bt_ctf_get_decl_from_def(self._d))
 963
 964                 def get_int_base(self):
 965                         """Return the base of an int or a negative value on error."""
 966                         return _bt_ctf_get_int_base(_bt_ctf_get_decl_from_def(self._d))
 967
 968                 def get_int_byte_order(self):
 969                         """
 970                         Return the byte order of an int or a negative
 971                         value on error.
 972                         """
 973                         return _bt_ctf_get_int_byte_order(_bt_ctf_get_decl_from_def(self._d))
 974
 975                 def get_int_len(self):
 976                         """
 977                         Return the size, in bits, of an int or a negative
 978                         value on error.
 979                         """
 980                         return _bt_ctf_get_int_len(_bt_ctf_get_decl_from_def(self._d))
 981
 982                 def get_enum_str(self):
 983                         """
 984                         Return the string matching the current enumeration.
 985                         Return None on error.
 986                         """
 987                         return _bt_ctf_get_enum_str(self._d)
 988
 989                 def get_encoding(self):
 990                         """
 991                         Return the encoding of an int or a string.
 992                         Return a negative value on error.
 993                         """
 994                         return _bt_ctf_get_encoding(_bt_ctf_get_decl_from_def(self._d))
 995
 996                 def get_array_len(self):
 997                         """
 998                         Return the len of an array or a negative
 999                         value on error.
1000                         """
1001                         return _bt_ctf_get_array_len(_bt_ctf_get_decl_from_def(self._d))
1002
1003                 def get_array_element_at(self, index):
1004                         """
1005                         Return the array's element at position index.
1006                         Return None on error
1007                         """
1008                         array = _bt_python_get_array_from_def(self._d)
1009                         if array is None:
1010                                 return None
1011
1012                         element = CTFReader.Definition.__new__(CTFReader.Definition)
1013                         element._d =  _bt_array_index(array, index)
1014                         if element._d is None:
1015                                 return None
1016                         return element
1017
1018                 def get_sequence_len(self):
1019                         """
1020                         Return the len of a sequence or a negative
1021                         value on error.
1022                         """
1023                         seq = _bt_python_get_sequence_from_def(self._d)
1024                         return _bt_sequence_len(seq)
1025
1026                 def get_sequence_element_at(self, index):
1027                         """
1028                         Return the sequence's element at position index,
1029                         otherwise return None
1030                         """
1031                         seq = _bt_python_get_sequence_from_def(self._d)
1032                         if seq is not None:
1033                                 element = CTFReader.Definition.__new__(CTFReader.Definition)
1034                                 element._d = _bt_sequence_index(seq, index)
1035                                 if element._d is not None:
1036                                         return element
1037                         return None
1038
1039                 def get_uint64(self):
1040                         """
1041                         Return the value associated with the field.
1042                         If the field does not exist or is not of the type requested,
1043                         the value returned is undefined. To check if an error occured,
1044                         use the CTFReader.field_error() function after accessing a field.
1045                         """
1046                         return _bt_ctf_get_uint64(self._d)
1047
1048                 def get_int64(self):
1049                         """
1050                         Return the value associated with the field.
1051                         If the field does not exist or is not of the type requested,
1052                         the value returned is undefined. To check if an error occured,
1053                         use the CTFReader.field_error() function after accessing a field.
1054                         """
1055                         return _bt_ctf_get_int64(self._d)
1056
1057                 def get_char_array(self):
1058                         """
1059                         Return the value associated with the field.
1060                         If the field does not exist or is not of the type requested,
1061                         the value returned is undefined. To check if an error occured,
1062                         use the CTFReader.field_error() function after accessing a field.
1063                         """
1064                         return _bt_ctf_get_char_array(self._d)
1065
1066                 def get_str(self):
1067                         """
1068                         Return the value associated with the field.
1069                         If the field does not exist or is not of the type requested,
1070                         the value returned is undefined. To check if an error occured,
1071                         use the CTFReader.field_error() function after accessing a field.
1072                         """
1073                         return _bt_ctf_get_string(self._d)
1074
1075                 def get_float(self):
1076                         """
1077                         Return the value associated with the field.
1078                         If the field does not exist or is not of the type requested,
1079                         the value returned is undefined. To check if an error occured,
1080                         use the CTFReader.field_error() function after accessing a field.
1081                         """
1082                         return _bt_ctf_get_float(self._d)
1083
1084                 def get_variant(self):
1085                         """
1086                         Return the variant's selected field.
1087                         If the field does not exist or is not of the type requested,
1088                         the value returned is undefined. To check if an error occured,
1089                         use the CTFReader.field_error() function after accessing a field.
1090                         """
1091                         return _bt_ctf_get_variant(self._d)
1092
1093                 def get_struct_field_count(self):
1094                         """
1095                         Return the number of fields contained in the structure.
1096                         If the field does not exist or is not of the type requested,
1097                         the value returned is undefined.
1098                         """
1099                         return _bt_ctf_get_struct_field_count(self._d)
1100
1101                 def get_struct_field_at(self, i):
1102                         """
1103                         Return the structure's field at position i.
1104                         If the field does not exist or is not of the type requested,
1105                         the value returned is undefined. To check if an error occured,
1106                         use the CTFReader.field_error() function after accessing a field.
1107                         """
1108                         return _bt_ctf_get_struct_field_index(self._d, i)
1109
1110                 def get_value(self):
1111                         """
1112                         Return the value associated with the field according to its type.
1113                         Return None on error.
1114                         """
1115                         id = self.field_type()
1116                         value = None
1117                         if id == CTFTypeId.STRING:
1118                                 value = self.get_str()
1119                         elif id == CTFTypeId.ARRAY:
1120                                 value = []
1121                                 for i in range(self.get_array_len()):
1122                                         element = self.get_array_element_at(i)
1123                                         value.append(element.get_value())
1124                         elif id == CTFTypeId.INTEGER:
1125                                 if self.get_int_signedness() == 0:
1126                                         value = self.get_uint64()
1127                                 else:
1128                                         value = self.get_int64()
1129                         elif id == CTFTypeId.ENUM:
1130                                 value = self.get_enum_str()
1131                         elif id == CTFTypeId.SEQUENCE:
1132                                 seq_len = self.get_sequence_len()
1133                                 value = []
1134                                 for i in range(seq_len):
1135                                         evDef = self.get_sequence_element_at(i)
1136                                         value.append(evDef.get_value())
1137                         elif id == CTFTypeId.FLOAT:
1138                                 value = self.get_float()
1139                         elif id == CTFTypeId.VARIANT:
1140                                 variant = CTFReader.Definition.__new__(CTFReader.Definition)
1141                                 variant._d = self.get_variant();
1142                                 value = variant.get_value()
1143                         elif id == CTFTypeId.STRUCT:
1144                                 value = {}
1145                                 for i in range(self.get_struct_field_count()):
1146                                         member = CTFReader.Definition.__new__(CTFReader.Definition)
1147                                         member._d = self.get_struct_field_at(i);
1148                                         value[member.field_name()] = member.get_value()
1149
1150                         if CTFReader.field_error():
1151                                 raise CTFReader.FieldError("Error occured while accessing field {} of type {}".format(self.field_name(), CTFTypeId.get_type_name(self.field_type())))
1152                         return value
1153
1154                 def get_scope(self):
1155                         """Return the scope of a field or None on error."""
1156                         return self._s
1157
1158         class EventDecl(object):
1159                 """Event declaration class.  Do not instantiate."""
1160
1161                 def __init__(self):
1162                         raise NotImplementedError("CTFReader.EventDecl cannot be instantiated")
1163
1164                 def __repr__(self):
1165                         return "Babeltrace EventDecl: name {0}".format(self.get_name())
1166
1167                 def get_name(self):
1168                         """Return the name of the event or None on error"""
1169                         return _bt_ctf_get_decl_event_name(self._d)
1170
1171                 def get_decl_fields(self, scope):
1172                         """
1173                         Return a list of CTFReader.FieldDecl
1174                         Return None on error.
1175                         """
1176                         ptr_list = _by_python_field_decl_listcaller(self._d, scope)
1177
1178                         if ptr_list is None:
1179                                 return None
1180
1181                         decl_list = []
1182                         i = 0
1183                         while True:
1184                                 tmp = CTFReader.FieldDecl.__new__(CTFReader.FieldDecl)
1185                                 tmp._d =  _bt_python_field_decl_one_from_list(
1186                                         ptr_list, i)
1187
1188                                 if tmp._d is None:
1189                                         #Last item of list is None
1190                                         break
1191
1192                                 decl_list.append(tmp)
1193                                 i += 1
1194                         return decl_list
1195
1196
1197         class FieldDecl(object):
1198                 """Field declaration class.  Do not instantiate."""
1199
1200                 def __init__(self):
1201                         raise NotImplementedError("CTFReader.FieldDecl cannot be instantiated")
1202
1203                 def __repr__(self):
1204                         return "Babeltrace FieldDecl: name {0}".format(self.get_name())
1205
1206                 def get_name(self):
1207                         """Return the name of a FieldDecl or None on error"""
1208                         return _bt_ctf_get_decl_field_name(self._d)
1209
1210
1211         @staticmethod
1212         def field_error():
1213                 """
1214                 Return the last error code encountered while
1215                 accessing a field and reset the error flag.
1216                 Return 0 if no error, a negative value otherwise.
1217                 """
1218                 return _bt_ctf_field_get_error()
1219
1220         @staticmethod
1221         def get_event_decl_list(trace_handle, context):
1222                 """
1223                 Return a list of CTFReader.EventDecl
1224                 Return None on error.
1225                 """
1226                 try:
1227                         handle_id = trace_handle._id
1228                 except AttributeError:
1229                                 raise TypeError("in get_event_decl_list, "
1230                                         "argument 1 must be a TraceHandle instance")
1231                 try:
1232                         ptr_list, count = _bt_python_event_decl_listcaller(handle_id, context._c)
1233                 except AttributeError:
1234                                 raise TypeError("in get_event_decl_list, "
1235                                         "argument 2 must be a Context instance")
1236
1237                 if ptr_list is None:
1238                         return None
1239
1240                 decl_list = []
1241                 for i in range(count):
1242                         tmp = CTFReader.EventDecl.__new__(CTFReader.EventDecl)
1243                         tmp._d =  _bt_python_decl_one_from_list(ptr_list, i)
1244                         decl_list.append(tmp)
1245
1246                 return decl_list
1247
1248 %}
1249
1250
1251
1252 // =================================================================
1253 //                            NEW FUNCTIONS
1254 //                         File and list-related
1255 //                         python-complements.h
1256 // =================================================================
1257
1258 %pythoncode %{
1259
1260 class File(object):
1261         """
1262         Open a file for babeltrace.
1263
1264         file_path is a string containing the path or None to use the
1265         standard output in writing mode.
1266
1267         The mode can be 'r', 'w' or 'a' for reading (default), writing or
1268         appending.  The file will be created if it doesn't exist when
1269         opened for writing or appending; it will be truncated when opened
1270         for writing.  Add a 'b' to the mode for binary files.  Add a '+'
1271         to the mode to allow simultaneous reading and writing.
1272         """
1273
1274         def __new__(cls, file_path, mode='r'):
1275                 # __new__ is used to control the return value
1276                 # as the File class should return None
1277                 # if _bt_file_open returns NULL
1278
1279                 # Type check
1280                 if file_path is not None and type(file_path) is not str:
1281                         raise TypeError("in method __init__, argument 2 of type 'str'")
1282                 if type(mode) is not str:
1283                         raise TypeError("in method __init__, argument 3 of type 'str'")
1284
1285                 # Opening file
1286                 file_ptr = _bt_file_open(file_path, mode)
1287                 if file_ptr is None:
1288                         return None
1289
1290                 # Class instantiation
1291                 file_inst = super(File, cls).__new__(cls)
1292                 file_inst._file = file_ptr
1293                 return file_inst
1294
1295         def __init__(self, file_path, mode='r'):
1296                 self._opened = True
1297                 self._use_stdout = False
1298
1299                 if file_path is None:
1300                         # use stdout
1301                         file_path = "stdout"
1302                         mode = 'w'
1303                         self._use_stdout = True
1304
1305                 self._file_path = file_path
1306                 self._mode = mode
1307
1308         def __del__(self):
1309                 self.close()
1310
1311         def __repr__(self):
1312                 if self._opened:
1313                         stat = 'opened'
1314                 else:
1315                         stat = 'closed'
1316                 return "{0} babeltrace File; file_path('{1}'), mode('{2}')".format(
1317                         stat, self._file_path, self._mode)
1318
1319         def close(self):
1320                 """Close the file.  Is also called using del."""
1321                 if self._opened and not self._use_stdout:
1322                         _bt_file_close(self._file)
1323                         self._opened = False
1324 %}