lttv/lttv/iattribute.h

   1 /* This file is part of the Linux Trace Toolkit viewer
   2  * Copyright (C) 2003-2004 Michel Dagenais
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License Version 2 as
   6  * published by the Free Software Foundation;
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  16  * MA 02111-1307, USA.
  17  */
  18
  19 /* FIXME : unnamed attributes not implemented */
  20
  21 #ifndef IATTRIBUTE_H
  22 #define IATTRIBUTE_H
  23
  24
  25 #include <glib-object.h>
  26 #include <lttv/time.h>
  27
  28 /* The content of a data structure may be seen as an array of pairs of
  29  * attribute name and value. This simple model allows generic navigation
  30  * and access functions over a wide range of structures. The names are
  31  * represented by unique integer identifiers, GQuarks. */
  32
  33 /* Please note that adding a value of type gobject that is non null does not
  34  * increment the reference count of this object : the actual reference to
  35  * the object is "given" to the attribute tree. When the gobject value
  36  * is removed, the object is unreferenced. A value copy through
  37  * lttv_iattribute_copy_value does increase the reference count of the
  38  * gobject. */
  39
  40 typedef GQuark LttvAttributeName;
  41
  42 typedef enum _LttvAttributeType {
  43         LTTV_INT, LTTV_UINT, LTTV_LONG, LTTV_ULONG, LTTV_FLOAT, LTTV_DOUBLE,
  44         LTTV_TIME, LTTV_POINTER, LTTV_STRING, LTTV_GOBJECT, LTTV_NONE
  45 } LttvAttributeType;
  46
  47 typedef union LttvAttributeValue {
  48         int *v_int;
  49         unsigned *v_uint;
  50         long *v_long;
  51         unsigned long *v_ulong;
  52         float *v_float;
  53         double *v_double;
  54         LttTime *v_time;
  55         gpointer *v_pointer;
  56         char **v_string;
  57         GObject **v_gobject;
  58 } LttvAttributeValue;
  59
  60
  61 /* GObject interface type macros */
  62
  63 #define LTTV_IATTRIBUTE_TYPE       (lttv_iattribute_get_type ())
  64 #define LTTV_IATTRIBUTE(obj)        (G_TYPE_CHECK_INSTANCE_CAST ((obj), LTTV_IATTRIBUTE_TYPE, LttvIAttribute))
  65 #define LTTV_IATTRIBUTE_CLASS(vtable)    (G_TYPE_CHECK_CLASS_CAST ((vtable), LTTV_IATTRIBUTE_TYPE, LttvIAttributeClass))
  66 #define LTTV_IS_IATTRIBUTE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), LTTV_IATTRIBUTE_TYPE))
  67 #define LTTV_IS_IATTRIBUTE_CLASS(vtable) (G_TYPE_CHECK_CLASS_TYPE ((vtable), LTTV_IATTRIBUTE_TYPE))
  68 #define LTTV_IATTRIBUTE_GET_CLASS(inst)  (G_TYPE_INSTANCE_GET_INTERFACE ((inst), LTTV_IATTRIBUTE_TYPE, LttvIAttributeClass))
  69
  70
  71 typedef struct _LttvIattribute LttvIAttribute; /* dummy object */
  72 typedef struct _LttvIAttributeClass LttvIAttributeClass;
  73
  74
  75 struct _LttvIAttributeClass {
  76         GTypeInterface parent;
  77
  78         LttvIAttribute* (*new_attribute) (LttvIAttribute *self);
  79
  80         unsigned int (*get_number) (LttvIAttribute *self);
  81
  82         gboolean (*named) (LttvIAttribute *self, gboolean *homogeneous);
  83
  84         LttvAttributeType (*get) (LttvIAttribute *self, unsigned i,
  85                         LttvAttributeName *name, LttvAttributeValue *v, gboolean *is_named);
  86
  87         LttvAttributeType (*get_by_name) (LttvIAttribute *self,
  88                         LttvAttributeName name, LttvAttributeValue *v);
  89
  90         LttvAttributeValue (*add) (LttvIAttribute *self, LttvAttributeName name,
  91                         LttvAttributeType t);
  92
  93         LttvAttributeValue (*add_unnamed) (LttvIAttribute *self,
  94                         LttvAttributeName name,
  95                         LttvAttributeType t);
  96
  97         void (*remove) (LttvIAttribute *self, unsigned i);
  98
  99         void (*remove_by_name) (LttvIAttribute *self,
 100                         LttvAttributeName name);
 101
 102         LttvIAttribute* (*find_subdir) (LttvIAttribute *self,
 103                         LttvAttributeName name);
 104
 105         LttvIAttribute* (*find_subdir_unnamed) (LttvIAttribute *self,
 106                         LttvAttributeName name);
 107
 108 };
 109
 110
 111 GType lttv_iattribute_get_type(void);
 112
 113
 114 /* Total number of attributes */
 115
 116 unsigned int lttv_iattribute_get_number(LttvIAttribute *self);
 117
 118
 119 /* Container type. Named (fields in struct or elements in a hash table)
 120    or unnamed (elements in an array) attributes, homogeneous type or not. */
 121
 122 gboolean lttv_iattribute_named(LttvIAttribute *self, gboolean *homogeneous);
 123
 124
 125 /* Get the i th attribute along with its type and a pointer to its value. */
 126
 127 LttvAttributeType lttv_iattribute_get(LttvIAttribute *self, unsigned i,
 128                 LttvAttributeName *name, LttvAttributeValue *v, gboolean *is_named);
 129
 130
 131 /* Get the named attribute in the table along with its type and a pointer to
 132    its value. If the named attribute does not exist, the type is LTTV_NONE. */
 133
 134 LttvAttributeType lttv_iattribute_get_by_name(LttvIAttribute *self,
 135                 LttvAttributeName name, LttvAttributeValue *v);
 136
 137
 138 /* Add an attribute, which must not exist. The name is an empty string for
 139    containers with unnamed attributes. Its value is initialized to 0 or NULL
 140    and its pointer returned. */
 141
 142 LttvAttributeValue lttv_iattribute_add(LttvIAttribute *self,
 143                 LttvAttributeName name, LttvAttributeType t);
 144
 145 LttvAttributeValue lttv_iattribute_add_unnamed(LttvIAttribute *self,
 146                 LttvAttributeName name, LttvAttributeType t);
 147 /* Remove an attribute */
 148
 149 void lttv_iattribute_remove(LttvIAttribute *self, unsigned i);
 150
 151 void lttv_iattribute_remove_by_name(LttvIAttribute *self,
 152                 LttvAttributeName name);
 153
 154
 155 /* Create an empty iattribute object and add it as an attribute under the
 156    specified name, or return an existing iattribute attribute. If an
 157    attribute of that name already exists but is not a GObject supporting the
 158    iattribute interface, return NULL. */
 159
 160 LttvIAttribute* lttv_iattribute_find_subdir(LttvIAttribute *self,
 161                 LttvAttributeName name);
 162
 163 LttvIAttribute* lttv_iattribute_find_subdir_unnamed(LttvIAttribute *self,
 164                 LttvAttributeName name);
 165
 166 /* The remaining utility functions are not part of the LttvIAttribute
 167    interface but operate on objects implementing it. */
 168
 169 /* Find the named attribute in the table, which must be of the specified type.
 170    If it does not exist, it is created with a default value of 0 (NULL for
 171    pointer types). Since the address of the value is obtained, it may be
 172    changed easily afterwards. The function returns false when the attribute
 173    exists but is of incorrect type. */
 174
 175 gboolean lttv_iattribute_find(LttvIAttribute *self, LttvAttributeName name,
 176                 LttvAttributeType t, LttvAttributeValue *v);
 177
 178
 179 /* Trees of attribute tables may be accessed using a hierarchical path with
 180    components separated by /, like in filesystems */
 181
 182 gboolean lttv_iattribute_find_by_path(LttvIAttribute *self, const char *path,
 183                 LttvAttributeType t, LttvAttributeValue *v);
 184
 185
 186 /* Shallow and deep copies */
 187
 188 void lttv_iattribute_copy_value(LttvAttributeType t, LttvAttributeValue dest,
 189                 LttvAttributeValue src);
 190
 191 LttvIAttribute *lttv_iattribute_shallow_copy(LttvIAttribute *self);
 192
 193 LttvIAttribute *lttv_iattribute_deep_copy(LttvIAttribute *self);
 194
 195 #endif // IATTRIBUTE_H