lib/rpmtd.h

   1 #ifndef _RPMTD_H
   2 #define _RPMTD_H
   3
   4 #include <rpm/rpmtypes.h>
   5 #include <rpm/argv.h>
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 typedef enum rpmtdFlags_e {
  12     RPMTD_NONE          = 0,
  13     RPMTD_ALLOCED       = (1 << 0),     /* was memory allocated? */
  14     RPMTD_PTR_ALLOCED   = (1 << 1),     /* were array pointers allocated? */
  15     RPMTD_IMMUTABLE     = (1 << 2),     /* header data or modifiable? */
  16     RPMTD_ARGV          = (1 << 3),     /* string array is NULL-terminated? */
  17 } rpmtdFlags;
  18
  19 /** \ingroup rpmtd
  20  * Container for rpm tag data (from headers or extensions).
  21  * @todo                Make this opaque (at least outside rpm itself)
  22  */
  23 struct rpmtd_s {
  24     rpmTag tag;         /* rpm tag of this data entry*/
  25     rpmTagType type;    /* data type */
  26     rpm_count_t count;  /* number of entries */
  27     rpm_data_t data;    /* pointer to actual data */
  28     rpmtdFlags flags;   /* flags on memory allocation etc */
  29     int ix;             /* iteration index */
  30 };
  31
  32 /** \ingroup rpmtd
  33  * Create new tag data container
  34  * @return              New, initialized tag data container.
  35  */
  36 rpmtd rpmtdNew(void);
  37
  38 /** \ingroup rpmtd
  39  * Destroy tag data container.
  40  * @param td            Tag data container
  41  * @return              NULL always
  42  */
  43 rpmtd rpmtdFree(rpmtd td);
  44
  45 /** \ingroup rpmtd
  46  * (Re-)initialize tag data container. Contents will be zeroed out
  47  * and iteration index reset.
  48  * @param td            Tag data container
  49  */
  50 void rpmtdReset(rpmtd td);
  51
  52 /** \ingroup rpmtd
  53  * Free contained data. This is always safe to call as the container knows
  54  * if data was malloc'ed or not. Container is reinitialized.
  55  * @param td            Tag data container
  56  */
  57 void rpmtdFreeData(rpmtd td);
  58
  59 /** \ingroup rpmtd
  60  * Retrieve array size of the container. For non-array types this is always 1.
  61  * @param td            Tag data container
  62  * @return              Number of entries in contained data.
  63  */
  64 rpm_count_t rpmtdCount(rpmtd td);
  65
  66 /** \ingroup rpmtd
  67  * Retrieve tag of the container.
  68  * @param td            Tag data container
  69  * @return              Rpm tag.
  70  */
  71 rpmTag rpmtdTag(rpmtd td);
  72
  73 /** \ingroup rpmtd
  74  * Retrieve type of the container.
  75  * @param td            Tag data container
  76  * @return              Rpm tag type.
  77  */
  78 rpmTagType rpmtdType(rpmtd td);
  79
  80 /** \ingroup rpmtd
  81  * Retrieve class of the container.
  82  * @param td            Tag data container
  83  * @return              Rpm tag class
  84  */
  85 rpmTagClass rpmtdClass(rpmtd td);
  86
  87 /** \ingroup rpmtd
  88  * Retrieve current iteration index of the container.
  89  * @param td            Tag data container
  90  * @return              Iteration index (or -1 if not iterating)
  91  */
  92 int rpmtdGetIndex(rpmtd td);
  93
  94 /** \ingroup rpmtd
  95  * Set iteration index of the container.
  96  * If new index is out of bounds for the container, -1 is returned and
  97  * iteration index is left untouched.
  98  * @param td            Tag data container
  99  * @param index         New index
 100  * @return              New index, or -1 if index out of bounds
 101  */
 102 int rpmtdSetIndex(rpmtd td, int index);
 103
 104 /** \ingroup rpmtd
 105  * Initialize tag container for iteration
 106  * @param td            Tag data container
 107  * @return              0 on success
 108  */
 109 int rpmtdInit(rpmtd td);
 110
 111 /** \ingroup rpmtd
 112  * Iterate over tag data container.
 113  * @param td            Tag data container
 114  * @return              Tag data container iterator index, -1 on termination
 115  */
 116 int rpmtdNext(rpmtd td);
 117
 118 /** \ingroup rpmtd
 119  * Iterate over uint32_t type tag data container.
 120  * @param td            Tag data container
 121  * @return              Pointer to next value, NULL on termination or error
 122  */
 123 uint32_t *rpmtdNextUint32(rpmtd td);
 124
 125 /** \ingroup rpmtd
 126  * Iterate over uint64_t type tag data container.
 127  * @param td            Tag data container
 128  * @return              Pointer to next value, NULL on termination or error
 129  */
 130 uint64_t *rpmtdNextUint64(rpmtd td);
 131
 132 /** \ingroup rpmtd
 133  * Iterate over string / string array type tag data container.
 134  * @param td            Tag data container
 135  * @return              Pointer to next value, NULL on termination or error
 136  */
 137 const char *rpmtdNextString(rpmtd td);
 138
 139 /** \ingroup rpmtd
 140  * Return char data from tag container.
 141  * For scalar return type, just return pointer to the integer. On array
 142  * types, return pointer to current iteration index. If the tag container
 143  * is not for char type, NULL is returned.
 144  * @param td            Tag data container
 145  * @return              Pointer to uint16_t, NULL on error
 146  */
 147 char *rpmtdGetChar(rpmtd td);
 148
 149 /** \ingroup rpmtd
 150  * Return uint16_t data from tag container.
 151  * For scalar return type, just return pointer to the integer. On array
 152  * types, return pointer to current iteration index. If the tag container
 153  * is not for int16 type, NULL is returned.
 154  * @param td            Tag data container
 155  * @return              Pointer to uint16_t, NULL on error
 156  */
 157 uint16_t * rpmtdGetUint16(rpmtd td);
 158
 159 /** \ingroup rpmtd
 160  * Return uint32_t data from tag container.
 161  * For scalar return type, just return pointer to the integer. On array
 162  * types, return pointer to current iteration index. If the tag container
 163  * is not for int32 type, NULL is returned.
 164  * @param td            Tag data container
 165  * @return              Pointer to uint32_t, NULL on error
 166  */
 167 uint32_t * rpmtdGetUint32(rpmtd td);
 168
 169 /** \ingroup rpmtd
 170  * Return uint64_t data from tag container.
 171  * For scalar return type, just return pointer to the integer. On array
 172  * types, return pointer to current iteration index. If the tag container
 173  * is not for int64 type, NULL is returned.
 174  * @param td            Tag data container
 175  * @return              Pointer to uint64_t, NULL on error
 176  */
 177 uint64_t * rpmtdGetUint64(rpmtd td);
 178
 179 /** \ingroup rpmtd
 180  * Return string data from tag container.
 181  * For string types, just return the string. On string array types,
 182  * return the string from current iteration index. If the tag container
 183  * is not for a string type, NULL is returned.
 184  * @param td            Tag data container
 185  * @return              String constant from container, NULL on error
 186  */
 187 const char * rpmtdGetString(rpmtd td);
 188
 189 /** \ingroup rpmtd
 190  * Return numeric value from tag container.
 191  * Returns the value of numeric container (RPM_NUMERIC_CLASS) from
 192  * current iteration index as uint64_t regardless of its internal
 193  * presentation (8/16/32/64-bit integer).
 194  * @param td            Tag data container
 195  * @return              Value of current iteration item as uint64_t,
 196  *                      0 for non-numeric types (error)
 197  */
 198 uint64_t rpmtdGetNumber(rpmtd td);
 199
 200 typedef enum rpmtdFormats_e {
 201     RPMTD_FORMAT_STRING         = 0,    /* plain string (any type) */
 202     RPMTD_FORMAT_ARMOR          = 1,    /* ascii armor format (bin types) */
 203     RPMTD_FORMAT_BASE64         = 2,    /* base64 encoding (bin types) */
 204     RPMTD_FORMAT_PGPSIG         = 3,    /* pgp/gpg signature (bin types) */
 205     RPMTD_FORMAT_DEPFLAGS       = 4,    /* dependency flags (int32 types) */
 206     RPMTD_FORMAT_FFLAGS         = 5,    /* file flags (int32 types) */
 207     RPMTD_FORMAT_PERMS          = 6,    /* permission string (int32 types) */
 208     RPMTD_FORMAT_TRIGGERTYPE    = 7,    /* trigger types */
 209     RPMTD_FORMAT_XML            = 8,    /* xml format (any type) */
 210     RPMTD_FORMAT_OCTAL          = 9,    /* octal format (int32 types) */
 211     RPMTD_FORMAT_HEX            = 10,   /* hex format (int32 types) */
 212     RPMTD_FORMAT_DATE           = 11,   /* date format (int32 types) */
 213     RPMTD_FORMAT_DAY            = 12,   /* day format (int32 types) */
 214     RPMTD_FORMAT_SHESCAPE       = 13,   /* shell escaped (any type) */
 215     RPMTD_FORMAT_ARRAYSIZE      = 14,   /* size of contained array (any type) */
 216     RPMTD_FORMAT_DEPTYPE        = 15,   /* dependency types (int32 types) */
 217 } rpmtdFormats;
 218
 219 /** \ingroup rpmtd
 220  * Format data from tag container to string presentation of given format.
 221  * Return malloced string presentation of current data in container,
 222  * converting from integers etc as necessary. On array types, data from
 223  * current iteration index is used for formatting.
 224  * @param td            Tag data container
 225  * @param fmt           Format to apply
 226  * @param errmsg        Error message from conversion (or NULL)
 227  * @return              String representation of current data (malloc'ed),
 228  *                      NULL on error
 229  */
 230 char *rpmtdFormat(rpmtd td, rpmtdFormats fmt, const char *errmsg);
 231
 232 /** \ingroup rpmtd
 233  * Set container tag and type.
 234  * For empty container, any valid tag can be set. If the container has
 235  * data, changing is only permitted to tag of same type.
 236  * @param td            Tag data container
 237  * @param tag           New tag
 238  * @return              1 on success, 0 on error
 239  */
 240 int rpmtdSetTag(rpmtd td, rpmTag tag);
 241
 242 /** \ingroup rpmtd
 243  * Construct tag container from uint8_t pointer.
 244  * Tag type is checked to be of compatible type (CHAR, INT8 or BIN).
 245  * For non-array types (BIN is a special case of INT8 array)
 246  * count must be exactly 1.
 247  * @param td            Tag data container
 248  * @param tag           Rpm tag to construct
 249  * @param data          Pointer to uint8_t (value or array)
 250  * @param count         Number of entries
 251  * @return              1 on success, 0 on error (eg wrong type)
 252  */
 253 int rpmtdFromUint8(rpmtd td, rpmTag tag, uint8_t *data, rpm_count_t count);
 254
 255 /** \ingroup rpmtd
 256  * Construct tag container from uint16_t pointer.
 257  * Tag type is checked to be of INT16 type. For non-array types count
 258  * must be exactly 1.
 259  * @param td            Tag data container
 260  * @param tag           Rpm tag to construct
 261  * @param data          Pointer to uint16_t (value or array)
 262  * @param count         Number of entries
 263  * @return              1 on success, 0 on error (eg wrong type)
 264  */
 265 int rpmtdFromUint16(rpmtd td, rpmTag tag, uint16_t *data, rpm_count_t count);
 266
 267 /** \ingroup rpmtd
 268  * Construct tag container from uint32_t pointer.
 269  * Tag type is checked to be of INT32 type. For non-array types count
 270  * must be exactly 1.
 271  * @param td            Tag data container
 272  * @param tag           Rpm tag to construct
 273  * @param data          Pointer to uint32_t (value or array)
 274  * @param count         Number of entries
 275  * @return              1 on success, 0 on error (eg wrong type)
 276  */
 277 int rpmtdFromUint32(rpmtd td, rpmTag tag, uint32_t *data, rpm_count_t count);
 278
 279 /** \ingroup rpmtd
 280  * Construct tag container from uint64_t pointer.
 281  * Tag type is checked to be of INT64 type. For non-array types count
 282  * must be exactly 1.
 283  * @param td            Tag data container
 284  * @param tag           Rpm tag to construct
 285  * @param data          Pointer to uint64_t (value or array)
 286  * @param count         Number of entries
 287  * @return              1 on success, 0 on error (eg wrong type)
 288  */
 289 int rpmtdFromUint64(rpmtd td, rpmTag tag, uint64_t *data, rpm_count_t count);
 290
 291 /** \ingroup rpmtd
 292  * Construct tag container from a string.
 293  * Tag type is checked to be of string type.
 294  * @param td            Tag data container
 295  * @param tag           Rpm tag to construct
 296  * @param data          String to use
 297  * @return              1 on success, 0 on error (eg wrong type)
 298  */
 299 int rpmtdFromString(rpmtd td, rpmTag tag, const char *data);
 300
 301 /** \ingroup rpmtd
 302  * Construct tag container from a string array.
 303  * Tag type is checked to be of string or string array type. For non-array
 304  * types count must be exactly 1.
 305  * @param td            Tag data container
 306  * @param tag           Rpm tag to construct
 307  * @param data          Pointer to string array
 308  * @param count         Number of entries
 309  * @return              1 on success, 0 on error (eg wrong type)
 310  */
 311 int rpmtdFromStringArray(rpmtd td, rpmTag tag, const char **data, rpm_count_t count);
 312
 313 /** \ingroup rpmtd
 314  * Construct tag container from ARGV_t array.
 315  * Tag type is checked to be of string array type and array is checked
 316  * to be non-empty.
 317  * @param td            Tag data container
 318  * @param tag           Rpm tag to construct
 319  * @param argv          ARGV array
 320  * @return              1 on success, 0 on error (eg wrong type)
 321  */
 322 int rpmtdFromArgv(rpmtd td, rpmTag tag, ARGV_t argv);
 323
 324 /** \ingroup rpmtd
 325  * Construct tag container from ARGI_t array.
 326  * Tag type is checked to be of integer array type and array is checked
 327  * to be non-empty.
 328  * @param td            Tag data container
 329  * @param tag           Rpm tag to construct
 330  * @param argi          ARGI array
 331  * @return              1 on success, 0 on error (eg wrong type)
 332  */
 333 int rpmtdFromArgi(rpmtd td, rpmTag tag, ARGI_t argi);
 334
 335 /* \ingroup rpmtd
 336  * Perform deep copy of container.
 337  * Create a modifiable copy of tag data container (on string arrays each
 338  * string is separately allocated)
 339  * @todo                Only string arrays types are supported currently
 340  * @param td            Container to copy
 341  * @return              New container or NULL on error
 342  */
 343 rpmtd rpmtdDup(rpmtd td);
 344
 345 #ifdef __cplusplus
 346 }
 347 #endif
 348
 349 #endif /* _RPMTD_H */