Apache Portable Runtime
apr_uri.h
Go to the documentation of this file.
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
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 */
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 APR_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  */
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 APR_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  */
170  const char *hostinfo,
171  apr_uri_t *uptr);
172 
173 /** @} */
174 #ifdef __cplusplus
175 }
176 #endif
177 
178 #endif /* APR_URI_H */
unsigned is_initialized
Definition: apr_uri.h:112
APR Network library.
unsigned dns_looked_up
Definition: apr_uri.h:115
char * hostinfo
Definition: apr_uri.h:89
struct hostent * hostent
Definition: apr_uri.h:106
apr_port_t port
Definition: apr_uri.h:109
char * query
Definition: apr_uri.h:101
char * password
Definition: apr_uri.h:93
apr_status_t apr_uri_parse_hostinfo(apr_pool_t *p, const char *hostinfo, apr_uri_t *uptr)
char * user
Definition: apr_uri.h:91
#define APR_DECLARE(type)
Definition: apr.h:500
Definition: apr_uri.h:85
apr_port_t apr_uri_port_of_scheme(const char *scheme_str)
char * fragment
Definition: apr_uri.h:103
unsigned dns_resolved
Definition: apr_uri.h:117
char * scheme
Definition: apr_uri.h:87
char * path
Definition: apr_uri.h:99
apr_status_t apr_uri_parse(apr_pool_t *p, const char *uri, apr_uri_t *uptr)
char * hostname
Definition: apr_uri.h:95
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
int apr_status_t
Definition: apr_errno.h:44
apr_uint16_t apr_port_t
Definition: apr_network_io.h:257
char * apr_uri_unparse(apr_pool_t *p, const apr_uri_t *uptr, unsigned flags)
char * port_str
Definition: apr_uri.h:97