1 /* ====================================================================
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
18 * ====================================================================
21 #ifndef SERF_BUCKET_UTIL_H
22 #define SERF_BUCKET_UTIL_H
25 * @file serf_bucket_util.h
26 * @brief This header defines a set of functions and other utilities
27 * for implementing buckets. It is not needed by users of the bucket
39 * Basic bucket creation function.
41 * This function will create a bucket of @a type, allocating the necessary
42 * memory from @a allocator. The @a data bucket-private information will
43 * be stored into the bucket.
45 serf_bucket_t *serf_bucket_create(
46 const serf_bucket_type_t *type,
47 serf_bucket_alloc_t *allocator,
51 * Default implementation of the @see read_iovec functionality.
53 * This function will use the @see read function to get a block of memory,
54 * then return it in the iovec.
56 apr_status_t serf_default_read_iovec(
57 serf_bucket_t *bucket,
64 * Default implementation of the @see read_for_sendfile functionality.
66 * This function will use the @see read function to get a block of memory,
67 * then return it as a header. No file will be returned.
69 apr_status_t serf_default_read_for_sendfile(
70 serf_bucket_t *bucket,
78 * Default implementation of the @see read_bucket functionality.
80 * This function will always return NULL, indicating that the @a type
81 * of bucket cannot be found within @a bucket.
83 serf_bucket_t *serf_default_read_bucket(
84 serf_bucket_t *bucket,
85 const serf_bucket_type_t *type);
88 * Default implementation of the @see destroy functionality.
90 * This function will return the @a bucket to its allcoator.
92 void serf_default_destroy(
93 serf_bucket_t *bucket);
97 * Default implementation of the @see destroy functionality.
99 * This function will return the @a bucket, and the data member to its
102 void serf_default_destroy_and_data(
103 serf_bucket_t *bucket);
107 * Allocate @a size bytes of memory using @a allocator.
109 * Returns NULL of the requested memory size could not be allocated.
111 void *serf_bucket_mem_alloc(
112 serf_bucket_alloc_t *allocator,
116 * Allocate @a size bytes of memory using @a allocator and set all of the
119 * Returns NULL of the requested memory size could not be allocated.
121 void *serf_bucket_mem_calloc(
122 serf_bucket_alloc_t *allocator,
126 * Free the memory at @a block, returning it to @a allocator.
128 void serf_bucket_mem_free(
129 serf_bucket_alloc_t *allocator,
134 * Analogous to apr_pstrmemdup, using a bucket allocator instead.
136 char *serf_bstrmemdup(
137 serf_bucket_alloc_t *allocator,
142 * Analogous to apr_pmemdup, using a bucket allocator instead.
145 serf_bucket_alloc_t *allocator,
150 * Analogous to apr_pstrdup, using a bucket allocator instead.
153 serf_bucket_alloc_t *allocator,
157 * Analogous to apr_pstrcatv, using a bucket allocator instead.
159 char * serf_bstrcatv(
160 serf_bucket_alloc_t *allocator,
163 apr_size_t *bytes_written);
166 * Read data up to a newline.
168 * @a acceptable contains the allowed forms of a newline, and @a found
169 * will return the particular newline type that was found. If a newline
170 * is not found, then SERF_NEWLINE_NONE will be placed in @a found.
172 * @a data should contain a pointer to the data to be scanned. @a len
173 * should specify the length of that data buffer. On exit, @a data will
174 * be advanced past the newline, and @a len will specify the remaining
175 * amount of data in the buffer.
177 * Given this pattern of behavior, the caller should store the initial
178 * value of @a data as the line start. The difference between the
179 * returned value of @a data and the saved start is the length of the
182 * Note that the newline character(s) will remain within the buffer.
183 * This function scans at a byte level for the newline characters. Thus,
184 * the data buffer may contain NUL characters. As a corollary, this
185 * function only works on 8-bit character encodings.
187 * If the data is fully consumed (@a len gets set to zero) and a CR
188 * character is found at the end and the CRLF sequence is allowed, then
189 * this function may store SERF_NEWLINE_CRLF_SPLIT into @a found. The
190 * caller should take particular consideration for the CRLF sequence
191 * that may be split across data buffer boundaries.
193 void serf_util_readline(
200 /** The buffer size used within @see serf_databuf_t. */
201 #define SERF_DATABUF_BUFSIZE 8000
203 /** Callback function which is used to refill the data buffer.
205 * The function takes @a baton, which is the @see read_baton value
206 * from the serf_databuf_t structure. Data should be placed into
207 * a buffer specified by @a buf, which is @a bufsize bytes long.
208 * The amount of data read should be returned in @a len.
210 * APR_EOF should be returned if no more data is available. APR_EAGAIN
211 * should be returned, rather than blocking. In both cases, @a buf
212 * should be filled in and @a len set, as appropriate.
214 typedef apr_status_t (*serf_databuf_reader_t)(
221 * This structure is used as an intermediate data buffer for some "external"
222 * source of data. It works as a scratch pad area for incoming data to be
223 * stored, and then returned as a ptr/len pair by the bucket read functions.
225 * This structure should be initialized by calling @see serf_databuf_init.
226 * Users should not bother to zero the structure beforehand.
229 /** The current data position within the buffer. */
232 /** Amount of data remaining in the buffer. */
233 apr_size_t remaining;
235 /** Callback function. */
236 serf_databuf_reader_t read;
238 /** A baton to hold context-specific data. */
241 /** Records the status from the last @see read operation. */
244 /** Holds the data until it can be returned. */
245 char buf[SERF_DATABUF_BUFSIZE];
250 * Initialize the @see serf_databuf_t structure specified by @a databuf.
252 void serf_databuf_init(
253 serf_databuf_t *databuf);
256 * Implement a bucket-style read function from the @see serf_databuf_t
257 * structure given by @a databuf.
259 * The @a requested, @a data, and @a len fields are interpreted and used
260 * as in the read function of @see serf_bucket_t.
262 apr_status_t serf_databuf_read(
263 serf_databuf_t *databuf,
264 apr_size_t requested,
269 * Implement a bucket-style readline function from the @see serf_databuf_t
270 * structure given by @a databuf.
272 * The @a acceptable, @a found, @a data, and @a len fields are interpreted
273 * and used as in the read function of @see serf_bucket_t.
275 apr_status_t serf_databuf_readline(
276 serf_databuf_t *databuf,
283 * Implement a bucket-style peek function from the @see serf_databuf_t
284 * structure given by @a databuf.
286 * The @a data, and @a len fields are interpreted and used as in the
287 * peek function of @see serf_bucket_t.
289 apr_status_t serf_databuf_peek(
290 serf_databuf_t *databuf,
299 #endif /* !SERF_BUCKET_UTIL_H */