pith/adrbklib.h

   1 /*
   2  * $Id: adrbklib.h 1012 2008-03-26 00:44:22Z hubert@u.washington.edu $
   3  *
   4  * ========================================================================
   5  * Copyright 2006-2008 University of Washington
   6  * Copyright 2013-2017 Eduardo Chappa
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * ========================================================================
  15  */
  16
  17 #ifndef PITH_ADRBKLIB_INCLUDED
  18 #define PITH_ADRBKLIB_INCLUDED
  19
  20
  21 #include "../pith/indxtype.h"
  22 #include "../pith/remtype.h"
  23 #include "../pith/store.h"
  24 #include "../pith/string.h"
  25
  26
  27 /*
  28  *  Some notes:
  29  *
  30  * The order that the address book is stored in on disk is the order that
  31  * the entries will be displayed in. When an address book is opened,
  32  * if it is ReadWrite the sort order is checked and it is sorted if it is
  33  * out of order.
  34  *
  35  * Considerable complexity that previously existed in the address book
  36  * code has been removed. Cpu speeds have improved significantly and
  37  * memory has increased dramatically, as well. The cost of the complexity
  38  * of the lookup file and hashtables and all that stuff is thought to be
  39  * more than the benefits. See pre-5.00 pine adrbklib.h for the way it
  40  * used to be.
  41  *
  42  * The display code has remained the same.
  43  * There is also some allocation happening
  44  * in addrbook.c. In particular, the display is a window into an array
  45  * of rows, at least one row per addrbook entry plus more for lists.
  46  * Each row is an AddrScrn_Disp structure and those should typically take
  47  * up 6 or 8 bytes. A cached copy of addrbook entries is not kept, just
  48  * the element number to look it up (and often get it out of the EntryRef
  49  * cache). In order to avoid having to allocate all those rows, this is
  50  * also in the form of a cache. Only 3 * screen_length rows are kept in
  51  * the cache, and the cache is always a simple interval of rows. That is,
  52  * rows between valid_low and valid_high are all in the cache. Row numbers
  53  * in the display list are a little mysterious. There is no origin. That
  54  * is, you don't necessarily know where the start or end of the display
  55  * is. You only know how to go forward and backward and how to "warp"
  56  * to new locations in the display and go forward and backward from there.
  57  * This is because we don't know how many rows there are all together. It
  58  * is also a way to avoid searching through everything to get somewhere.
  59  * If you want to go to the End, you warp there and start backwards instead
  60  * of reading through all the entries to get there. If you edit an entry
  61  * so that it sorts into a new location, you warp to that new location to
  62  * save processing all of the entries in between.
  63  *
  64  *
  65  * Notes about RFC1522 encoding:
  66  *
  67  * If the fullname field contains other than US-ASCII characters, it is
  68  * encoded using the rules of RFC1522 or its successor. The value actually
  69  * stored in the file is encoded, even if it matches the character set of
  70  * the user. This is so it is easy to pass the entry around or to change
  71  * character sets without invalidating entries in the address book. When
  72  * a fullname is displayed, it is first decoded. If the fullname field is
  73  * encoded as being from a character set other than the user's character
  74  * set, that will be retained until the user edits the field. Then it will
  75  * change over to the user's character set. The comment field works in
  76  * the same way, as do the "phrase" fields of any addresses. On outgoing
  77  * mail, the correct character set will be retained if you use ComposeTo
  78  * from the address book screen. However, if you use a nickname from the
  79  * composer or ^T from the composer, the character set will be lost if it
  80  * is different from the user's character set.
  81  *
  82  *
  83  * Notes about RemoteViaImap address books:
  84  *
  85  * There are currently two types of address books, Local and Imap. Local means
  86  * it is in a local file. Imap means it is stored in a folder on a remote
  87  * IMAP server. The folder is a regular folder containing mail messages but
  88  * the messages are special. The first message is a header message. The last
  89  * message is the address book data. In between messages are old versions of
  90  * the address book data. The address book data is stored in the message as
  91  * it would be on disk, with no fancy mime encoding or anything. When it is
  92  * used the data from the last message in the folder is copied to a local file
  93  * and then it is used just like a local file. The local file is a cache for
  94  * the remote data. We can tell the remote data has been changed by looking
  95  * at the Date of the last message in the remote folder. If we see it has
  96  * changed we copy the whole file over again and replace the cache file.
  97  * A possibly quicker way to tell if it has changed is if the UID has
  98  * changed or the number of messages in the folder has changed. We use those
  99  * methods if possible since they don't require opening a new stream and
 100  * selecting the folder.  There is one metadata file for address book data.
 101  * The name of that file is stored in the pinerc file. It contains the names
 102  * of the cache files for RemoveViaImap address books plus other caching
 103  * information for those address books (uid...).
 104  */
 105
 106 #define NFIELDS 11 /* one more than num of data fields in addrbook entry */
 107
 108 /*
 109  * The type a_c_arg_t is a little confusing. It's the type we use in
 110  * place of adrbk_cntr_t when we want to pass an adrbk_cntr_t in an argument.
 111  * We were running into problems with the integral promotion of adrbk_cntr_t
 112  * args. A_c_arg_t has to be large enough to hold a promoted adrbk_cntr_t.
 113  * So, if adrbk_cntr_t is unsigned short, then a_c_arg_t needs to be int if
 114  * int is larger than short, or unsigned int if short is same size as int.
 115  * Since usign16_t always fits in a short, a_c_arg_t of unsigned int should
 116  * always work for !HUGE. For HUGE, UINT32 will be either an unsigned int
 117  * or an unsigned long. If it is an unsigned long, then a_c_arg_t better be
 118  * an unsigned long, too. If it is an unsigned int, then a_c_arg_t could
 119  * be an unsigned int, too. However, if we just make it unsigned long, then
 120  * it will be the same in all cases and big enough in all cases.
 121  */
 122
 123 #define adrbk_cntr_t UINT32  /* addrbook counter type                */
 124 typedef unsigned long a_c_arg_t;     /* type of arg passed for adrbk_cntr_t  */
 125 #define NO_NEXT ((adrbk_cntr_t)-1)
 126 #define MAX_ADRBK_SIZE (2000000000L) /* leave room for extra display lines   */
 127
 128 /*
 129  * The value NO_NEXT is reserved to mean that there is no next address, or that
 130  * there is no address number to return. This is similar to getc returning
 131  * -1 when there is no char to get, but since we've defined this to be
 132  * unsigned we need to reserve one of the valid values for this purpose.
 133  * With current implementation it needs to be all 1's, so memset initialization
 134  * will work correctly.
 135  */
 136
 137 typedef enum {NotSet, Single, List} Tag;
 138
 139
 140 /* This is what is actually used by the routines that manipulate things */
 141 typedef struct adrbk_entry {
 142     char *nickname;    /* UTF-8                                         */
 143     char *fullname;    /* of simple addr or list (stored in UTF-8)      */
 144     union addr {
 145         char *addr;    /* for simple Single entries                     */
 146         char **list;   /* for distribution lists                        */
 147     } addr;
 148     char *fcc;         /* fcc specific for when sending to this address */
 149     char *extra;       /* comments field (stored in UTF-8)              */
 150     char  referenced;  /* for detecting loops during lookup             */
 151     Tag   tag;         /* single addr (Single) or a list (List)         */
 152 } AdrBk_Entry;
 153
 154
 155 typedef struct abook_tree_node {
 156     struct abook_tree_node *down;       /* next letter of nickname */
 157     struct abook_tree_node *right;      /* alternate letter of nickname */
 158     char                    value;      /* character at this node */
 159     adrbk_cntr_t            entrynum;   /* use NO_NEXT as no-data indicator */
 160 } AdrBk_Trie;
 161
 162
 163 /* information useful for displaying the addrbook */
 164 typedef struct width_stuff {
 165     int max_nickname_width;
 166     int max_fullname_width;
 167     int max_addrfield_width;
 168     int max_fccfield_width;
 169     int third_biggest_fullname_width;
 170     int third_biggest_addrfield_width;
 171     int third_biggest_fccfield_width;
 172 } WIDTH_INFO_S;
 173
 174
 175 typedef struct expanded_list {
 176     adrbk_cntr_t          ent;
 177     struct expanded_list *next;
 178 } EXPANDED_S;
 179
 180
 181 typedef enum {Local, Imap} AdrbkType;
 182
 183
 184 #ifndef IMAP_IDLE_TIMEOUT
 185 #define IMAP_IDLE_TIMEOUT       (10L * 60L)     /* seconds */
 186 #endif
 187 #ifndef FILE_VALID_CHK_INTERVAL
 188 #define FILE_VALID_CHK_INTERVAL (      15L)     /* seconds */
 189 #endif
 190 #ifndef LOW_FREQ_CHK_INTERVAL
 191 #define LOW_FREQ_CHK_INTERVAL   (240)           /* minutes */
 192 #endif
 193
 194 typedef struct adrbk {
 195     AdrbkType     type;                /* type of address book               */
 196     char         *orig_filename;       /* passed in filename                 */
 197     char         *filename;            /* addrbook filename                  */
 198     char         *our_filecopy;        /* session copy of filename contents  */
 199     FILE         *fp;                  /* fp for our_filecopy                */
 200     adrbk_cntr_t  count;               /* how many entries in addrbook       */
 201     adrbk_cntr_t  del_count;           /* how many #DELETED entries in abook */
 202     AdrBk_Entry  *arr;                 /* array of entries                   */
 203     AdrBk_Entry  *del;                 /* array of deleted entries           */
 204     AdrBk_Trie   *nick_trie;
 205     AdrBk_Trie   *addr_trie;
 206     AdrBk_Trie   *full_trie;
 207     AdrBk_Trie   *revfull_trie;
 208     time_t        last_change_we_know_about;/* to look for others changing it*/
 209     time_t        last_local_valid_chk;/* when valid check was done          */
 210     unsigned      flags;               /* see defines in alpine.h (DEL_FILE...)*/
 211     WIDTH_INFO_S  widths;              /* helps addrbook.c format columns    */
 212     int           sort_rule;
 213     EXPANDED_S   *exp;                 /* this is for addrbook.c to use.  A
 214                                list of expanded list entry nums is kept here */
 215     EXPANDED_S   *checks;              /* this is for addrbook.c to use.  A
 216                                list of checked entry nums is kept here */
 217     EXPANDED_S   *selects;             /* this is for addrbook.c to use.  A
 218                                list of selected entry nums is kept here */
 219     REMDATA_S    *rd;
 220 } AdrBk;
 221
 222
 223 /*
 224  * The definitions starting here have to do with the virtual scrolling
 225  * region view into the addressbooks. That is, the display.
 226  *
 227  * We could make every use of an AdrBk_Entry go through a function call
 228  * like adrbk_get_ae(). Instead, we try to be smart and avoid the extra
 229  * function calls by knowing when the addrbook entry is still valid, either
 230  * because we haven't called any functions that could invalidate it or because
 231  * we have locked it in the cache. If we do lock it, we need to be careful
 232  * that it eventually gets unlocked. That can be done by an explicit
 233  * adrbk_get_ae(Unlock) call, or it is done implicitly when the address book
 234  * is written out. The reason it can get invalidated is that the abe that
 235  * we get returned to us is just a pointer to a cached addrbook entry, and
 236  * that entry can be flushed from the cache by other addrbook activity.
 237  * So we need to be careful to make sure the abe is certain to be valid
 238  * before using it.
 239  *
 240  * Data structures for the display of the address book. There's one
 241  * of these structures per line on the screen.
 242  *
 243  * Types: Title -- The title line for the different address books. It has
 244  *                 a ptr to the text of the Title line.
 245  * ClickHereCmb -- This is the line that says to click here to
 246  *                 expand.  It changes types into the individual expanded
 247  *                 components once it is expanded.  It doesn't have any data
 248  *                 other than an implicit title. This is only used with the
 249  *                 combined-style addrbook display.
 250  * ListClickHere --This is the line that says to click here to
 251  *                 expand the members of a distribution list. It changes
 252  *                 types into the individual expanded ListEnt's (if any)
 253  *                 when it is expanded. It has a ptr to an AdrBk_Entry.
 254  *    ListEmpty -- Line that says this is an empty distribution list. No data.
 255  *        Empty -- Line that says this is an empty addressbook. No data.
 256  *    ZoomEmpty -- Line that says no addrs in zoomed view. No data.
 257  * AddFirstGLob -- Place holder for adding an abook. No data.
 258  * AddFirstPers -- Place holder for adding an abook. No data.
 259  *   DirServers -- Place holder for accessing directory servers. No data.
 260  *       Simple -- A single addressbook entry. It has a ptr to an AdrBk_Entry.
 261  *                 When it is displayed, the fields are usually:
 262  *                 <nickname>       <fullname>       <address or another nic>
 263  *     ListHead -- The head of an address list. This has a ptr to an
 264  *                 AdrBk_Entry.
 265  *                 <blank line> followed by
 266  *                 <nickname>       <fullname>       "DISTRIBUTION LIST:"
 267  *      ListEnt -- The rest of an address list. It has a pointer to its
 268  *                 ListHead element and a ptr (other) to this specific address
 269  *                 (not a ptr to another AdrBk_Entry).
 270  *                 <blank>          <blank>          <address or another nic>
 271  *         Text -- A ptr to text. For example, the ----- lines and
 272  *                 whitespace lines.
 273  *    NoAbooks  -- There are no address books at all.
 274  *   Beginnning -- The (imaginary) elements before the first real element
 275  *          End -- The (imaginary) elements after the last real element
 276  */
 277 typedef enum {DlNotSet, Empty, ZoomEmpty, AddFirstPers, AddFirstGlob,
 278               AskServer, Title, Simple, ListHead, ListClickHere,
 279               ListEmpty, ListEnt, Text, Beginning, End, NoAbooks,
 280               ClickHereCmb, TitleCmb} LineType;
 281 /* each line of address book display is one of these structures */
 282 typedef struct addrscrn_disp {
 283     union {
 284         struct {
 285             adrbk_cntr_t  ab_element_number; /* which addrbook entry     */
 286             adrbk_cntr_t  ab_list_offset;    /* which member of the list */
 287         }addrbook_entry;
 288         char        *text_ptr;               /* a UTF-8 string */
 289     }union_to_save_space;
 290     LineType       type;
 291 } AddrScrn_Disp;
 292 #define usst union_to_save_space.text_ptr
 293 #define elnum union_to_save_space.addrbook_entry.ab_element_number
 294 #define l_offset union_to_save_space.addrbook_entry.ab_list_offset
 295
 296 #define entry_is_checked    exp_is_expanded
 297 #define entry_get_next      exp_get_next
 298 #define entry_set_checked   exp_set_expanded
 299 #define entry_unset_checked exp_unset_expanded
 300 #define any_checked         exp_any_expanded
 301 #define howmany_checked     exp_howmany_expanded
 302
 303 #define entry_is_selected   exp_is_expanded
 304 #define entry_set_selected  exp_set_expanded
 305 #define entry_unset_selected exp_unset_expanded
 306 #define any_selected        exp_any_expanded
 307 #define howmany_selected    exp_howmany_expanded
 308
 309 #define entry_is_deleted    exp_is_expanded
 310 #define entry_set_deleted   exp_set_expanded
 311 #define howmany_deleted     exp_howmany_expanded
 312
 313 #define entry_is_added      exp_is_expanded
 314 #define entry_set_added     exp_set_expanded
 315
 316 /*
 317  * Argument to expand_address and build_address_internal is a BuildTo,
 318  * which is either a char * address or an AdrBk_Entry * (if we have already
 319  * looked it up in an addrbook).
 320  */
 321 typedef enum {Str, Abe} Build_To_Arg_Type;
 322 typedef struct build_to {
 323     Build_To_Arg_Type type;
 324     union {
 325         char        *str;  /* normal looking address string */
 326         AdrBk_Entry *abe;  /* addrbook entry */
 327     }arg;
 328 } BuildTo;
 329
 330
 331 /* Display lines used up by each top-level addrbook, counting blanks */
 332 #define LINES_PER_ABOOK (3)
 333 /* How many of those lines are visible (not blank) */
 334 #define VIS_LINES_PER_ABOOK (2)
 335 /* How many extra lines are between the personal and global sections */
 336 #define XTRA_LINES_BETWEEN (1)
 337 /* How many lines does the PerAdd line take, counting blank line */
 338 #define LINES_PER_ADD_LINE (2)
 339 /* Extra title lines above first entry that are shown when the combined-style
 340    display is turned on. */
 341 #define XTRA_TITLE_LINES_IN_OLD_ABOOK_DISP (4)
 342
 343 typedef enum {DlcNotSet,
 344               DlcPersAdd,               /* config screen only */
 345               DlcGlobAdd,               /*    "      "    "   */
 346
 347               DlcTitle,                 /* top level displays */
 348               DlcTitleNoPerm,           /*  "    "      "     */
 349               DlcSubTitle,              /*  "    "      "     */
 350               DlcTitleBlankTop,         /*  "    "      "     */
 351               DlcGlobDelim1,            /*  "    "      "     */
 352               DlcGlobDelim2,            /*  "    "      "     */
 353               DlcDirDelim1,             /*  "    "      "     */
 354               DlcDirDelim2,             /*  "    "      "     */
 355               DlcDirAccess,             /*  "    "      "     */
 356               DlcDirSubTitle,           /*  "    "      "     */
 357               DlcDirBlankTop,           /*  "    "      "     */
 358
 359               DlcTitleDashTopCmb,       /* combined-style top level display */
 360               DlcTitleCmb,              /*     "      "    "    "      "    */
 361               DlcTitleDashBottomCmb,    /*     "      "    "    "      "    */
 362               DlcTitleBlankBottomCmb,   /*     "      "    "    "      "    */
 363               DlcClickHereCmb,          /*     "      "    "    "      "    */
 364               DlcTitleBlankTopCmb,      /*     "      "    "    "      "    */
 365               DlcDirDelim1a,            /*     "      "    "    "      "    */
 366               DlcDirDelim1b,            /*     "      "    "    "      "    */
 367               DlcDirDelim1c,            /*     "      "    "    "      "    */
 368
 369               DlcEmpty,                 /* display of a single address book */
 370               DlcZoomEmpty,             /*    "                             */
 371               DlcNoPermission,          /*    "                             */
 372               DlcSimple,                /*    "                             */
 373               DlcListHead,              /*    "                             */
 374               DlcListClickHere,         /*    "                             */
 375               DlcListEmpty,             /*    "                             */
 376               DlcListEnt,               /*    "                             */
 377               DlcListBlankTop,          /*    "                             */
 378               DlcListBlankBottom,       /*    "                             */
 379               DlcNoAbooks,              /*    "                             */
 380
 381               DlcOneBeforeBeginning,    /* used in both */
 382               DlcTwoBeforeBeginning,    /*  "   "   "   */
 383               DlcBeginning,             /*  "   "   "   */
 384               DlcEnd} DlCacheType;
 385
 386 typedef enum {Initialize, FirstEntry, LastEntry, ArbitraryStartingPoint,
 387               DoneWithCache, FlushDlcFromCache, Lookup} DlMgrOps;
 388 typedef enum {Warp, DontWarp} HyperType;
 389
 390 /*
 391  * The DlCacheTypes are the types that a dlcache element can be labeled.
 392  * The idea is that there needs to be enough information in the single
 393  * cache element by itself so that you can figure out what the next and
 394  * previous dl rows are by just knowing this one row.
 395  *
 396  * In the top-level display, there are DlcTitle lines or DlcTitleNoPerm
 397  * lines, which are the same except we know that we can't access the
 398  * address book in the latter case. DlcSubTitle lines follow each of the
 399  * types of Title lines, and Titles within a section are separated by
 400  * DlcTitleBlankTop lines, which belong to (have the same adrbk_num as)
 401  * the Title they are above.
 402  * If there are no address books and no directory servers defined, we
 403  * have a DlcNoAbooks line. When we are displaying an individual address
 404  * book (not in the top-level display) there is another set of types. An
 405  * empty address book consists of one line of type DlcEmpty. An address
 406  * book without read permission is a DlcNoPermission. Simple address book
 407  * entries consist of a single DlcSimple line. Lists begin with a
 408  * DlcListHead. If the list is not expanded the DlcListHead is followed by
 409  * a DlcListClickHere. If it is known to be a list with no members the
 410  * DlcListHead is followed by a DlcListEmpty. If there are members and
 411  * the list is expanded, each list member is a single line of type
 412  * DlcListEnt. Two lists are separated by a DlcListBlankBottom belonging
 413  * to the first list. A list followed or preceded by a DlcSimple address
 414  * row has a DlcListBlank(Top or Bottom) separating it from the
 415  * DlcSimple. Above the top row of the display is an imaginary line of
 416  * type DlcOneBeforeBeginning. Before that is a DlcTwoBeforeBeginning. And
 417  * before that all the lines are just DlcBeginning lines. After the last
 418  * display line is a DlcEnd.
 419  *
 420  * The DlcDirAccess's are indexed by adrbk_num (re-used for this).
 421  * Adrbk_num -1 means access all of the servers.
 422  * Adrbk_num 0 ... n_serv -1 means access all a particular server.
 423  * Adrbk_num n_serv means access as if from composer using config setup.
 424  *
 425  * Here are the types of lines and where they fall in the top-level display:
 426  *
 427  * (not a visible line)                 DlcBeginning
 428  * (not a visible line)                 DlcBeginning
 429  * (not a visible line)                 DlcTwoBeforeBeginning
 430  * (not a visible line)                 DlcOneBeforeBeginning
 431  *     Title                            DlcTitle (or TitleNoPerm)
 432  *       Subtitle                       DlcSubTitle
 433  * ---this is blank----------------     DlcTitleBlankTop
 434  *     Title                            DlcTitle (or TitleNoPerm)
 435  *       Subtitle                       DlcSubTitle
 436  * ---this is blank----------------     DlcGlobDelim1
 437  * ---this is blank----------------     DlcGlobDelim2
 438  *     Title                            DlcTitle (or TitleNoPerm)
 439  *       Subtitle                       DlcSubTitle
 440  * ---this is blank----------------     DlcTitleBlankTop
 441  *     Title                            DlcTitle (or TitleNoPerm)
 442  *       Subtitle                       DlcSubTitle
 443  * ---this is blank----------------     DlcDirDelim1
 444  * ---this is blank----------------     DlcDirDelim2
 445  *     Directory (query server 1)       DlcDirAccess (adrbk_num 0)
 446  *       Subtitle                       DlcDirSubTitle (adrbk_num 0)
 447  * ---this is blank----------------     DlcDirBlankTop
 448  *     Directory (query server 2)       DlcDirAccess (adrbk_num 1)
 449  *       Subtitle                       DlcDirSubTitle (adrbk_num 1)
 450  * (not a visible line)                 DlcEnd
 451  * (not a visible line)                 DlcEnd
 452  *
 453  *
 454  * There is a combined-style display triggered by the F_CMBND_ABOOK_DISP
 455  * feature. It's a mixture of the top-level and open addrbook displays. When an
 456  * addrbook is opened the rest of the addrbooks don't disappear from the
 457  * screen. In this view, the ClickHere lines can be replaced with the entire
 458  * contents of the addrbook, but the other stuff remains on the screen, too.
 459  * Here are the types of lines and where they fall in the
 460  * combined-style display:
 461  *
 462  * (not a visible line)                 DlcBeginning
 463  * (not a visible line)                 DlcBeginning
 464  * (not a visible line)                 DlcTwoBeforeBeginning
 465  * (not a visible line)                 DlcOneBeforeBeginning
 466  * --------------------------------     DlcTitleDashTopOld
 467  *     Title                            DlcTitleOld
 468  * --------------------------------     DlcTitleDashBottomOld
 469  * ---this is blank----------------     DlcTitleBlankBottom
 470  *     ClickHere                        DlcClickHereOld
 471  * ---this is blank----------------     DlcTitleBlankTop
 472  * --------------------------------     DlcTitleDashTopOld
 473  *     Title                            DlcTitleOld
 474  * --------------------------------     DlcTitleDashBottomOld
 475  * ---this is blank----------------     DlcTitleBlankBottom
 476  *     ClickHere                        DlcClickHereOld
 477  * ---this is blank----------------     DlcDirDelim1
 478  * --------------------------------     DlcDirDelim1a
 479  * Directories                          DlcDirDelim1b
 480  * --------------------------------     DlcDirDelim1c
 481  * ---this is blank----------------     DlcDirDelim2
 482  *     Directory (query server 1)       DlcDirAccess (adrbk_num 0)
 483  *       Subtitle                       DlcDirSubTitle (adrbk_num 0)
 484  * ---this is blank----------------     DlcDirBlankTop
 485  *     Directory (query server 2)       DlcDirAccess (adrbk_num 1)
 486  *       Subtitle                       DlcDirSubTitle (adrbk_num 1)
 487  * (not a visible line)                 DlcEnd
 488  * (not a visible line)                 DlcEnd
 489  *
 490  * If there are no addrbooks in either of the two sections, or no Directory
 491  * servers, then that section is left out of the display. If there is only
 492  * one address book and no Directories, then the user goes directly into the
 493  * single addressbook view which looks like:
 494  *
 495  * if(no entries in addrbook)
 496  *
 497  * (not a visible line)                 DlcBeginning
 498  * (not a visible line)                 DlcBeginning
 499  * (not a visible line)                 DlcTwoBeforeBeginning
 500  * (not a visible line)                 DlcOneBeforeBeginning
 501  *     Empty or NoPerm or NoAbooks      DlcEmpty, DlcZoomEmpty, DlcNoPermission,
 502  *                                      or DlcNoAbooks
 503  * (not a visible line)                 DlcEnd
 504  * (not a visible line)                 DlcEnd
 505  *
 506  * else
 507  *
 508  * (not a visible line)                 DlcBeginning
 509  * (not a visible line)                 DlcBeginning
 510  * (not a visible line)                 DlcTwoBeforeBeginning
 511  * (not a visible line)                 DlcOneBeforeBeginning
 512  *     Simple Entry                     DlcSimple
 513  *     Simple Entry                     DlcSimple
 514  *     Simple Entry                     DlcSimple
 515  *                                      DlcListBlankTop
 516  *     List Header                      DlcListHead
 517  *          Unexpanded List             DlcListClickHere
 518  *          or
 519  *          Empty List                  DlcListEmpty
 520  *          or
 521  *          List Entry 1                DlcListEnt
 522  *          List Entry 2                DlcListEnt
 523  *                                      DlcListBlankBottom
 524  *     List Header                      DlcListHead
 525  *          List Entry 1                DlcListEnt
 526  *          List Entry 2                DlcListEnt
 527  *          List Entry 3                DlcListEnt
 528  *                                      DlcListBlankBottom
 529  *     Simple Entry                     DlcSimple
 530  *                                      DlcListBlankTop
 531  *     List Header                      DlcListHead
 532  *          Unexpanded List             DlcListClickHere
 533  * (not a visible line)                 DlcEnd
 534  * (not a visible line)                 DlcEnd
 535  *
 536  * The config screen view is similar to the top-level view except there
 537  * is no directory section (it has it's own config screen) and if there
 538  * are zero personal addrbooks or zero global addrbooks then a placeholder
 539  * line of type DlcPersAdd or DlcGlobAdd takes the place of the DlcTitle
 540  * line.
 541  */
 542 typedef struct dl_cache {
 543     long         global_row; /* disp_list row number */
 544     adrbk_cntr_t dlcelnum;   /* which elnum from that addrbook */
 545     adrbk_cntr_t dlcoffset;  /* offset in a list, only for ListEnt rows */
 546     short        adrbk_num;  /* which address book we're related to */
 547     DlCacheType  type;       /* type of this row */
 548     AddrScrn_Disp dl;        /* the actual dl that goes with this row */
 549 } DL_CACHE_S;
 550
 551
 552 typedef enum {Nickname, Fullname, Addr, Filecopy, Comment, Notused,
 553               Def, WhenNoAddrDisplayed, Checkbox, Selected} ColumnType;
 554
 555 /*
 556  * Users can customize the addrbook display, so this tells us which data
 557  * is in a particular column and how wide the column is. There is an
 558  * array of these per addrbook, of length NFIELDS (number of possible cols).
 559  */
 560 typedef struct column_description {
 561     ColumnType type;
 562     WidthType  wtype;
 563     int        req_width; /* requested width (for fixed and percent types) */
 564     int        width;     /* actual width to use */
 565     int        old_width;
 566 } COL_S;
 567
 568
 569 /* address book attributes for peraddrbook type */
 570 #define GLOBAL          0x1     /* else it is personal */
 571 #define REMOTE_VIA_IMAP 0x2     /* else it is a local file  */
 572
 573
 574 typedef enum {TotallyClosed, /* hash tables not even set up yet               */
 575               Closed,     /* data not read in, no display list                */
 576               NoDisplay,  /* data is accessible, no display list              */
 577               HalfOpen,   /* data not accessible, initial display list is set */
 578               ThreeQuartOpen, /* like HalfOpen without partial_close          */
 579               Open        /* data is accessible and display list is set       */
 580              } OpenStatus;
 581
 582 /*
 583  * There is one of these per addressbook.
 584  */
 585 typedef struct peraddrbook {
 586     unsigned            type;
 587     AccessType          access;
 588     OpenStatus          ostatus;
 589     char               *abnick,              /* kept internally in UTF-8 */
 590                        *filename;
 591     AdrBk              *address_book;        /* the address book handle */
 592     int                 gave_parse_warnings;
 593     COL_S               disp_form[NFIELDS];  /* display format */
 594     int                 nick_is_displayed;   /* these are for convenient, */
 595     int                 full_is_displayed;   /* fast access.  Could get   */
 596     int                 addr_is_displayed;   /* same info from disp_form. */
 597     int                 fcc_is_displayed;
 598     int                 comment_is_displayed;
 599     STORE_S            *so;                  /* storage obj for addrbook
 600                                                 temporarily stored here   */
 601 } PerAddrBook;
 602
 603
 604 /*
 605  * This keeps track of the state of the screen and information about all
 606  * the address books. We usually only have one of these but sometimes
 607  * we save a version of this state (with save_state) and re-call the
 608  * address book functions. Then when we pop back up to where we were
 609  * (with restore_state) the screen and the state of the address books
 610  * is restored to what it was.
 611  */
 612 typedef struct addrscreenstate {
 613     PerAddrBook   *adrbks;       /* array of addrbooks                    */
 614     int            initialized,  /* have we done at least simple init?    */
 615                    n_addrbk,     /* how many addrbooks are there          */
 616                    how_many_personals, /* how many of those are personal? */
 617                    cur,          /* current addrbook                      */
 618                    cur_row,      /* currently selected line               */
 619                    old_cur_row,  /* previously selected line              */
 620                    l_p_page;     /* lines per (screen) page               */
 621     long           top_ent;      /* index in disp_list of top entry on screen */
 622     int            ro_warning,   /* whether or not to give warning        */
 623                    checkboxes,   /* whether or not to display checkboxes  */
 624                    selections,   /* whether or not to display selections  */
 625                    do_bold,      /* display selections in bold            */
 626                    no_op_possbl, /* user can't do anything with current conf */
 627                    zoomed,       /* zoomed into view only selected entries */
 628                    config,       /* called from config screen             */
 629                    n_serv,       /* how many directory servers are there  */
 630                    n_impl;       /* how many of those have impl bit set   */
 631 #ifdef  _WINDOWS
 632     long           last_ent;     /* index of last known entry             */
 633 #endif
 634 } AddrScrState;
 635
 636
 637 /*
 638  * AddrBookScreen and AddrBookConfig are the maintenance screens, all the
 639  * others are selection screens. The AddrBookConfig screen is an entry
 640  * point from the Setup/Addressbooks command in the main menu. Those that
 641  * end in Com are called from the pico HeaderEditor, either while in the
 642  * composer or while editing an address book entry.  SelectManyNicks
 643  * returns a comma-separated list of nicknames. SelectAddrLccCom and
 644  * SelectNicksCom return a comma-separated list of nicknames.
 645  * SelectNickTake, SelectNickCom, and SelectNick all return a single
 646  * nickname.  The ones that returns multiple nicknames or multiple
 647  * addresses all allow ListMode. They are SelectAddrLccCom,
 648  * SelectNicksCom, and SelectMultNoFull.
 649  */
 650 typedef enum {AddrBookScreen,      /* maintenance screen                     */
 651               AddrBookConfig,      /* config screen                          */
 652               SelectAddrLccCom,    /* returns list of nicknames of lists     */
 653               SelectNicksCom,      /* just like SelectAddrLccCom, but allows
 654                                       selecting simple *and* list entries    */
 655               SelectNick,          /* returns single nickname                */
 656               SelectNickTake,      /* Same as SelectNick but different help  */
 657               SelectNickCom,       /* Same as SelectNick but from composer   */
 658               SelectManyNicks,     /* Returns list of nicks */
 659               SelectAddr,          /* Returns single address */
 660               SelectAddrNoFull,    /* Returns single address without fullname */
 661               SelectMultNoFull     /* Returns mult addresses without fullname */
 662              } AddrBookArg;
 663
 664
 665 typedef struct save_state_struct {
 666     AddrScrState *savep;
 667     OpenStatus   *stp;
 668     DL_CACHE_S   *dlc_to_warp_to;
 669 } SAVE_STATE_S;
 670
 671
 672 typedef struct act_list {
 673     PerAddrBook *pab;
 674     adrbk_cntr_t num,
 675                  num_in_dst;
 676     unsigned int skip:1,
 677                  dup:1;
 678 } ACTION_LIST_S;
 679
 680
 681 typedef struct ta_abook_state {
 682     PerAddrBook  *pab;
 683     SAVE_STATE_S  state;
 684 } TA_STATE_S;
 685
 686
 687 /*
 688  * Many of these should really only have a single value but we give them
 689  * an array for uniformity.
 690  */
 691 typedef struct _vcard_info {
 692     char **nickname;
 693     char **fullname;
 694     char  *first;
 695     char  *middle;
 696     char  *last;
 697     char **fcc;
 698     char **note;
 699     char **title;
 700     char **tel;
 701     char **email;
 702 } VCARD_INFO_S;
 703
 704
 705 extern AddrScrState as;
 706 extern jmp_buf      addrbook_changed_unexpectedly;
 707 extern long         msgno_for_pico_callback;
 708 extern BODY        *body_for_pico_callback;
 709 extern ENVELOPE    *env_for_pico_callback;
 710 extern int          ab_nesting_level;
 711
 712
 713 /*
 714  * These constants are supposed to be suitable for use as longs where the longs
 715  * are representing a line number or message number.
 716  * These constants aren't suitable for use with type adrbk_cntr_t. There is
 717  * a constant called NO_NEXT which you probably want for that.
 718  */
 719 #define NO_LINE         (2147483645L)
 720 #define CHANGED_CURRENT (NO_LINE + 1L)
 721
 722
 723 /*
 724  * The do-while stuff is so these are statements and can be written with
 725  * a following ; like a regular statement without worrying about braces and all.
 726  */
 727 #define SKIP_SPACE(p) do{while(*p && *p == SPACE)p++;}while(0)
 728 #define SKIP_TO_TAB(p) do{while(*p && *p != TAB)p++;}while(0)
 729 #define RM_END_SPACE(start,end)                                             \
 730             do{char *_ptr = end;                                            \
 731                while(--_ptr >= start && *_ptr == SPACE)*_ptr = '\0';}while(0)
 732 #define REPLACE_NEWLINES_WITH_SPACE(p)                                      \
 733                 do{register char *_qq;                                      \
 734                    for(_qq = p; *_qq; _qq++)                                \
 735                        if(*_qq == '\n' || *_qq == '\r')                     \
 736                            *_qq = SPACE;}while(0)
 737 #define DELETED "#DELETED-"
 738 #define DELETED_LEN 9
 739
 740
 741 #define ONE_HUNDRED_DAYS (60L * 60L * 24L * 100L)
 742
 743 /*
 744  * When address book entries are deleted, they are left in the file
 745  * with the nickname prepended with a string like #DELETED-96/01/25#,
 746  * which stands for year 96, month 1, day 25 of the month. When one of
 747  * these entries is more than ABOOK_DELETED_EXPIRE_TIME seconds old,
 748  * then it will be totally removed from the address book the next time
 749  * an adrbk_write() is done. This is for emergencies where somebody
 750  * deletes something from their address book and would like to get it
 751  * back. You get it back by editing the nickname field manually to remove
 752  * the extra 18 characters off the front.
 753  */
 754 #ifndef ABOOK_DELETED_EXPIRE_TIME
 755 #define ABOOK_DELETED_EXPIRE_TIME   ONE_HUNDRED_DAYS
 756 #endif
 757
 758
 759 #ifdef  ENABLE_LDAP
 760 typedef struct _cust_filt {
 761     char *filt;
 762     int   combine;
 763 } CUSTOM_FILT_S;
 764
 765 #define RUN_LDAP        "LDAP: "
 766 #define LEN_RL          6
 767 #define QRUN_LDAP       "\"LDAP: "
 768 #define LEN_QRL         7
 769 #define LDAP_DISP       "[ LDAP Lookup ]"
 770 #endif
 771
 772
 773 /*
 774  * There are no restrictions on the length of any of the fields, except that
 775  * there are some restrictions in the current input routines.
 776  */
 777
 778 /*
 779  * The on-disk address book has entries that look like:
 780  *
 781  * Nickname TAB Fullname TAB Address_Field TAB Fcc TAB Comment
 782  *
 783  * An entry may be broken over more than one line but only at certain
 784  * spots. A continuation line starts with spaces (spaces, not white space).
 785  * One place a line break can occur is after any of the TABs. The other
 786  * place is in the middle of a list of addresses, between addresses.
 787  * The Address_Field may be either a simple address without the fullname
 788  * or brackets, or it may be an address list. An address list is
 789  * distinguished by the fact that it begins with "(" and ends with ")".
 790  * Addresses within a list are comma separated and each address in the list
 791  * may be a full rfc822 address, including Fullname and so on.
 792  *
 793  * Examples:
 794  * fred TAB Flintstone, Fred TAB fred@bedrock.net TAB fcc-flintstone TAB comment
 795  * or
 796  * fred TAB Flintstone, Fred TAB \n
 797  *    fred@bedrock.net TAB fcc-flintstone TAB \n
 798  *    comment
 799  * somelist TAB Some List TAB (fred, \n
 800  *    Barney Rubble <barney@bedrock.net>, wilma@bedrock.net) TAB \n
 801  *    fcc-for-some-list TAB comment
 802  */
 803
 804
 805 /* exported prototypes */
 806 AdrBk         *adrbk_open(PerAddrBook *, char *, char *, size_t, int);
 807 int            adrbk_is_in_sort_order(AdrBk *, int);
 808 adrbk_cntr_t   adrbk_count(AdrBk *);
 809 AdrBk_Entry   *adrbk_get_ae(AdrBk *, a_c_arg_t);
 810 AdrBk_Entry   *adrbk_lookup_by_nick(AdrBk *, char *, adrbk_cntr_t *);
 811 AdrBk_Entry   *adrbk_lookup_by_addr(AdrBk *, char *, adrbk_cntr_t *);
 812 char          *adrbk_formatname(char *, char **, char **);
 813 void           adrbk_clearrefs(AdrBk *);
 814 AdrBk_Entry   *adrbk_newentry(void);
 815 AdrBk_Entry   *copy_ae(AdrBk_Entry *);
 816 int            adrbk_add(AdrBk *, a_c_arg_t, char *, char *, char *, char *,
 817                          char *, Tag, adrbk_cntr_t *, int *, int, int, int);
 818 int            adrbk_append(AdrBk *, char *, char *, char *,
 819                             char *, char *, Tag, adrbk_cntr_t *);
 820 int            adrbk_delete(AdrBk *, a_c_arg_t, int, int, int, int);
 821 int            adrbk_listdel(AdrBk *, a_c_arg_t, char *);
 822 int            adrbk_listdel_all(AdrBk *, a_c_arg_t);
 823 int            adrbk_nlistadd(AdrBk *, a_c_arg_t,adrbk_cntr_t *,int *,char **,int,int,int);
 824 void           adrbk_check_validity(AdrBk *, long);
 825 MAILSTREAM    *adrbk_handy_stream(char *);
 826 void           adrbk_close(AdrBk *);
 827 void           adrbk_partial_close(AdrBk *);
 828 void           note_closed_adrbk_stream(MAILSTREAM *);
 829 int            adrbk_write(AdrBk *, a_c_arg_t, adrbk_cntr_t *, int *, int, int);
 830 void           free_ae(AdrBk_Entry **);
 831 void           exp_free(EXPANDED_S *);
 832 int            exp_is_expanded(EXPANDED_S *, a_c_arg_t);
 833 int            exp_howmany_expanded(EXPANDED_S *);
 834 int            exp_any_expanded(EXPANDED_S *);
 835 adrbk_cntr_t   exp_get_next(EXPANDED_S **);
 836 void           exp_set_expanded(EXPANDED_S *, a_c_arg_t);
 837 void           exp_unset_expanded(EXPANDED_S *, a_c_arg_t);
 838 int            adrbk_sort(AdrBk *, a_c_arg_t, adrbk_cntr_t *, int);
 839 int            any_ab_open(void);
 840 void           init_ab_if_needed(void);
 841 int            init_addrbooks(OpenStatus, int, int, int);
 842 void           addrbook_reset(void);
 843 void           addrbook_redo_sorts(void);
 844 AccessType     adrbk_access(PerAddrBook *);
 845 void           trim_remote_adrbks(void);
 846 void           completely_done_with_adrbks(void);
 847 void           init_abook(PerAddrBook *, OpenStatus);
 848 int            adrbk_check_all_validity_now(void);
 849 int            adrbk_check_and_fix(PerAddrBook *, int, int, int);
 850 int            adrbk_check_and_fix_all(int, int, int);
 851 void           adrbk_maintenance(void);
 852 char         **parse_addrlist(char *);
 853 char          *skip_to_next_addr(char *);
 854 void           add_forced_entries(AdrBk *);
 855 int          any_addressbook_in_remote_stream(MAILSTREAM *);
 856
 857 #endif /* PITH_ADRBKLIB_INCLUDED */