| /* |
| ** Licensed to the Apache Software Foundation (ASF) under one or more |
| ** contributor license agreements. See the NOTICE file distributed with |
| ** this work for additional information regarding copyright ownership. |
| ** The ASF licenses this file to You under the Apache License, Version 2.0 |
| ** (the "License"); you may not use this file except in compliance with |
| ** the License. You may obtain a copy of the License at |
| ** |
| ** http://www.apache.org/licenses/LICENSE-2.0 |
| ** |
| ** Unless required by applicable law or agreed to in writing, software |
| ** distributed under the License is distributed on an "AS IS" BASIS, |
| ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| ** See the License for the specific language governing permissions and |
| ** limitations under the License. |
| */ |
| |
| #ifndef APREQ_PARAM_H |
| #define APREQ_PARAM_H |
| |
| #include "apreq.h" |
| #include "apr_buckets.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| |
| /** |
| * @file apreq_param.h |
| * @brief Request parsing and parameter API |
| * @ingroup libapreq2 |
| */ |
| |
| |
| /** Common data structure for params and file uploads */ |
| typedef struct apreq_param_t { |
| apr_table_t *info; /**< header table associated with the param */ |
| apr_bucket_brigade *upload; /**< brigade used to spool upload files */ |
| unsigned flags; /**< charsets, taint marks, app-specific bits */ |
| const apreq_value_t v; /**< underlying name/value info */ |
| } apreq_param_t; |
| |
| |
| /** @return 1 if the taint flag is set, 0 otherwise. */ |
| static APR_INLINE |
| unsigned apreq_param_is_tainted(const apreq_param_t *p) { |
| return APREQ_FLAGS_GET(p->flags, APREQ_TAINTED); |
| } |
| |
| /** Sets the tainted flag. */ |
| static APR_INLINE |
| void apreq_param_tainted_on(apreq_param_t *p) { |
| APREQ_FLAGS_ON(p->flags, APREQ_TAINTED); |
| } |
| |
| /** Turns off the taint flag. */ |
| static APR_INLINE |
| void apreq_param_tainted_off(apreq_param_t *p) { |
| APREQ_FLAGS_OFF(p->flags, APREQ_TAINTED); |
| } |
| |
| /** Sets the character encoding for this parameter. */ |
| static APR_INLINE |
| apreq_charset_t apreq_param_charset_set(apreq_param_t *p, apreq_charset_t c) { |
| apreq_charset_t old = (apreq_charset_t) |
| APREQ_FLAGS_GET(p->flags, APREQ_CHARSET); |
| APREQ_FLAGS_SET(p->flags, APREQ_CHARSET, c); |
| return old; |
| } |
| |
| /** Gets the character encoding for this parameter. */ |
| static APR_INLINE |
| apreq_charset_t apreq_param_charset_get(apreq_param_t *p) { |
| return (apreq_charset_t)APREQ_FLAGS_GET(p->flags, APREQ_CHARSET); |
| } |
| |
| |
| /** Upgrades args and body table values to apreq_param_t structs. */ |
| static APR_INLINE |
| apreq_param_t *apreq_value_to_param(const char *val) |
| { |
| union { const char *in; char *out; } deconst; |
| |
| deconst.in = val; |
| return apreq_attr_to_type(apreq_param_t, v, |
| apreq_attr_to_type(apreq_value_t, data, deconst.out)); |
| } |
| |
| |
| |
| /** creates a param from name/value information */ |
| APREQ_DECLARE(apreq_param_t *) apreq_param_make(apr_pool_t *p, |
| const char *name, |
| const apr_size_t nlen, |
| const char *val, |
| const apr_size_t vlen); |
| |
| /** |
| * Url-decodes a name=value pair into a param. |
| * |
| * @param param points to the decoded parameter on success |
| * @param pool Pool from which the param is allocated. |
| * @param word Start of the name=value pair. |
| * @param nlen Length of urlencoded name. |
| * @param vlen Length of urlencoded value. |
| * |
| * @return APR_SUCCESS on success. |
| * @return ::APREQ_ERROR_BADSEQ or ::APREQ_ERROR_BADCHAR on malformed input. |
| * |
| * @remarks Unless vlen == 0, this function assumes there is |
| * exactly one character ('=') which separates the pair. |
| * |
| */ |
| APREQ_DECLARE(apr_status_t) apreq_param_decode(apreq_param_t **param, |
| apr_pool_t *pool, |
| const char *word, |
| apr_size_t nlen, |
| apr_size_t vlen); |
| |
| /** |
| * Url-encodes the param into a name-value pair. |
| * @param pool Pool which allocates the returned string. |
| * @param param Param to encode. |
| * @return name-value pair representing the param. |
| */ |
| APREQ_DECLARE(char *) apreq_param_encode(apr_pool_t *pool, |
| const apreq_param_t *param); |
| |
| /** |
| * Parse a url-encoded string into a param table. |
| * @param pool pool used to allocate the param data. |
| * @param t table to which the params are added. |
| * @param qs Query string to url-decode. |
| * @return APR_SUCCESS if successful, error otherwise. |
| * @remark This function uses [&;] as the set of tokens |
| * to delineate words, and will treat a word w/o '=' |
| * as a name-value pair with value-length = 0. |
| * |
| */ |
| APREQ_DECLARE(apr_status_t) apreq_parse_query_string(apr_pool_t *pool, |
| apr_table_t *t, |
| const char *qs); |
| |
| |
| /** |
| * Returns an array of parameters (apreq_param_t *) matching the given key. |
| * The key is case-insensitive. |
| * @param p Allocates the returned array. |
| * @param t the parameter table returned by apreq_args(), apreq_body() |
| * or apreq_params() |
| * @param key Null-terminated search key, case insensitive. |
| * key==NULL fetches all parameters. |
| * @return an array of apreq_param_t* (pointers) |
| * @remark Also parses the request if necessary. |
| */ |
| APREQ_DECLARE(apr_array_header_t *) apreq_params_as_array(apr_pool_t *p, |
| const apr_table_t *t, |
| const char *key); |
| |
| /** |
| * Returns a ", " -joined string containing all parameters |
| * for the requested key, an empty string if none are found. |
| * The key is case-insensitive. |
| * |
| * @param p Allocates the return string. |
| * @param t the parameter table returned by apreq_args(), apreq_body() |
| * or apreq_params() |
| * @param key Null-terminated parameter name, case insensitive. |
| * key==NULL fetches all values. |
| * @param mode Join type- see apreq_join(). |
| * @return the joined string or NULL on error |
| * @remark Also parses the request if necessary. |
| */ |
| APREQ_DECLARE(const char *) apreq_params_as_string(apr_pool_t *p, |
| const apr_table_t *t, |
| const char *key, |
| apreq_join_t mode); |
| |
| /** |
| * Returns a table of all params in req->body with non-NULL upload brigades. |
| * @param body parameter table returned by apreq_body() or apreq_params() |
| * @param pool Pool which allocates the table struct. |
| * @return Upload table. |
| * @remark Will parse the request if necessary. |
| */ |
| APREQ_DECLARE(const apr_table_t *) apreq_uploads(const apr_table_t *body, |
| apr_pool_t *pool); |
| |
| /** |
| * Returns the first param in req->body which has both param->v.name |
| * matching key (case insensitive) and param->upload != NULL. |
| * @param body parameter table returned by apreq_body() or apreq_params() |
| * @param name Parameter name. key == NULL returns first upload. |
| * @return Corresponding upload, NULL if none found. |
| * @remark Will parse the request as necessary. |
| */ |
| APREQ_DECLARE(const apreq_param_t *) apreq_upload(const apr_table_t *body, |
| const char *name); |
| |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* APREQ_PARAM_H */ |
| |
| |
| |