granicus.if.org Git - apache/blob - include/apreq_param.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_PARAM_H
  19 #define APREQ_PARAM_H
  20
  21 #include "apreq.h"
  22 #include "apr_buckets.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28
  29 /**
  30  * @file apreq_param.h
  31  * @brief Request parsing and parameter API
  32  * @ingroup libapreq2
  33  */
  34
  35
  36 /** Common data structure for params and file uploads */
  37 typedef struct apreq_param_t {
  38     apr_table_t         *info;   /**< header table associated with the param */
  39     apr_bucket_brigade  *upload; /**< brigade used to spool upload files */
  40     unsigned             flags;  /**< charsets, taint marks, app-specific bits */
  41     const apreq_value_t  v;      /**< underlying name/value info */
  42 } apreq_param_t;
  43
  44
  45 /** @return 1 if the taint flag is set, 0 otherwise. */
  46 static APR_INLINE
  47 unsigned apreq_param_is_tainted(const apreq_param_t *p) {
  48     return APREQ_FLAGS_GET(p->flags, APREQ_TAINTED);
  49 }
  50
  51 /** Sets the tainted flag. */
  52 static APR_INLINE
  53 void apreq_param_tainted_on(apreq_param_t *p) {
  54     APREQ_FLAGS_ON(p->flags, APREQ_TAINTED);
  55 }
  56
  57 /** Turns off the taint flag. */
  58 static APR_INLINE
  59 void apreq_param_tainted_off(apreq_param_t *p) {
  60     APREQ_FLAGS_OFF(p->flags, APREQ_TAINTED);
  61 }
  62
  63 /** Sets the character encoding for this parameter. */
  64 static APR_INLINE
  65 apreq_charset_t apreq_param_charset_set(apreq_param_t *p, apreq_charset_t c) {
  66     apreq_charset_t old = (apreq_charset_t)
  67         APREQ_FLAGS_GET(p->flags, APREQ_CHARSET);
  68     APREQ_FLAGS_SET(p->flags, APREQ_CHARSET, c);
  69     return old;
  70 }
  71
  72 /** Gets the character encoding for this parameter. */
  73 static APR_INLINE
  74 apreq_charset_t apreq_param_charset_get(apreq_param_t *p) {
  75     return (apreq_charset_t)APREQ_FLAGS_GET(p->flags, APREQ_CHARSET);
  76 }
  77
  78
  79 /** Upgrades args and body table values to apreq_param_t structs. */
  80 static APR_INLINE
  81 apreq_param_t *apreq_value_to_param(const char *val)
  82 {
  83     union { const char *in; char *out; } deconst;
  84
  85     deconst.in = val;
  86     return apreq_attr_to_type(apreq_param_t, v,
  87            apreq_attr_to_type(apreq_value_t, data, deconst.out));
  88 }
  89
  90
  91
  92 /** creates a param from name/value information */
  93 APREQ_DECLARE(apreq_param_t *) apreq_param_make(apr_pool_t *p,
  94                                                 const char *name,
  95                                                 const apr_size_t nlen,
  96                                                 const char *val,
  97                                                 const apr_size_t vlen);
  98
  99 /**
 100  * Url-decodes a name=value pair into a param.
 101  *
 102  * @param param points to the decoded parameter on success
 103  * @param pool  Pool from which the param is allocated.
 104  * @param word  Start of the name=value pair.
 105  * @param nlen  Length of urlencoded name.
 106  * @param vlen  Length of urlencoded value.
 107  *
 108  * @return APR_SUCCESS on success.
 109  * @return ::APREQ_ERROR_BADSEQ or ::APREQ_ERROR_BADCHAR on malformed input.
 110  *
 111  * @remarks     Unless vlen == 0, this function assumes there is
 112  *              exactly one character ('=') which separates the pair.
 113  *
 114  */
 115 APREQ_DECLARE(apr_status_t) apreq_param_decode(apreq_param_t **param,
 116                                                apr_pool_t *pool,
 117                                                const char *word,
 118                                                apr_size_t nlen,
 119                                                apr_size_t vlen);
 120
 121 /**
 122  * Url-encodes the param into a name-value pair.
 123  * @param pool Pool which allocates the returned string.
 124  * @param param Param to encode.
 125  * @return name-value pair representing the param.
 126  */
 127 APREQ_DECLARE(char *) apreq_param_encode(apr_pool_t *pool,
 128                                          const apreq_param_t *param);
 129
 130 /**
 131  * Parse a url-encoded string into a param table.
 132  * @param pool    pool used to allocate the param data.
 133  * @param t       table to which the params are added.
 134  * @param qs      Query string to url-decode.
 135  * @return        APR_SUCCESS if successful, error otherwise.
 136  * @remark        This function uses [&;] as the set of tokens
 137  *                to delineate words, and will treat a word w/o '='
 138  *                as a name-value pair with value-length = 0.
 139  *
 140  */
 141 APREQ_DECLARE(apr_status_t) apreq_parse_query_string(apr_pool_t *pool,
 142                                                      apr_table_t *t,
 143                                                      const char *qs);
 144
 145
 146 /**
 147  * Returns an array of parameters (apreq_param_t *) matching the given key.
 148  * The key is case-insensitive.
 149  * @param p Allocates the returned array.
 150  * @param t the parameter table returned by apreq_args(), apreq_body()
 151  *    or apreq_params()
 152  * @param key Null-terminated search key, case insensitive.
 153  *    key==NULL fetches all parameters.
 154  * @return an array of apreq_param_t* (pointers)
 155  * @remark Also parses the request if necessary.
 156  */
 157 APREQ_DECLARE(apr_array_header_t *) apreq_params_as_array(apr_pool_t *p,
 158                                                           const apr_table_t *t,
 159                                                           const char *key);
 160
 161 /**
 162  * Returns a ", " -joined string containing all parameters
 163  * for the requested key, an empty string if none are found.
 164  * The key is case-insensitive.
 165  *
 166  * @param p Allocates the return string.
 167  * @param t the parameter table returned by apreq_args(), apreq_body()
 168  *    or apreq_params()
 169  * @param key Null-terminated parameter name, case insensitive.
 170  *    key==NULL fetches all values.
 171  * @param mode Join type- see apreq_join().
 172  * @return the joined string or NULL on error
 173  * @remark Also parses the request if necessary.
 174  */
 175 APREQ_DECLARE(const char *) apreq_params_as_string(apr_pool_t *p,
 176                                                    const apr_table_t *t,
 177                                                    const char *key,
 178                                                    apreq_join_t mode);
 179
 180 /**
 181  * Returns a table of all params in req->body with non-NULL upload brigades.
 182  * @param body parameter table returned by apreq_body() or apreq_params()
 183  * @param pool Pool which allocates the table struct.
 184  * @return Upload table.
 185  * @remark Will parse the request if necessary.
 186  */
 187 APREQ_DECLARE(const apr_table_t *) apreq_uploads(const apr_table_t *body,
 188                                                  apr_pool_t *pool);
 189
 190 /**
 191  * Returns the first param in req->body which has both param->v.name
 192  * matching key (case insensitive) and param->upload != NULL.
 193  * @param body parameter table returned by apreq_body() or apreq_params()
 194  * @param name Parameter name. key == NULL returns first upload.
 195  * @return Corresponding upload, NULL if none found.
 196  * @remark Will parse the request as necessary.
 197  */
 198 APREQ_DECLARE(const apreq_param_t *) apreq_upload(const apr_table_t *body,
 199                                                   const char *name);
 200
 201
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205
 206 #endif /* APREQ_PARAM_H */
 207
 208
 209