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