1251877Speter/* Copyright 2002-2004 Justin Erenkrantz and Greg Stein 2251877Speter * 3251877Speter * Licensed under the Apache License, Version 2.0 (the "License"); 4251877Speter * you may not use this file except in compliance with the License. 5251877Speter * You may obtain a copy of the License at 6251877Speter * 7251877Speter * http://www.apache.org/licenses/LICENSE-2.0 8251877Speter * 9251877Speter * Unless required by applicable law or agreed to in writing, software 10251877Speter * distributed under the License is distributed on an "AS IS" BASIS, 11251877Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12251877Speter * See the License for the specific language governing permissions and 13251877Speter * limitations under the License. 14251877Speter */ 15251877Speter 16251877Speter#ifndef SERF_BUCKET_UTIL_H 17251877Speter#define SERF_BUCKET_UTIL_H 18251877Speter 19251877Speter/** 20251877Speter * @file serf_bucket_util.h 21251877Speter * @brief This header defines a set of functions and other utilities 22251877Speter * for implementing buckets. It is not needed by users of the bucket 23251877Speter * system. 24251877Speter */ 25251877Speter 26251877Speter#include "serf.h" 27251877Speter 28251877Speter#ifdef __cplusplus 29251877Speterextern "C" { 30251877Speter#endif 31251877Speter 32251877Speter 33251877Speter/** 34251877Speter * Basic bucket creation function. 35251877Speter * 36251877Speter * This function will create a bucket of @a type, allocating the necessary 37251877Speter * memory from @a allocator. The @a data bucket-private information will 38251877Speter * be stored into the bucket. 39251877Speter */ 40251877Speterserf_bucket_t *serf_bucket_create( 41251877Speter const serf_bucket_type_t *type, 42251877Speter serf_bucket_alloc_t *allocator, 43251877Speter void *data); 44251877Speter 45251877Speter/** 46251877Speter * Default implementation of the @see read_iovec functionality. 47251877Speter * 48251877Speter * This function will use the @see read function to get a block of memory, 49251877Speter * then return it in the iovec. 50251877Speter */ 51251877Speterapr_status_t serf_default_read_iovec( 52251877Speter serf_bucket_t *bucket, 53251877Speter apr_size_t requested, 54251877Speter int vecs_size, 55251877Speter struct iovec *vecs, 56251877Speter int *vecs_used); 57251877Speter 58251877Speter/** 59251877Speter * Default implementation of the @see read_for_sendfile functionality. 60251877Speter * 61251877Speter * This function will use the @see read function to get a block of memory, 62251877Speter * then return it as a header. No file will be returned. 63251877Speter */ 64251877Speterapr_status_t serf_default_read_for_sendfile( 65251877Speter serf_bucket_t *bucket, 66251877Speter apr_size_t requested, 67251877Speter apr_hdtr_t *hdtr, 68251877Speter apr_file_t **file, 69251877Speter apr_off_t *offset, 70251877Speter apr_size_t *len); 71251877Speter 72251877Speter/** 73251877Speter * Default implementation of the @see read_bucket functionality. 74251877Speter * 75251877Speter * This function will always return NULL, indicating that the @a type 76251877Speter * of bucket cannot be found within @a bucket. 77251877Speter */ 78251877Speterserf_bucket_t *serf_default_read_bucket( 79251877Speter serf_bucket_t *bucket, 80251877Speter const serf_bucket_type_t *type); 81251877Speter 82251877Speter/** 83251877Speter * Default implementation of the @see destroy functionality. 84251877Speter * 85251877Speter * This function will return the @a bucket to its allcoator. 86251877Speter */ 87251877Spetervoid serf_default_destroy( 88251877Speter serf_bucket_t *bucket); 89251877Speter 90251877Speter 91251877Speter/** 92251877Speter * Default implementation of the @see destroy functionality. 93251877Speter * 94251877Speter * This function will return the @a bucket, and the data member to its 95251877Speter * allocator. 96251877Speter */ 97251877Spetervoid serf_default_destroy_and_data( 98251877Speter serf_bucket_t *bucket); 99251877Speter 100251877Speter 101251877Speter/** 102251877Speter * Allocate @a size bytes of memory using @a allocator. 103251877Speter * 104251877Speter * Returns NULL of the requested memory size could not be allocated. 105251877Speter */ 106251877Spetervoid *serf_bucket_mem_alloc( 107251877Speter serf_bucket_alloc_t *allocator, 108251877Speter apr_size_t size); 109251877Speter 110251877Speter/** 111251877Speter * Allocate @a size bytes of memory using @a allocator and set all of the 112251877Speter * memory to 0. 113251877Speter * 114251877Speter * Returns NULL of the requested memory size could not be allocated. 115251877Speter */ 116251877Spetervoid *serf_bucket_mem_calloc( 117251877Speter serf_bucket_alloc_t *allocator, 118251877Speter apr_size_t size); 119251877Speter 120251877Speter/** 121251877Speter * Free the memory at @a block, returning it to @a allocator. 122251877Speter */ 123251877Spetervoid serf_bucket_mem_free( 124251877Speter serf_bucket_alloc_t *allocator, 125251877Speter void *block); 126251877Speter 127251877Speter 128251877Speter/** 129251877Speter * Analogous to apr_pstrmemdup, using a bucket allocator instead. 130251877Speter */ 131251877Speterchar *serf_bstrmemdup( 132251877Speter serf_bucket_alloc_t *allocator, 133251877Speter const char *str, 134251877Speter apr_size_t size); 135251877Speter 136251877Speter/** 137251877Speter * Analogous to apr_pmemdup, using a bucket allocator instead. 138251877Speter */ 139251877Spetervoid * serf_bmemdup( 140251877Speter serf_bucket_alloc_t *allocator, 141251877Speter const void *mem, 142251877Speter apr_size_t size); 143251877Speter 144251877Speter/** 145251877Speter * Analogous to apr_pstrdup, using a bucket allocator instead. 146251877Speter */ 147251877Speterchar * serf_bstrdup( 148251877Speter serf_bucket_alloc_t *allocator, 149251877Speter const char *str); 150251877Speter 151253895Speter/** 152253895Speter * Analogous to apr_pstrcatv, using a bucket allocator instead. 153253895Speter */ 154253895Speterchar * serf_bstrcatv( 155253895Speter serf_bucket_alloc_t *allocator, 156253895Speter struct iovec *vec, 157253895Speter int vecs, 158253895Speter apr_size_t *bytes_written); 159251877Speter 160251877Speter/** 161251877Speter * Read data up to a newline. 162251877Speter * 163251877Speter * @a acceptable contains the allowed forms of a newline, and @a found 164251877Speter * will return the particular newline type that was found. If a newline 165251877Speter * is not found, then SERF_NEWLINE_NONE will be placed in @a found. 166251877Speter * 167251877Speter * @a data should contain a pointer to the data to be scanned. @a len 168251877Speter * should specify the length of that data buffer. On exit, @a data will 169251877Speter * be advanced past the newline, and @a len will specify the remaining 170251877Speter * amount of data in the buffer. 171251877Speter * 172251877Speter * Given this pattern of behavior, the caller should store the initial 173251877Speter * value of @a data as the line start. The difference between the 174251877Speter * returned value of @a data and the saved start is the length of the 175251877Speter * line. 176251877Speter * 177251877Speter * Note that the newline character(s) will remain within the buffer. 178251877Speter * This function scans at a byte level for the newline characters. Thus, 179251877Speter * the data buffer may contain NUL characters. As a corollary, this 180251877Speter * function only works on 8-bit character encodings. 181251877Speter * 182251877Speter * If the data is fully consumed (@a len gets set to zero) and a CR 183251877Speter * character is found at the end and the CRLF sequence is allowed, then 184251877Speter * this function may store SERF_NEWLINE_CRLF_SPLIT into @a found. The 185251877Speter * caller should take particular consideration for the CRLF sequence 186251877Speter * that may be split across data buffer boundaries. 187251877Speter */ 188251877Spetervoid serf_util_readline( 189251877Speter const char **data, 190251877Speter apr_size_t *len, 191251877Speter int acceptable, 192251877Speter int *found); 193251877Speter 194251877Speter 195251877Speter/** The buffer size used within @see serf_databuf_t. */ 196251877Speter#define SERF_DATABUF_BUFSIZE 8000 197251877Speter 198251877Speter/** Callback function which is used to refill the data buffer. 199251877Speter * 200251877Speter * The function takes @a baton, which is the @see read_baton value 201251877Speter * from the serf_databuf_t structure. Data should be placed into 202251877Speter * a buffer specified by @a buf, which is @a bufsize bytes long. 203251877Speter * The amount of data read should be returned in @a len. 204251877Speter * 205251877Speter * APR_EOF should be returned if no more data is available. APR_EAGAIN 206251877Speter * should be returned, rather than blocking. In both cases, @a buf 207251877Speter * should be filled in and @a len set, as appropriate. 208251877Speter */ 209251877Spetertypedef apr_status_t (*serf_databuf_reader_t)( 210251877Speter void *baton, 211251877Speter apr_size_t bufsize, 212251877Speter char *buf, 213251877Speter apr_size_t *len); 214251877Speter 215251877Speter/** 216251877Speter * This structure is used as an intermediate data buffer for some "external" 217251877Speter * source of data. It works as a scratch pad area for incoming data to be 218251877Speter * stored, and then returned as a ptr/len pair by the bucket read functions. 219251877Speter * 220251877Speter * This structure should be initialized by calling @see serf_databuf_init. 221251877Speter * Users should not bother to zero the structure beforehand. 222251877Speter */ 223251877Spetertypedef struct { 224251877Speter /** The current data position within the buffer. */ 225251877Speter const char *current; 226251877Speter 227251877Speter /** Amount of data remaining in the buffer. */ 228251877Speter apr_size_t remaining; 229251877Speter 230251877Speter /** Callback function. */ 231251877Speter serf_databuf_reader_t read; 232251877Speter 233251877Speter /** A baton to hold context-specific data. */ 234251877Speter void *read_baton; 235251877Speter 236251877Speter /** Records the status from the last @see read operation. */ 237251877Speter apr_status_t status; 238251877Speter 239251877Speter /** Holds the data until it can be returned. */ 240251877Speter char buf[SERF_DATABUF_BUFSIZE]; 241251877Speter 242251877Speter} serf_databuf_t; 243251877Speter 244251877Speter/** 245251877Speter * Initialize the @see serf_databuf_t structure specified by @a databuf. 246251877Speter */ 247251877Spetervoid serf_databuf_init( 248251877Speter serf_databuf_t *databuf); 249251877Speter 250251877Speter/** 251251877Speter * Implement a bucket-style read function from the @see serf_databuf_t 252251877Speter * structure given by @a databuf. 253251877Speter * 254251877Speter * The @a requested, @a data, and @a len fields are interpreted and used 255251877Speter * as in the read function of @see serf_bucket_t. 256251877Speter */ 257251877Speterapr_status_t serf_databuf_read( 258251877Speter serf_databuf_t *databuf, 259251877Speter apr_size_t requested, 260251877Speter const char **data, 261251877Speter apr_size_t *len); 262251877Speter 263251877Speter/** 264251877Speter * Implement a bucket-style readline function from the @see serf_databuf_t 265251877Speter * structure given by @a databuf. 266251877Speter * 267251877Speter * The @a acceptable, @a found, @a data, and @a len fields are interpreted 268251877Speter * and used as in the read function of @see serf_bucket_t. 269251877Speter */ 270251877Speterapr_status_t serf_databuf_readline( 271251877Speter serf_databuf_t *databuf, 272251877Speter int acceptable, 273251877Speter int *found, 274251877Speter const char **data, 275251877Speter apr_size_t *len); 276251877Speter 277251877Speter/** 278251877Speter * Implement a bucket-style peek function from the @see serf_databuf_t 279251877Speter * structure given by @a databuf. 280251877Speter * 281251877Speter * The @a data, and @a len fields are interpreted and used as in the 282251877Speter * peek function of @see serf_bucket_t. 283251877Speter */ 284251877Speterapr_status_t serf_databuf_peek( 285251877Speter serf_databuf_t *databuf, 286251877Speter const char **data, 287251877Speter apr_size_t *len); 288251877Speter 289251877Speter 290251877Speter#ifdef __cplusplus 291251877Speter} 292251877Speter#endif 293251877Speter 294251877Speter#endif /* !SERF_BUCKET_UTIL_H */ 295