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