Merge branch 'io'
[ccan] / 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_ */