pith/bldaddr.h

   1 /*
   2  * $Id: bldaddr.h 769 2007-10-24 00:15:40Z hubert@u.washington.edu $
   3  *
   4  * ========================================================================
   5  * Copyright 2006-2007 University of Washington
   6  * Copyright 2013-2022 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_BLDADDR_INCLUDED
  18 #define PITH_BLDADDR_INCLUDED
  19
  20
  21 #include "../pith/adrbklib.h"
  22 #include "../pith/state.h"
  23 #include "../pith/ldap.h"
  24 #include "../pith/pattern.h"
  25 #include "../pith/remtype.h"
  26
  27
  28 /*
  29  * This is the structure that the builders impose on the private data
  30  * that is pointed to by the bldr_private pointer in each header entry.
  31  *
  32  * The bldr_private pointer points to a PrivateTop which consists of two
  33  * parts, whose purposes are independent:
  34  *    ******* This part no longer exists ******
  35  *   encoded -- This is used to preserve the charset information for
  36  *                addresses in this entry. For example, if the user types
  37  *                in a nickname which has a charset in it, the encoded
  38  *                version containing the charset information is saved here
  39  *                along with a checksum of the text that created it (the
  40  *                line containing the nickname).
  41  *         etext -- Pointer to the encoded text.
  42  *     chksumlen -- Length of string that produced the etext.
  43  *     chksumval -- Checksum of that string.
  44  *         The string that produced the etext is just the displayed
  45  *         value of the entry, not the nickname before it was expanded.
  46  *         That's so we can check on the next builder call to see if it
  47  *         was changed or not. Appending or prepending more addresses to
  48  *         what's there will work, the etext from the old contents will
  49  *         be combined with the etext from the appended stuff. (The check
  50  *         is for appending or prepending so appending AND prepending all
  51  *         at once won't work, charset will be lost.) If the middle of the
  52  *         text is edited the charset is lost. If text is removed, the
  53  *         charset is lost.
  54  *
  55  *  affector -- This is for entries which affect the contents of other
  56  *                fields. For example, the Lcc field affects what goes in
  57  *                the To and Fcc fields, and the To field affects what goes
  58  *                in the Fcc field.
  59  *           who -- Who caused this field to be set last.
  60  *     chksumlen -- Length of string in the "who" field that caused the effect.
  61  *     chksumval -- Checksum of that string.
  62  *         The string that is being checksummed is the one that is displayed
  63  *         in the field doing the affecting. So, for the affector in the
  64  *         Fcc headerentry, the who might point to either To or Lcc and
  65  *         then the checksummed string would be either the To or Lcc displayed
  66  *         string. The purpose of the affector is to remember that the
  67  *         affected field was set from an address book entry that is no
  68  *         longer identifiable once it is expanded. For example, if a list
  69  *         is entered into the Lcc field, then the To field gets the list
  70  *         fullname and the fcc field gets the fcc entry for the list. If
  71  *         we move out of the Lcc field and back in and call the builder
  72  *         again, the list has been expanded and we can't tell (except for
  73  *         the affector) that the same list is what caused the results.
  74  *         Same for the To field. A nickname entered there will cause the
  75  *         fcc of that nickname to go in the Fcc field and the affector
  76  *         will cause it to stick as long as the To field is only appended to.
  77  *
  78  * It may seem a little strange that the PrivateAffector doesn't have a text
  79  * field. The reason is that the text is actually displayed in that field
  80  * and so is contained in the entry itself, unlike the PrivateEncoded
  81  * which has etext which is not displayed and is only used when we go to
  82  * send the mail.
  83  */
  84
  85 typedef enum {BP_Unset, BP_To, BP_Lcc} WhoSetUs;
  86
  87 typedef struct private_affector {
  88     WhoSetUs who;
  89     int      cksumlen;
  90     unsigned long cksumval;
  91 } PrivateAffector;
  92
  93 /*
  94  * This used to have more than one member. We could get rid
  95  * of this structure now if we wanted to, and just have the
  96  * PrivateAffector at the top-level, but it's easier alone.
  97  * Who knows, we may have a need for something else to be added
  98  * to the structure in the future.
  99  */
 100 typedef struct private_top {
 101     PrivateAffector *affector;
 102 } PrivateTop;
 103
 104 /* save_and_restore flags */
 105 #define SAR_SAVE        1
 106 #define SAR_RESTORE     2
 107
 108 /* exported prototypes */
 109 int      our_build_address(BuildTo, char **, char **, char **, void (*)(int, SAVE_STATE_S *));
 110 int      build_address_internal(BuildTo, char **, char **, char **, int *, char **,
 111                                 void (*)(int, SAVE_STATE_S *), int, int *);
 112 ADDRESS *expand_address(BuildTo, char *, char *, int *, char **, \
 113                         int *, char **, char **, int, int, int *);
 114 ADDRESS *massage_phrase_addr(char *, char *, char *);
 115 char    *get_fcc(char *);
 116 void     set_last_fcc(char *);
 117 char    *get_fcc_based_on_to(ADDRESS *);
 118 void     free_privatetop(PrivateTop **);
 119 void     strip_personal_quotes(ADDRESS *);
 120 void     free_bldaddr_module_globals(void);
 121
 122 #endif /* PITH_BLDADDR_INCLUDED */