lib/rpmds.h

   1 #ifndef H_RPMDS
   2 #define H_RPMDS
   3
   4 /** \ingroup rpmdep rpmtrans
   5  * \file lib/rpmds.h
   6  * Structure(s) used for dependency tag sets.
   7  */
   8
   9 #include "rpmps.h"
  10
  11 /**
  12  */
  13 /*@-exportlocal@*/
  14 /*@unchecked@*/
  15 extern int _rpmds_debug;
  16 /*@=exportlocal@*/
  17
  18 /**
  19  */
  20 /*@-exportlocal@*/
  21 /*@unchecked@*/
  22 extern int _rpmds_nopromote;
  23 /*@=exportlocal@*/
  24
  25 #if defined(_RPMDS_INTERNAL)
  26 /**
  27  * A package dependency set.
  28  */
  29 struct rpmds_s {
  30     int i;                      /*!< Element index. */
  31
  32 /*@observer@*/
  33     const char * Type;          /*!< Tag name. */
  34 /*@only@*/ /*@null@*/
  35     const char * DNEVR;         /*!< Formatted dependency string. */
  36
  37     rpmTag tagN;                /*!< Header tag. */
  38 /*@refcounted@*/ /*@null@*/
  39     Header h;                   /*!< Header for dependency set (or NULL) */
  40
  41 /*@only@*/
  42     const char ** N;            /*!< Name. */
  43 /*@only@*/
  44     const char ** EVR;          /*!< Epoch-Version-Release. */
  45 /*@only@*/
  46     int_32 * Flags;             /*!< Flags identifying context/comparison. */
  47     rpmTagType Nt, EVRt, Ft;    /*!< Tag data types. */
  48     int_32 Count;               /*!< No. of elements */
  49     int nopromote;              /*!< Don't promote Epoch: in rpmdsCompare()? */
  50 /*@refs@*/
  51     int nrefs;                  /*!< Reference count. */
  52 };
  53 #endif  /* _RPMDS_INTERNAL */
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /**
  60  * Unreference a dependency set instance.
  61  * @param ds            dependency set
  62  * @param msg
  63  * @return              NULL always
  64  */
  65 /*@unused@*/ /*@null@*/
  66 rpmds rpmdsUnlink (/*@killref@*/ /*@only@*/ /*@null@*/ rpmds ds,
  67                 /*@null@*/ const char * msg)
  68         /*@modifies ds @*/;
  69
  70 /** @todo Remove debugging entry from the ABI. */
  71 /*@-exportlocal@*/
  72 /*@null@*/
  73 rpmds XrpmdsUnlink (/*@killref@*/ /*@only@*/ /*@null@*/ rpmds ds,
  74                 /*@null@*/ const char * msg, const char * fn, unsigned ln)
  75         /*@modifies ds @*/;
  76 /*@=exportlocal@*/
  77 #define rpmdsUnlink(_ds, _msg)  XrpmdsUnlink(_ds, _msg, __FILE__, __LINE__)
  78
  79 /**
  80  * Reference a dependency set instance.
  81  * @param ds            dependency set
  82  * @param msg
  83  * @return              new dependency set reference
  84  */
  85 /*@unused@*/ /*@newref@*/
  86 rpmds rpmdsLink (/*@null@*/ rpmds ds, /*@null@*/ const char * msg)
  87         /*@modifies ds @*/;
  88
  89 /** @todo Remove debugging entry from the ABI. */
  90 /*@newref@*/
  91 rpmds XrpmdsLink (/*@null@*/ rpmds ds, /*@null@*/ const char * msg,
  92                 const char * fn, unsigned ln)
  93         /*@modifies ds @*/;
  94 #define rpmdsLink(_ds, _msg)    XrpmdsLink(_ds, _msg, __FILE__, __LINE__)
  95
  96 /**
  97  * Destroy a dependency set.
  98  * @param ds            dependency set
  99  * @return              NULL always
 100  */
 101 /*@null@*/
 102 rpmds rpmdsFree(/*@killref@*/ /*@only@*/ /*@null@*/ rpmds ds)
 103         /*@modifies ds@*/;
 104 /**
 105  * Create and load a dependency set.
 106  * @param h             header
 107  * @param tagN          type of dependency
 108  * @param scareMem      Use pointers to refcounted header memory?
 109  * @return              new dependency set
 110  */
 111 /*@null@*/
 112 rpmds rpmdsNew(Header h, rpmTag tagN, int scareMem)
 113         /*@modifies h @*/;
 114
 115 /**
 116  * Return new formatted dependency string.
 117  * @param dspfx         formatted dependency string prefix
 118  * @param ds            dependency set
 119  * @return              new formatted dependency (malloc'ed)
 120  */
 121 /*@only@*/
 122 char * rpmdsNewDNEVR(const char * dspfx, const rpmds ds)
 123         /*@*/;
 124
 125 /**
 126  * Create, load and initialize a dependency for this header.
 127  * @param h             header
 128  * @param tagN          type of dependency
 129  * @param Flags         comparison flags
 130  * @return              new dependency set
 131  */
 132 /*@null@*/
 133 rpmds rpmdsThis(Header h, rpmTag tagN, int_32 Flags)
 134         /*@*/;
 135
 136 /**
 137  * Create, load and initialize a dependency set of size 1.
 138  * @param tagN          type of dependency
 139  * @param N             name
 140  * @param EVR           epoch:version-release
 141  * @param Flags         comparison flags
 142  * @return              new dependency set
 143  */
 144 /*@null@*/
 145 rpmds rpmdsSingle(rpmTag tagN, const char * N, const char * EVR, int_32 Flags)
 146         /*@*/;
 147
 148 /**
 149  * Return dependency set count.
 150  * @param ds            dependency set
 151  * @return              current count
 152  */
 153 int rpmdsCount(/*@null@*/ const rpmds ds)
 154         /*@*/;
 155
 156 /**
 157  * Return dependency set index.
 158  * @param ds            dependency set
 159  * @return              current index
 160  */
 161 int rpmdsIx(/*@null@*/ const rpmds ds)
 162         /*@*/;
 163
 164 /**
 165  * Set dependency set index.
 166  * @param ds            dependency set
 167  * @param ix            new index
 168  * @return              current index
 169  */
 170 int rpmdsSetIx(/*@null@*/ rpmds ds, int ix)
 171         /*@modifies ds @*/;
 172
 173 /**
 174  * Return current formatted dependency string.
 175  * @param ds            dependency set
 176  * @return              current dependency DNEVR, NULL on invalid
 177  */
 178 /*@observer@*/ /*@null@*/
 179 extern const char * rpmdsDNEVR(/*@null@*/ const rpmds ds)
 180         /*@*/;
 181
 182 /**
 183  * Return current dependency name.
 184  * @param ds            dependency set
 185  * @return              current dependency name, NULL on invalid
 186  */
 187 /*@observer@*/ /*@null@*/
 188 extern const char * rpmdsN(/*@null@*/ const rpmds ds)
 189         /*@*/;
 190
 191 /**
 192  * Return current dependency epoch-version-release.
 193  * @param ds            dependency set
 194  * @return              current dependency EVR, NULL on invalid
 195  */
 196 /*@observer@*/ /*@null@*/
 197 extern const char * rpmdsEVR(/*@null@*/ const rpmds ds)
 198         /*@*/;
 199
 200 /**
 201  * Return current dependency flags.
 202  * @param ds            dependency set
 203  * @return              current dependency flags, 0 on invalid
 204  */
 205 int_32 rpmdsFlags(/*@null@*/ const rpmds ds)
 206         /*@*/;
 207
 208 /**
 209  * Return current dependency type.
 210  * @param ds            dependency set
 211  * @return              current dependency type, 0 on invalid
 212  */
 213 rpmTag rpmdsTagN(/*@null@*/ const rpmds ds)
 214         /*@*/;
 215
 216 /**
 217  * Return current "Don't promote Epoch:" flag.
 218  *
 219  * This flag controls for Epoch: promotion when a dependency set is
 220  * compared. If the flag is set (for already installed packages), then
 221  * an unspecified value will be treated as Epoch: 0. Otherwise (for added
 222  * packages), the Epoch: portion of the comparison is skipped if the value
 223  * is not specified, i.e. an unspecified Epoch: is assumed to be equal
 224  * in dependency comparisons.
 225  *
 226  * @param ds            dependency set
 227  * @return              current "Don't promote Epoch:" flag
 228  */
 229 int rpmdsNoPromote(/*@null@*/ const rpmds ds)
 230         /*@*/;
 231
 232 /**
 233  * Set "Don't promote Epoch:" flag.
 234  * @param ds            dependency set
 235  * @return              previous "Don't promote Epoch:" flag
 236  */
 237 int rpmdsSetNoPromote(/*@null@*/ const rpmds ds, int nopromote)
 238         /*@*/;
 239
 240 /**
 241  * Notify of results of dependency match.
 242  * @param ds            dependency set
 243  * @param where         where dependency was resolved (or NULL)
 244  * @param rc            0 == YES, otherwise NO
 245  */
 246 /*@-globuse@*/ /* FIX: rpmMessage annotation is a lie */
 247 void rpmdsNotify(/*@null@*/ rpmds ds, /*@null@*/ const char * where, int rc)
 248         /*@globals fileSystem @*/
 249         /*@modifies fileSystem @*/;
 250 /*@=globuse@*/
 251
 252 /**
 253  * Return next dependency set iterator index.
 254  * @param ds            dependency set
 255  * @return              dependency set iterator index, -1 on termination
 256  */
 257 int rpmdsNext(/*@null@*/ rpmds ds)
 258         /*@modifies ds @*/;
 259
 260 /**
 261  * Initialize dependency set iterator.
 262  * @param ds            dependency set
 263  * @return              dependency set
 264  */
 265 /*@null@*/
 266 rpmds rpmdsInit(/*@null@*/ rpmds ds)
 267         /*@modifies ds @*/;
 268
 269 /**
 270  * Compare two versioned dependency ranges, looking for overlap.
 271  * @param A             1st dependency
 272  * @param B             2nd dependency
 273  * @return              1 if dependencies overlap, 0 otherwise
 274  */
 275 int rpmdsCompare(const rpmds A, const rpmds B)
 276         /*@*/;
 277
 278 /**
 279  * Report a Requires: or Conflicts: dependency problem.
 280  * @param ps            transaction set problems
 281  * @param pkgNEVR       package name/epoch/version/release
 282  * @param ds            dependency set
 283  * @param suggestedKeys filename or python object address
 284  * @param adding        dependency problem is from added package set?
 285  */
 286 void rpmdsProblem(/*@null@*/ rpmps ps, const char * pkgNEVR, const rpmds ds,
 287                 /*@only@*/ /*@null@*/ const fnpyKey * suggestedKeys,
 288                 int adding)
 289         /*@modifies ps @*/;
 290
 291 /**
 292  * Compare package provides dependencies from header with a single dependency.
 293  * @param h             header
 294  * @param req           dependency set
 295  * @param nopromote     Don't promote Epoch: in comparison?
 296  * @return              1 if any dependency overlaps, 0 otherwise
 297  */
 298 int rpmdsAnyMatchesDep (const Header h, const rpmds req, int nopromote)
 299         /*@modifies h @*/;
 300
 301 /**
 302  * Compare package name-version-release from header with a single dependency.
 303  * @deprecated Remove from API when obsoletes is correctly implemented.
 304  * @param h             header
 305  * @param req           dependency set
 306  * @param nopromote     Don't promote Epoch: in comparison?
 307  * @return              1 if dependency overlaps, 0 otherwise
 308  */
 309 int rpmdsNVRMatchesDep(const Header h, const rpmds req, int nopromote)
 310         /*@*/;
 311
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 #endif  /* H_RPMDS */