git.ozlabs.org Git - ccan/blob - ccan/rfc822/rfc822.h

   1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
   2 #ifndef CCAN_RFC822_H_
   3 #define CCAN_RFC822_H_
   4
   5 #include <stdlib.h>
   6
   7 #include <ccan/bytestring/bytestring.h>
   8
   9 /* #define CCAN_RFC822_DEBUG 1 */
  10
  11 struct rfc822_header;
  12 struct rfc822_msg;
  13
  14 /**
  15  * rfc822_set_allocation_failure_handler - set function to call on allocation
  16  *                                         failure
  17  * @h: failure handler function pointer
  18  *
  19  * Normally functions in this module abort() on allocation failure for
  20  * simplicity.  You can change this behaviour by calling this function
  21  * to set an alternative callback for allocation failures.  The
  22  * callback is called with a string describing where the failure
  23  * occurred, which can be used to log a more useful error message.
  24  *
  25  * Note that tal also has a default function which calls abort() on allocation
  26  * failure: see tal_set_backend().
  27  *
  28  * Example:
  29  *      static void my_handler(const char *str)
  30  *      {
  31  *              fprintf(stderr, "Allocation failure: %s\n", str);
  32  *              exit(1);
  33  *      }
  34  *
  35  *      static void do_rfc822_stuff(void *buf, size_t len)
  36  *      {
  37  *              rfc822_set_allocation_failure_handler(&my_handler);
  38  *              rfc822_start(NULL, buf, len);
  39  *      }
  40  */
  41 void rfc822_set_allocation_failure_handler(void (*h)(const char *));
  42
  43
  44 static inline bool rfc822_iswsp(char c)
  45 {
  46         return (c == ' ') || (c == '\t');
  47 }
  48
  49 /**
  50  * rfc822_check - check validity of an rfc822_msg context
  51  * @msg: message to validate
  52  *
  53  * This debugging function checks the validity of the internal data
  54  * structures in an active rfc822_msg context.  If @abortstr is
  55  * non-NULL, that will be printed in a diagnostic if the state is
  56  * inconsistent, and the function will abort.  If the state of the
  57  * structure is valid it returns it unchanged.
  58  *
  59  * Returns the @msg if the message is consistent, NULL if not (it can
  60  * never return NULL if @abortstr is set).
  61  */
  62 struct rfc822_msg *rfc822_check(const struct rfc822_msg *msg,
  63                                 const char *abortstr);
  64
  65 /**
  66  * rfc822_start - start parsing a new rfc822 message
  67  * @ctx: tal context to make allocations in (or talloc #ifdef TAL_USE_TALLOC)
  68  * @p: pointer to a buffer containing the message text
  69  * @len: length of the message text
  70  *
  71  * This function creates a new rfc822_msg context for parsing an
  72  * rfc822 message, initialized based on the message text given by the
  73  * pointer.
  74  */
  75 struct rfc822_msg *rfc822_start(const void *ctx, const char *p, size_t len);
  76
  77 /**
  78  * rfc822_free - free an rfc822 message
  79  * @msg: message to free
  80  *
  81  * Frees an rfc822_msg context, including all subsiduary data
  82  * structures.
  83  */
  84 void rfc822_free(struct rfc822_msg *msg);
  85
  86 /**
  87  * rfc822_first_header - retrieve the first header of an rfc822 message
  88  * @msg: message
  89  *
  90  * Finds the first header field of @msg and returns a struct
  91  * rfc822_header pointer representing it.
  92  */
  93 #define rfc822_first_header(msg) (rfc822_next_header((msg), NULL))
  94
  95 /**
  96  * rfc822_next_header - retrieve the next header of an rfc822 message
  97  * @msg: message
  98  * @hdr: current header field
  99  *
 100  * Finds the header field of @msg which immediately follows @hdr and
 101  * returns a struct rfc822_header pointer for it.  If @hdr is NULL,
 102  * returns the first header in the message.
 103  */
 104 struct rfc822_header *rfc822_next_header(struct rfc822_msg *msg,
 105                                          struct rfc822_header *hdr);
 106
 107 #define rfc822_for_each_header(msg, hdr) \
 108         for ((hdr) = rfc822_first_header((msg)); \
 109              (hdr);                                     \
 110              (hdr) = rfc822_next_header((msg), (hdr)))
 111
 112 /**
 113  * rfc822_body - retrieve the body of an rfc822 message
 114  * @msg: message
 115  *
 116  * Finds the body of @msg and returns a bytestring containing its
 117  * contents.
 118  */
 119 struct bytestring rfc822_body(struct rfc822_msg *msg);
 120
 121 enum rfc822_header_errors {
 122         RFC822_HDR_NO_COLON = 1,
 123         RFC822_HDR_BAD_NAME_CHARS = 2,
 124 };
 125
 126 enum rfc822_header_errors rfc822_header_errors(struct rfc822_msg *msg,
 127                                                struct rfc822_header *hdr);
 128
 129 /**
 130  * rfc822_header_raw_content - retrieve the raw content of an rfc822 header
 131  * @hdr: a header handle
 132  *
 133  * This returns a bytestring containing the complete contents (name
 134  * and value) of @hdr.  This will work even if the header is badly
 135  * formatted and cannot otherwise be parsed.
 136  */
 137 struct bytestring rfc822_header_raw_content(struct rfc822_msg *msg,
 138                                             struct rfc822_header *hdr);
 139
 140
 141 /**
 142  * rfc822_header_raw_name - retrieve the name of an rfc822 header
 143  * @hdr: a header handle
 144  *
 145  * This returns a bytestring containing the header name of @hdr.  This
 146  * could include any invalid characters, in the case of a badly
 147  * formatted header.
 148  */
 149 struct bytestring rfc822_header_raw_name(struct rfc822_msg *msg,
 150                                          struct rfc822_header *hdr);
 151
 152 /**
 153  * rfc822_header_raw_value - retrieve the unprocessed value of an rfc822 header
 154  * @hdr: a header handle
 155  *
 156  * This returns a bytestring containing the complete contents of
 157  * @hdr's value.  This includes the terminating and any internal
 158  * (folded) newlines.
 159  */
 160 struct bytestring rfc822_header_raw_value(struct rfc822_msg *msg,
 161                                           struct rfc822_header *hdr);
 162
 163 /**
 164  * rfc822_header_unfolded_value - retrieve the unfolded value of an rfc822 header
 165  * @hdr: a header handle
 166  *
 167  * This returns a bytestring containing the unfolded contents of
 168  * @hdr's value.  That is, the header value with any internal and the
 169  * terminating newline removed.
 170  */
 171 struct bytestring rfc822_header_unfolded_value(struct rfc822_msg *msg,
 172                                                struct rfc822_header *hdr);
 173
 174 /**
 175  * rfc822_header_is - determine if a header is of a given name
 176  * @msg: message
 177  * @hdr: a header handle
 178  * @name: header name
 179  *
 180  * This returns true if the header field @hdr has name @name (case
 181  * insensitive), otherwise false.
 182  */
 183 bool rfc822_header_is(struct rfc822_msg *msg, struct rfc822_header *hdr,
 184                       const char *name);
 185
 186 struct rfc822_header *rfc822_first_header_of_name(struct rfc822_msg *msg,
 187                                                   const char *name);
 188 struct rfc822_header *rfc822_next_header_of_name(struct rfc822_msg *msg,
 189                                                  struct rfc822_header *hdr,
 190                                                  const char *name);
 191
 192 #endif /* CCAN_RFC822_H_ */