granicus.if.org Git - apache/blob - include/apreq.h

   1 /*
   2 **  Licensed to the Apache Software Foundation (ASF) under one or more
   3 ** contributor license agreements.  See the NOTICE file distributed with
   4 ** this work for additional information regarding copyright ownership.
   5 ** The ASF licenses this file to You under the Apache License, Version 2.0
   6 ** (the "License"); you may not use this file except in compliance with
   7 ** the License.  You may obtain a copy of the License at
   8 **
   9 **      http://www.apache.org/licenses/LICENSE-2.0
  10 **
  11 **  Unless required by applicable law or agreed to in writing, software
  12 **  distributed under the License is distributed on an "AS IS" BASIS,
  13 **  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 **  See the License for the specific language governing permissions and
  15 **  limitations under the License.
  16 */
  17
  18 #ifndef APREQ_H
  19 #define APREQ_H
  20
  21 #ifdef APREQ_DEBUG
  22 #include <assert.h>
  23 #endif
  24
  25 #include "ap_config.h"
  26 #include "apr_tables.h"
  27 #include <stddef.h>
  28
  29 #ifdef  __cplusplus
  30  extern "C" {
  31 #endif
  32
  33 /**
  34  * @file apreq.h
  35  * @brief Main header file...
  36  * @ingroup libapreq2
  37  *
  38  * Define the common data structures.
  39  */
  40
  41 /**
  42  * Read chucks of data in 64k blocks from the request
  43  */
  44
  45 #define APREQ_DEFAULT_READ_BLOCK_SIZE   (64  * 1024)
  46
  47 /**
  48  * Maximum number of bytes mod_apreq2 will send off to libapreq2 for parsing.
  49  * mod_apreq2 will log this event and subsequently remove itself
  50  * from the filter chain.
  51  * @see ap_set_read_limit
  52  */
  53 #define APREQ_DEFAULT_READ_LIMIT        (64 * 1024 * 1024)
  54 /**
  55  * Maximum number of bytes mod_apreq2 will let accumulate within the
  56  * heap-buckets in a brigade. Excess data will be spooled to an
  57  * appended file bucket
  58  * @see ap_set_brigade_read_limit
  59  */
  60 #define APREQ_DEFAULT_BRIGADE_LIMIT     (256 * 1024)
  61
  62 /**
  63  * Number of elements in the initial apr_table
  64  * @see apr_table_make
  65  */
  66 #define APREQ_DEFAULT_NELTS              8
  67
  68
  69
  70 /**
  71  * Check to see if specified bit f is off in bitfield name
  72  */
  73 #define APREQ_FLAGS_OFF(f, name) ((f) &= ~(name##_MASK << name##_BIT))
  74 /**
  75  * Check to see if specified bit f is on in bitfield name
  76  */
  77 #define APREQ_FLAGS_ON(f, name)  ((f) |=  (name##_MASK << name##_BIT))
  78 /**
  79  *  Get specified bit f in bitfield name
  80  */
  81 #define APREQ_FLAGS_GET(f, name) (((f) >> name##_BIT) & name##_MASK)
  82 /**
  83  * Set specified bit f in bitfield name to value
  84  * Note the below BIT/Mask defines are used sans the
  85  * _BIT, _MASK because of the this define's \#\#_MASK, \#\#_BIT usage.
  86  * Each come in a pair
  87  */
  88 #define APREQ_FLAGS_SET(f, name, value)                 \
  89     ((f) = (((f) & ~(name##_MASK << name##_BIT))        \
  90             | ((name##_MASK & (value)) << name##_BIT)))
  91
  92 /**
  93  * Charset Bit
  94  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
  95  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
  96  */
  97 #define APREQ_CHARSET_BIT           0
  98
  99 /**
 100  * Charset Mask
 101  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 102  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 103  */
 104 #define APREQ_CHARSET_MASK        255
 105
 106 /**
 107  * Tainted Bit
 108  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 109  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 110  */
 111 #define APREQ_TAINTED_BIT           8
 112 /**
 113  * Tainted Mask
 114  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 115  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 116  */
 117 #define APREQ_TAINTED_MASK          1
 118
 119 /**
 120  * Cookier Version Bit
 121  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 122  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 123  */
 124
 125 #define APREQ_COOKIE_VERSION_BIT   11
 126 /**
 127  * Cookie Version Mask
 128  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 129  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 130  */
 131 #define APREQ_COOKIE_VERSION_MASK   3
 132
 133 /**
 134  * Cookie's Secure Bit
 135  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 136  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 137  */
 138 #define APREQ_COOKIE_SECURE_BIT    13
 139 /**
 140  * Cookie's Secure Mask
 141  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 142  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 143  */
 144 #define APREQ_COOKIE_SECURE_MASK    1
 145
 146 /**
 147  * Cookie's HttpOnly Bit
 148  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 149  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 150  */
 151 #define APREQ_COOKIE_HTTPONLY_BIT    14
 152 /**
 153  * Cookie's HttpOnly Mask
 154  * @see APREQ_FLAGS_OFF @see APREQ_FLAGS_ON
 155  * @see APREQ_FLAGS_GET @see APREQ_FLAGS_SET
 156  */
 157 #define APREQ_COOKIE_HTTPONLY_MASK    1
 158
 159 /** Character encodings. */
 160 typedef enum {
 161     APREQ_CHARSET_ASCII  =0,
 162     APREQ_CHARSET_LATIN1 =1, /* ISO-8859-1   */
 163     APREQ_CHARSET_CP1252 =2, /* Windows-1252 */
 164     APREQ_CHARSET_UTF8   =8
 165 } apreq_charset_t;
 166
 167
 168 /** @enum apreq_join_t Join type */
 169 typedef enum {
 170     APREQ_JOIN_AS_IS,      /**< Join the strings without modification */
 171     APREQ_JOIN_ENCODE,     /**< Url-encode the strings before joining them */
 172     APREQ_JOIN_DECODE,     /**< Url-decode the strings before joining them */
 173     APREQ_JOIN_QUOTE       /**< Quote the strings, backslashing existing quote marks. */
 174 } apreq_join_t;
 175
 176 /** @enum apreq_match_t Match type */
 177 typedef enum {
 178     APREQ_MATCH_FULL,       /**< Full match only. */
 179     APREQ_MATCH_PARTIAL     /**< Partial matches are ok. */
 180 } apreq_match_t;
 181
 182 /** @enum apreq_expires_t Expiration date format */
 183 typedef enum {
 184     APREQ_EXPIRES_HTTP,       /**< Use date formatting consistent with RFC 2616 */
 185     APREQ_EXPIRES_NSCOOKIE    /**< Use format consistent with Netscape's Cookie Spec */
 186 } apreq_expires_t;
 187
 188
 189 /** @brief libapreq's pre-extensible string type */
 190 typedef struct apreq_value_t {
 191     char             *name;    /**< value name */
 192     apr_size_t        nlen;    /**< length of name */
 193     apr_size_t        dlen;    /**< length of data */
 194     char              data[1]; /**< value data  */
 195 } apreq_value_t;
 196
 197 /**
 198  * Adds the specified apreq_value_t to the apr_table_t.
 199  *
 200  * @param v value to add
 201  * @param t add v to this table
 202  *
 203  * @return void
 204  *
 205  * @ see apr_table_t @see apr_value_t
 206  */
 207
 208 static APR_INLINE
 209 void apreq_value_table_add(const apreq_value_t *v, apr_table_t *t) {
 210     apr_table_addn(t, v->name, v->data);
 211 }
 212
 213 /**
 214  * @param T type
 215  * @param A attribute
 216  * @param P
 217  *
 218  * XXX
 219  */
 220 #define apreq_attr_to_type(T,A,P) ( (T*) ((char*)(P)-offsetof(T,A)) )
 221
 222 /**
 223  * Initialize libapreq2. Applications (except apache modules using
 224  * mod_apreq) should call this exactly once before they use any
 225  * libapreq2 modules.  If you want to modify the list of default parsers
 226  * with apreq_register_parser(), please use apreq_pre_initialize()
 227  * and apreq_post_initialize() instead.
 228  *
 229  * @param pool a base pool persisting while libapreq2 is used
 230  * @remarks after you detroy the pool, you have to call this function again
 231  *    with a new pool if you still plan to use libapreq2
 232  */
 233 APREQ_DECLARE(apr_status_t) apreq_initialize(apr_pool_t *pool);
 234
 235
 236 /**
 237  * Pre-initialize libapreq2. Applications (except apache modules using
 238  * mod_apreq2) should call this exactly once before they register custom
 239  * parsers with libapreq2. mod_apreq2 does this automatically during the
 240  * post-config phase, so modules that need call apreq_register_parser should
 241  * create a post-config hook using APR_HOOK_MIDDLE.
 242  *
 243  * @param pool a base pool persisting while libapreq2 is used
 244  * @remarks after you detroyed the pool, you have to call this function again
 245  *    with a new pool if you still plan to use libapreq2
 246  */
 247 APREQ_DECLARE(apr_status_t) apreq_pre_initialize(apr_pool_t *pool);
 248
 249 /**
 250  * Post-initialize libapreq2. Applications (except apache modules using
 251  * mod_apreq2) should this exactly once before they use any
 252  * libapreq2 modules for parsing.
 253  *
 254  * @param pool the same pool that was used in apreq_pre_initialize().
 255  */
 256 APREQ_DECLARE(apr_status_t) apreq_post_initialize(apr_pool_t *pool);
 257
 258
 259 #ifdef __cplusplus
 260  }
 261 #endif
 262
 263 #endif /* APREQ_H */