Apache Portable Runtime
apr_uri.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /*
00018  * apr_uri.h: External Interface of apr_uri.c
00019  */
00020 
00021 /**
00022  * @file apr_uri.h
00023  * @brief APR-UTIL URI Routines
00024  */
00025 
00026 #ifndef APR_URI_H
00027 #define APR_URI_H
00028 
00029 #include "apu.h"
00030 
00031 #include "apr_network_io.h"
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif
00036 
00037 /**
00038  * @defgroup APR_Util_URI URI
00039  * @ingroup APR
00040  * @{
00041  */
00042 
00043 #define APR_URI_FTP_DEFAULT_PORT         21 /**< default FTP port */
00044 #define APR_URI_SSH_DEFAULT_PORT         22 /**< default SSH port */
00045 #define APR_URI_TELNET_DEFAULT_PORT      23 /**< default telnet port */
00046 #define APR_URI_GOPHER_DEFAULT_PORT      70 /**< default Gopher port */
00047 #define APR_URI_HTTP_DEFAULT_PORT        80 /**< default HTTP port */
00048 #define APR_URI_POP_DEFAULT_PORT        110 /**< default POP port */
00049 #define APR_URI_NNTP_DEFAULT_PORT       119 /**< default NNTP port */
00050 #define APR_URI_IMAP_DEFAULT_PORT       143 /**< default IMAP port */
00051 #define APR_URI_PROSPERO_DEFAULT_PORT   191 /**< default Prospero port */
00052 #define APR_URI_WAIS_DEFAULT_PORT       210 /**< default WAIS port */
00053 #define APR_URI_LDAP_DEFAULT_PORT       389 /**< default LDAP port */
00054 #define APR_URI_HTTPS_DEFAULT_PORT      443 /**< default HTTPS port */
00055 #define APR_URI_RTSP_DEFAULT_PORT       554 /**< default RTSP port */
00056 #define APR_URI_SNEWS_DEFAULT_PORT      563 /**< default SNEWS port */
00057 #define APR_URI_ACAP_DEFAULT_PORT       674 /**< default ACAP port */
00058 #define APR_URI_NFS_DEFAULT_PORT       2049 /**< default NFS port */
00059 #define APR_URI_TIP_DEFAULT_PORT       3372 /**< default TIP port */
00060 #define APR_URI_SIP_DEFAULT_PORT       5060 /**< default SIP port */
00061 
00062 /** Flags passed to unparse_uri_components(): */
00063 /** suppress "scheme://user\@site:port" */
00064 #define APR_URI_UNP_OMITSITEPART    (1U<<0)
00065 /** Just omit user */
00066 #define APR_URI_UNP_OMITUSER        (1U<<1)
00067 /** Just omit password */
00068 #define APR_URI_UNP_OMITPASSWORD    (1U<<2)
00069 /** omit "user:password\@" part */
00070 #define APR_URI_UNP_OMITUSERINFO    (APR_URI_UNP_OMITUSER | \
00071                                      APR_URI_UNP_OMITPASSWORD)
00072 /** Show plain text password (default: show XXXXXXXX) */
00073 #define APR_URI_UNP_REVEALPASSWORD  (1U<<3)
00074 /** Show "scheme://user\@site:port" only */
00075 #define APR_URI_UNP_OMITPATHINFO    (1U<<4)
00076 /** Omit the "?queryarg" from the path */
00077 #define APR_URI_UNP_OMITQUERY       (1U<<5)
00078 
00079 /** @see apr_uri_t */
00080 typedef struct apr_uri_t apr_uri_t;
00081 
00082 /**
00083  * A structure to encompass all of the fields in a uri
00084  */
00085 struct apr_uri_t {
00086     /** scheme ("http"/"ftp"/...) */
00087     char *scheme;
00088     /** combined [user[:password]\@]host[:port] */
00089     char *hostinfo;
00090     /** user name, as in http://user:passwd\@host:port/ */
00091     char *user;
00092     /** password, as in http://user:passwd\@host:port/ */
00093     char *password;
00094     /** hostname from URI (or from Host: header) */
00095     char *hostname;
00096     /** port string (integer representation is in "port") */
00097     char *port_str;
00098     /** the request path (or NULL if only scheme://host was given) */
00099     char *path;
00100     /** Everything after a '?' in the path, if present */
00101     char *query;
00102     /** Trailing "#fragment" string, if present */
00103     char *fragment;
00104 
00105     /** structure returned from gethostbyname() */
00106     struct hostent *hostent;
00107 
00108     /** The port number, numeric, valid only if port_str != NULL */
00109     apr_port_t port;
00110     
00111     /** has the structure been initialized */
00112     unsigned is_initialized:1;
00113 
00114     /** has the DNS been looked up yet */
00115     unsigned dns_looked_up:1;
00116     /** has the dns been resolved yet */
00117     unsigned dns_resolved:1;
00118 };
00119 
00120 /* apr_uri.c */
00121 /**
00122  * Return the default port for a given scheme.  The schemes recognized are
00123  * http, ftp, https, gopher, wais, nntp, snews, and prospero
00124  * @param scheme_str The string that contains the current scheme
00125  * @return The default port for this scheme
00126  */ 
00127 APR_DECLARE(apr_port_t) apr_uri_port_of_scheme(const char *scheme_str);
00128 
00129 /**
00130  * Unparse a apr_uri_t structure to an URI string.  Optionally 
00131  * suppress the password for security reasons.
00132  * @param p The pool to allocate out of
00133  * @param uptr All of the parts of the uri
00134  * @param flags How to unparse the uri.  One of:
00135  * <PRE>
00136  *    APR_URI_UNP_OMITSITEPART        Suppress "scheme://user\@site:port" 
00137  *    APR_URI_UNP_OMITUSER            Just omit user 
00138  *    APR_URI_UNP_OMITPASSWORD        Just omit password 
00139  *    APR_URI_UNP_OMITUSERINFO        Omit "user:password\@" part
00140  *    APR_URI_UNP_REVEALPASSWORD      Show plain text password (default: show XXXXXXXX)
00141  *    APR_URI_UNP_OMITPATHINFO        Show "scheme://user\@site:port" only 
00142  *    APR_URI_UNP_OMITQUERY           Omit "?queryarg" or "#fragment" 
00143  * </PRE>
00144  * @return The uri as a string
00145  */
00146 APR_DECLARE(char *) apr_uri_unparse(apr_pool_t *p, 
00147                                     const apr_uri_t *uptr,
00148                                     unsigned flags);
00149 
00150 /**
00151  * Parse a given URI, fill in all supplied fields of a apr_uri_t
00152  * structure. This eliminates the necessity of extracting host, port,
00153  * path, query info repeatedly in the modules.
00154  * @param p The pool to allocate out of
00155  * @param uri The uri to parse
00156  * @param uptr The apr_uri_t to fill out
00157  * @return APR_SUCCESS for success or error code
00158  */
00159 APR_DECLARE(apr_status_t) apr_uri_parse(apr_pool_t *p, const char *uri, 
00160                                         apr_uri_t *uptr);
00161 
00162 /**
00163  * Special case for CONNECT parsing: it comes with the hostinfo part only
00164  * @param p The pool to allocate out of
00165  * @param hostinfo The hostinfo string to parse
00166  * @param uptr The apr_uri_t to fill out
00167  * @return APR_SUCCESS for success or error code
00168  */
00169 APR_DECLARE(apr_status_t) apr_uri_parse_hostinfo(apr_pool_t *p, 
00170                                                  const char *hostinfo, 
00171                                                  apr_uri_t *uptr);
00172 
00173 /** @} */
00174 #ifdef __cplusplus
00175 }
00176 #endif
00177 
00178 #endif /* APR_URI_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines