httpd/include/apreq_param.h

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