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
9 ** http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include "apr_buckets.h"
31 * @brief Request parsing and parameter API
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 */
45 /** @return 1 if the taint flag is set, 0 otherwise. */
47 unsigned apreq_param_is_tainted(const apreq_param_t *p) {
48 return APREQ_FLAGS_GET(p->flags, APREQ_TAINTED);
51 /** Sets the tainted flag. */
53 void apreq_param_tainted_on(apreq_param_t *p) {
54 APREQ_FLAGS_ON(p->flags, APREQ_TAINTED);
57 /** Turns off the taint flag. */
59 void apreq_param_tainted_off(apreq_param_t *p) {
60 APREQ_FLAGS_OFF(p->flags, APREQ_TAINTED);
63 /** Sets the character encoding for this parameter. */
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);
72 /** Gets the character encoding for this parameter. */
74 apreq_charset_t apreq_param_charset_get(apreq_param_t *p) {
75 return (apreq_charset_t)APREQ_FLAGS_GET(p->flags, APREQ_CHARSET);
79 /** Upgrades args and body table values to apreq_param_t structs. */
81 apreq_param_t *apreq_value_to_param(const char *val)
83 union { const char *in; char *out; } deconst;
86 return apreq_attr_to_type(apreq_param_t, v,
87 apreq_attr_to_type(apreq_value_t, data, deconst.out));
92 /** creates a param from name/value information */
93 APREQ_DECLARE(apreq_param_t *) apreq_param_make(apr_pool_t *p,
95 const apr_size_t nlen,
97 const apr_size_t vlen);
100 * Url-decodes a name=value pair into a param.
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.
108 * @return APR_SUCCESS on success.
109 * @return ::APREQ_ERROR_BADSEQ or ::APREQ_ERROR_BADCHAR on malformed input.
111 * @remarks Unless vlen == 0, this function assumes there is
112 * exactly one character ('=') which separates the pair.
115 APREQ_DECLARE(apr_status_t) apreq_param_decode(apreq_param_t **param,
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.
127 APREQ_DECLARE(char *) apreq_param_encode(apr_pool_t *pool,
128 const apreq_param_t *param);
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.
141 APREQ_DECLARE(apr_status_t) apreq_parse_query_string(apr_pool_t *pool,
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()
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.
157 APREQ_DECLARE(apr_array_header_t *) apreq_params_as_array(apr_pool_t *p,
158 const apr_table_t *t,
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.
166 * @param p Allocates the return string.
167 * @param t the parameter table returned by apreq_args(), apreq_body()
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.
175 APREQ_DECLARE(const char *) apreq_params_as_string(apr_pool_t *p,
176 const apr_table_t *t,
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.
187 APREQ_DECLARE(const apr_table_t *) apreq_uploads(const apr_table_t *body,
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.
198 APREQ_DECLARE(const apreq_param_t *) apreq_upload(const apr_table_t *body,
206 #endif /* APREQ_PARAM_H */