X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=doc%2FAPI.txt;h=e13e6adf3545d306e36c2496dd2feb50479d1eea;hp=bc3a4a10512e1aef477ee950de8a61d009250159;hb=f5464725ea2c2344ffa73a67eac22b9f0ddb65dd;hpb=953bcd8957c2230a42f1e456b4f375cdabd6d861

diff --git a/doc/API.txt b/doc/API.txt
index bc3a4a10..e13e6adf 100644
--- a/doc/API.txt
+++ b/doc/API.txt
@@ -28,6 +28,20 @@ TERMINOLOGY
 * A "trace handle" is a unique identifier representing a trace file.
   It allows the user to manipulate a trace directly.
 
+* The "declaration" of a field or an event, is the structure which contains
+  the representaion of an object as declared in the metadata. All the
+  declarations of all events and fields can be accessed as soon as the trace is
+  open, but of course they contain no trace data, just the layout.
+
+* The "definition" of a field or an event is the structure in which the actual
+  trace data is contained. When we read an event in the trace, we access its
+  definition and we can access all the field definitions contained in all the
+  scopes of this event to the get the actual data.
+
+* "Scopes" allow specifying the level at which the information about the
+  current event must be fetched: event header, event payload, event context,
+  stream context. Compound-type (arrays, structures, sequences and variants)
+  fields are relative scopes which contain fields.
 
 
 USAGE
@@ -125,8 +139,13 @@ variant)
 
 For more information on each scope, see the CTF specifications.
 
-The function to get a field list is the bt_ctf_get_field_list(). The function
-to get the definition of a specific field is bt_ctf_get_field().
+The bt_ctf_get_field_list() function gives access to the list of fields in the
+current event. The bt_ctf_get_field() function gives acces to of a specific
+field of an event.
+
+The bt_ctf_get_event_decl_list() and bt_ctf_get_decl_fields() functions give
+respectively access to the list of the events declared in a trace and the list
+of the fields declared in an event.
 
 Once the field is obtained, we can obtain its name and type using the
 bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The
@@ -143,8 +162,8 @@ possible types are defined in the ctf_type_id enum:
 	CTF_TYPE_SEQUENCE,
 	NR_CTF_TYPES.
 
-Depending on the field type, we can get informations about the field with these
-functions:
+Depending on the field type, we can get informations about the field with the
+following functions:
 	* bt_ctf_get_index()		return the element at the index
 					position of an array of a sequence;
 
@@ -166,7 +185,13 @@ functions:
 						CTF_STRING_ASCII,
 						CTF_STRING_UNKNOWN.
 
-These functions give access to the value associated with a field :
+All of these functions require a field declaration as parameter, depending on
+the source type of data (struct definition* or struct bt_ctf_field_decl*), the
+user might have to call bt_ctf_get_decl_from_def() or
+bt_ctf_get_decl_from_field_decl().
+
+The following functions give access to the value associated with a field
+defintion:
 	* bt_ctf_get_uint64();
 	* bt_ctf_get_int64();
 	* bt_ctf_get_char_array();