Pileus Git - ~andy/fetchmail/blob - uid_db.h

   1 /*
   2   POP3 UID database
   3
   4         Copyright (c) 2010 MAD Partners, Ltd. (rweikusat@mssgmbh.com)
   5
   6         This file is being published in accordance with the GPLv2 terms
   7         contained in the COPYING file being part of the fetchmail
   8         6.3.17 release, including the OpenSSL exemption.
   9 */
  10 #ifndef fetchmail_uid_db_h
  11 #define fetchmail_uid_db_h
  12
  13 /*  includes */
  14 #include <stddef.h>
  15
  16 /*  types */
  17 struct uid_db_record {
  18     char *id;
  19     size_t id_len;
  20
  21     /*
  22       num       -       message number assigned by server
  23       status    -       message status (eg seen, deleted, ...)
  24       pos       -       position in record list
  25     */
  26     unsigned num, status, pos;
  27
  28     struct uid_db_record *next;
  29 };
  30
  31 struct num_ndx {
  32     /*
  33       Used to find uid records by message number.
  34
  35       pos_0_value       -       highest message number
  36       end_value         -       lowest known message number
  37
  38       Grows downwards because the fastuidl-code may record
  39       message numbers in non-ascending order but the
  40       lookup array should ideally only be large enough to
  41       store pointers to interesting ('new') messages.
  42     */
  43     struct uid_db_record **records;
  44     unsigned pos_0_value, end_value;
  45 };
  46
  47 struct uid_db
  48 {
  49     struct pat_node *pat_root;
  50
  51     struct uid_db_record **records;
  52     unsigned records_max, records_next;
  53
  54     struct num_ndx num_ndx;
  55 };
  56
  57 typedef int uid_db_traversal_routine(struct uid_db_record *, void *);
  58
  59 /*  routines */
  60 /**  initialization/ finalization */
  61 void init_uid_db(struct uid_db *db);
  62
  63 void free_uid_db(struct uid_db *db);
  64
  65 static inline void clear_uid_db(struct uid_db *db)
  66 {
  67     free_uid_db(db);
  68     init_uid_db(db);
  69 }
  70
  71 /**  message number index handling */
  72 static inline unsigned uid_db_num_ofs(struct num_ndx const *num_ndx, unsigned num)
  73 {
  74     return num_ndx->pos_0_value - num;
  75 }
  76
  77 void set_uid_db_num(struct uid_db *db, struct uid_db_record *rec,
  78                     unsigned num);
  79
  80 static inline void set_uid_db_num_pos_0(struct uid_db *db, unsigned num)
  81 {
  82     db->num_ndx.pos_0_value = num;
  83     db->num_ndx.end_value = num + 1;
  84 }
  85
  86 void reset_uid_db_nums(struct uid_db *db);
  87
  88 /**  various uidl db manipulatiors */
  89 struct uid_db_record *uid_db_insert(struct uid_db *db,
  90                                     char const *id, unsigned status);
  91
  92 void swap_uid_db_data(struct uid_db *db_0, struct uid_db *db_1);
  93
  94 /**  search routines */
  95 struct uid_db_record *find_uid_by_id(struct uid_db *db, char const *id);
  96
  97 static inline struct uid_db_record *
  98 find_uid_by_num(struct uid_db *db, unsigned num)
  99 {
 100     struct num_ndx *num_ndx;
 101
 102     num_ndx = &db->num_ndx;
 103     return num >= num_ndx->end_value ?
 104         num_ndx->records[uid_db_num_ofs(num_ndx, num)] : NULL;
 105 }
 106
 107 static inline struct uid_db_record *
 108 find_uid_by_pos(struct uid_db *db, unsigned pos)
 109 {
 110     return pos < db->records_next ? db->records[pos] : NULL;
 111 }
 112
 113 static inline struct uid_db_record *
 114 first_uid_in_db(struct uid_db *db, char const *id)
 115 {
 116     return find_uid_by_id(db, id);
 117 }
 118
 119 struct uid_db_record *last_uid_in_db(struct uid_db *db, char const *id);
 120
 121 /**  various accessors */
 122 static inline unsigned uid_db_n_records(struct uid_db const *db)
 123 {
 124     return db->records_next;
 125 }
 126
 127 /*
 128   Traverses the struct uid_db records array in insert order,
 129   invoking the subroutine pointed to by r with a pointer to
 130   each record and the arg pointer as arguments. If the return
 131   value of that is non-zero, traverse_uid_db immediately returns
 132   with this value. Otherwise, zero is returned after the last
 133   record was visited.
 134
 135   The uid_db_traversal_routine must not modify the uid_db during
 136   traversal.
 137 */
 138 int traverse_uid_db(struct uid_db *db,
 139                     uid_db_traversal_routine *r, void *arg);
 140
 141 #endif