contrib/apr-util/include/apr_uri.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /*
  18  * apr_uri.h: External Interface of apr_uri.c
  19  */
  20
  21 /**
  22  * @file apr_uri.h
  23  * @brief APR-UTIL URI Routines
  24  */
  25
  26 #ifndef APR_URI_H
  27 #define APR_URI_H
  28
  29 #include "apu.h"
  30
  31 #include "apr_network_io.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * @defgroup APR_Util_URI URI
  39  * @ingroup APR_Util
  40  * @{
  41  */
  42
  43 #define APR_URI_FTP_DEFAULT_PORT         21 /**< default FTP port */
  44 #define APR_URI_SSH_DEFAULT_PORT         22 /**< default SSH port */
  45 #define APR_URI_TELNET_DEFAULT_PORT      23 /**< default telnet port */
  46 #define APR_URI_GOPHER_DEFAULT_PORT      70 /**< default Gopher port */
  47 #define APR_URI_HTTP_DEFAULT_PORT        80 /**< default HTTP port */
  48 #define APR_URI_POP_DEFAULT_PORT        110 /**< default POP port */
  49 #define APR_URI_NNTP_DEFAULT_PORT       119 /**< default NNTP port */
  50 #define APR_URI_IMAP_DEFAULT_PORT       143 /**< default IMAP port */
  51 #define APR_URI_PROSPERO_DEFAULT_PORT   191 /**< default Prospero port */
  52 #define APR_URI_WAIS_DEFAULT_PORT       210 /**< default WAIS port */
  53 #define APR_URI_LDAP_DEFAULT_PORT       389 /**< default LDAP port */
  54 #define APR_URI_HTTPS_DEFAULT_PORT      443 /**< default HTTPS port */
  55 #define APR_URI_RTSP_DEFAULT_PORT       554 /**< default RTSP port */
  56 #define APR_URI_SNEWS_DEFAULT_PORT      563 /**< default SNEWS port */
  57 #define APR_URI_ACAP_DEFAULT_PORT       674 /**< default ACAP port */
  58 #define APR_URI_NFS_DEFAULT_PORT       2049 /**< default NFS port */
  59 #define APR_URI_TIP_DEFAULT_PORT       3372 /**< default TIP port */
  60 #define APR_URI_SIP_DEFAULT_PORT       5060 /**< default SIP port */
  61
  62 /** Flags passed to unparse_uri_components(): */
  63 /** suppress "scheme://user\@site:port" */
  64 #define APR_URI_UNP_OMITSITEPART    (1U<<0)
  65 /** Just omit user */
  66 #define APR_URI_UNP_OMITUSER        (1U<<1)
  67 /** Just omit password */
  68 #define APR_URI_UNP_OMITPASSWORD    (1U<<2)
  69 /** omit "user:password\@" part */
  70 #define APR_URI_UNP_OMITUSERINFO    (APR_URI_UNP_OMITUSER | \
  71                                      APR_URI_UNP_OMITPASSWORD)
  72 /** Show plain text password (default: show XXXXXXXX) */
  73 #define APR_URI_UNP_REVEALPASSWORD  (1U<<3)
  74 /** Show "scheme://user\@site:port" only */
  75 #define APR_URI_UNP_OMITPATHINFO    (1U<<4)
  76 /** Omit the "?queryarg" from the path */
  77 #define APR_URI_UNP_OMITQUERY       (1U<<5)
  78
  79 /** @see apr_uri_t */
  80 typedef struct apr_uri_t apr_uri_t;
  81
  82 /**
  83  * A structure to encompass all of the fields in a uri
  84  */
  85 struct apr_uri_t {
  86     /** scheme ("http"/"ftp"/...) */
  87     char *scheme;
  88     /** combined [user[:password]\@]host[:port] */
  89     char *hostinfo;
  90     /** user name, as in http://user:passwd\@host:port/ */
  91     char *user;
  92     /** password, as in http://user:passwd\@host:port/ */
  93     char *password;
  94     /** hostname from URI (or from Host: header) */
  95     char *hostname;
  96     /** port string (integer representation is in "port") */
  97     char *port_str;
  98     /** the request path (or NULL if only scheme://host was given) */
  99     char *path;
 100     /** Everything after a '?' in the path, if present */
 101     char *query;
 102     /** Trailing "#fragment" string, if present */
 103     char *fragment;
 104
 105     /** structure returned from gethostbyname() */
 106     struct hostent *hostent;
 107
 108     /** The port number, numeric, valid only if port_str != NULL */
 109     apr_port_t port;
 110
 111     /** has the structure been initialized */
 112     unsigned is_initialized:1;
 113
 114     /** has the DNS been looked up yet */
 115     unsigned dns_looked_up:1;
 116     /** has the dns been resolved yet */
 117     unsigned dns_resolved:1;
 118 };
 119
 120 /* apr_uri.c */
 121 /**
 122  * Return the default port for a given scheme.  The schemes recognized are
 123  * http, ftp, https, gopher, wais, nntp, snews, and prospero
 124  * @param scheme_str The string that contains the current scheme
 125  * @return The default port for this scheme
 126  */
 127 APU_DECLARE(apr_port_t) apr_uri_port_of_scheme(const char *scheme_str);
 128
 129 /**
 130  * Unparse a apr_uri_t structure to an URI string.  Optionally
 131  * suppress the password for security reasons.
 132  * @param p The pool to allocate out of
 133  * @param uptr All of the parts of the uri
 134  * @param flags How to unparse the uri.  One of:
 135  * <PRE>
 136  *    APR_URI_UNP_OMITSITEPART        Suppress "scheme://user\@site:port"
 137  *    APR_URI_UNP_OMITUSER            Just omit user
 138  *    APR_URI_UNP_OMITPASSWORD        Just omit password
 139  *    APR_URI_UNP_OMITUSERINFO        Omit "user:password\@" part
 140  *    APR_URI_UNP_REVEALPASSWORD      Show plain text password (default: show XXXXXXXX)
 141  *    APR_URI_UNP_OMITPATHINFO        Show "scheme://user\@site:port" only
 142  *    APR_URI_UNP_OMITQUERY           Omit "?queryarg" or "#fragment"
 143  * </PRE>
 144  * @return The uri as a string
 145  */
 146 APU_DECLARE(char *) apr_uri_unparse(apr_pool_t *p,
 147                                     const apr_uri_t *uptr,
 148                                     unsigned flags);
 149
 150 /**
 151  * Parse a given URI, fill in all supplied fields of a apr_uri_t
 152  * structure. This eliminates the necessity of extracting host, port,
 153  * path, query info repeatedly in the modules.
 154  * @param p The pool to allocate out of
 155  * @param uri The uri to parse
 156  * @param uptr The apr_uri_t to fill out
 157  * @return APR_SUCCESS for success or error code
 158  */
 159 APU_DECLARE(apr_status_t) apr_uri_parse(apr_pool_t *p, const char *uri,
 160                                         apr_uri_t *uptr);
 161
 162 /**
 163  * Special case for CONNECT parsing: it comes with the hostinfo part only
 164  * @param p The pool to allocate out of
 165  * @param hostinfo The hostinfo string to parse
 166  * @param uptr The apr_uri_t to fill out
 167  * @return APR_SUCCESS for success or error code
 168  */
 169 APU_DECLARE(apr_status_t) apr_uri_parse_hostinfo(apr_pool_t *p,
 170                                                  const char *hostinfo,
 171                                                  apr_uri_t *uptr);
 172
 173 /** @} */
 174 #ifdef __cplusplus
 175 }
 176 #endif
 177
 178 #endif /* APR_URI_H */