iPXE
uri.h
Go to the documentation of this file.
1 #ifndef _IPXE_URI_H
2 #define _IPXE_URI_H
3 
4 /** @file
5  *
6  * Uniform Resource Identifiers
7  *
8  */
9 
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11 
12 #include <stddef.h>
13 #include <stdlib.h>
14 #include <ipxe/refcnt.h>
15 #include <ipxe/in.h>
16 
17 struct parameters;
18 
19 /** A Uniform Resource Identifier
20  *
21  * Terminology for this data structure is as per uri(7), except that
22  * "path" is defined to include the leading '/' for an absolute path.
23  *
24  * Note that all fields within a URI are optional and may be NULL.
25  *
26  * The pointers to the various fields are packed together so they can
27  * be accessed in array fashion in some places in uri.c where doing so
28  * saves significant code size.
29  *
30  * Some examples are probably helpful:
31  *
32  * http://www.ipxe.org/wiki :
33  *
34  * scheme = "http", host = "www.ipxe.org", path = "/wiki"
35  *
36  * /var/lib/tftpboot :
37  *
38  * path = "/var/lib/tftpboot"
39  *
40  * mailto:bob@nowhere.com :
41  *
42  * scheme = "mailto", opaque = "bob@nowhere.com"
43  *
44  * ftp://joe:secret@insecure.org:8081/hidden/path/to?what=is#this
45  *
46  * scheme = "ftp", user = "joe", password = "secret",
47  * host = "insecure.org", port = "8081", path = "/hidden/path/to",
48  * query = "what=is", fragment = "this"
49  *
50  * The URI syntax includes a percent-encoding mechanism that can be
51  * used to represent characters that would otherwise not be possible,
52  * such as a '/' character within the password field. These encodings
53  * are decoded during the URI parsing stage, thereby allowing protocol
54  * implementations to consume the raw field values directly without
55  * further decoding.
56  *
57  * Some protocols (such as HTTP) communicate using URI-encoded values.
58  * For these protocols, the original encoded substring must be
59  * retained verbatim since the choice of whether or not to encode a
60  * particular character may have significance to the receiving
61  * application. We therefore retain the originally-encoded substrings
62  * for the path, query, and fragment fields.
63  */
64 struct uri {
65  /** Reference count */
66  struct refcnt refcnt;
67  /** Scheme */
68  const char *scheme;
69  /** Opaque part */
70  const char *opaque;
71  /** User name */
72  const char *user;
73  /** Password */
74  const char *password;
75  /** Host name */
76  const char *host;
77  /** Port number */
78  const char *port;
79  /** Path (after URI decoding) */
80  const char *path;
81  /** Path (with original URI encoding) */
82  const char *epath;
83  /** Query (with original URI encoding) */
84  const char *equery;
85  /** Fragment (with original URI encoding) */
86  const char *efragment;
87  /** Request parameters */
88  struct parameters *params;
89 } __attribute__ (( packed ));
90 
91 /**
92  * Access URI field
93  *
94  * @v uri URI
95  * @v field URI field index
96  * @ret field URI field (as an lvalue)
97  */
98 #define uri_field( uri, field ) (&uri->scheme)[field]
99 
100 /**
101  * Calculate index of a URI field
102  *
103  * @v name URI field name
104  * @ret field URI field index
105  */
106 #define URI_FIELD( name ) \
107  ( ( offsetof ( struct uri, name ) - \
108  offsetof ( struct uri, scheme ) ) / sizeof ( void * ) )
109 
110 /** URI fields */
112  URI_SCHEME = URI_FIELD ( scheme ),
113  URI_OPAQUE = URI_FIELD ( opaque ),
115  URI_PASSWORD = URI_FIELD ( password ),
116  URI_HOST = URI_FIELD ( host ),
118  URI_PATH = URI_FIELD ( path ),
119  URI_EPATH = URI_FIELD ( epath ),
120  URI_EQUERY = URI_FIELD ( equery ),
121  URI_EFRAGMENT = URI_FIELD ( efragment ),
123 };
124 
125 /**
126  * URI is an absolute URI
127  *
128  * @v uri URI
129  * @ret is_absolute URI is absolute
130  *
131  * An absolute URI begins with a scheme, e.g. "http:" or "mailto:".
132  * Note that this is a separate concept from a URI with an absolute
133  * path.
134  */
135 static inline int uri_is_absolute ( const struct uri *uri ) {
136  return ( uri->scheme != NULL );
137 }
138 
139 /**
140  * URI has an opaque part
141  *
142  * @v uri URI
143  * @ret has_opaque URI has an opaque part
144  */
145 static inline int uri_has_opaque ( const struct uri *uri ) {
146  return ( uri->opaque && ( uri->opaque[0] != '\0' ) );
147 }
148 
149 /**
150  * URI has a path
151  *
152  * @v uri URI
153  * @ret has_path URI has a path
154  */
155 static inline int uri_has_path ( const struct uri *uri ) {
156  return ( uri->path && ( uri->path[0] != '\0' ) );
157 }
158 
159 /**
160  * URI has an absolute path
161  *
162  * @v uri URI
163  * @ret has_absolute_path URI has an absolute path
164  *
165  * An absolute path begins with a '/'. Note that this is a separate
166  * concept from an absolute URI. Note also that a URI may not have a
167  * path at all.
168  */
169 static inline int uri_has_absolute_path ( const struct uri *uri ) {
170  return ( uri->path && ( uri->path[0] == '/' ) );
171 }
172 
173 /**
174  * URI has a relative path
175  *
176  * @v uri URI
177  * @ret has_relative_path URI has a relative path
178  *
179  * A relative path begins with something other than a '/'. Note that
180  * this is a separate concept from a relative URI. Note also that a
181  * URI may not have a path at all.
182  */
183 static inline int uri_has_relative_path ( const struct uri *uri ) {
184  return ( uri->path && ( uri->path[0] != '/' ) );
185 }
186 
187 /**
188  * Increment URI reference count
189  *
190  * @v uri URI, or NULL
191  * @ret uri URI as passed in
192  */
193 static inline __attribute__ (( always_inline )) struct uri *
194 uri_get ( struct uri *uri ) {
195  ref_get ( &uri->refcnt );
196  return uri;
197 }
198 
199 /**
200  * Decrement URI reference count
201  *
202  * @v uri URI, or NULL
203  */
204 static inline __attribute__ (( always_inline )) void
205 uri_put ( struct uri *uri ) {
206  ref_put ( &uri->refcnt );
207 }
208 
209 extern struct uri *cwuri;
210 
211 extern size_t uri_decode ( const char *encoded, void *buf, size_t len );
212 extern size_t uri_encode ( unsigned int field, const void *raw, size_t raw_len,
213  char *buf, ssize_t len );
214 extern size_t uri_encode_string ( unsigned int field, const char *string,
215  char *buf, ssize_t len );
216 extern struct uri * parse_uri ( const char *uri_string );
217 extern size_t format_uri ( const struct uri *uri, char *buf, size_t len );
218 extern char * format_uri_alloc ( const struct uri *uri );
219 extern unsigned int uri_port ( const struct uri *uri,
220  unsigned int default_port );
221 extern struct uri * uri_dup ( const struct uri *uri );
222 extern char * resolve_path ( const char *base_path,
223  const char *relative_path );
224 extern struct uri * resolve_uri ( const struct uri *base_uri,
225  struct uri *relative_uri );
226 extern struct uri * pxe_uri ( struct sockaddr *sa_server,
227  const char *filename );
228 extern void churi ( struct uri *uri );
229 
230 #endif /* _IPXE_URI_H */
Definition: uri.h:116
#define __attribute__(x)
Definition: compiler.h:10
const char * equery
Query (with original URI encoding)
Definition: uri.h:84
struct uri * cwuri
Current working URI.
Definition: cwuri.c:38
static void uri_put(struct uri *uri)
Decrement URI reference count.
Definition: uri.h:205
static struct uri * uri_get(struct uri *uri)
Increment URI reference count.
Definition: uri.h:194
static int uri_is_absolute(const struct uri *uri)
URI is an absolute URI.
Definition: uri.h:135
#define URI_FIELD(name)
Calculate index of a URI field.
Definition: uri.h:106
static int uri_has_path(const struct uri *uri)
URI has a path.
Definition: uri.h:155
static int uri_has_relative_path(const struct uri *uri)
URI has a relative path.
Definition: uri.h:183
A request parameter list.
Definition: params.h:16
struct uri * parse_uri(const char *uri_string)
Parse URI.
Definition: uri.c:296
Definition: uri.h:117
size_t uri_decode(const char *encoded, void *buf, size_t len)
Decode URI field.
Definition: uri.c:53
A reference counter.
Definition: refcnt.h:26
const char * port
Port number.
Definition: uri.h:78
struct uri * resolve_uri(const struct uri *base_uri, struct uri *relative_uri)
Resolve base+relative URI.
Definition: uri.c:694
const char * scheme
Scheme.
Definition: uri.h:68
Definition: uri.h:118
u8 port
Port number.
Definition: CIB_PRM.h:31
struct ntlm_data user
User name.
Definition: ntlm.h:20
char * resolve_path(const char *base_path, const char *relative_path)
Resolve base+relative path.
Definition: uri.c:632
const char * path
Path (after URI decoding)
Definition: uri.h:80
uri_fields
URI fields.
Definition: uri.h:111
struct parameters * params
Request parameters.
Definition: uri.h:88
static size_t raw_len
Definition: base16.h:53
Generalized socket address structure.
Definition: socket.h:96
#define ref_get(refcnt)
Get additional reference to object.
Definition: refcnt.h:92
size_t format_uri(const struct uri *uri, char *buf, size_t len)
Format URI.
Definition: uri.c:471
unsigned int uri_port(const struct uri *uri, unsigned int default_port)
Get port from URI.
Definition: uri.c:455
Definition: uri.h:114
const char * host
Host name.
Definition: uri.h:76
void churi(struct uri *uri)
Change working URI.
Definition: cwuri.c:45
Definition: uri.h:119
size_t uri_encode_string(unsigned int field, const char *string, char *buf, ssize_t len)
Encode URI field string.
Definition: uri.c:235
const char * efragment
Fragment (with original URI encoding)
Definition: uri.h:86
static int uri_has_absolute_path(const struct uri *uri)
URI has an absolute path.
Definition: uri.h:169
uint32_t len
Length.
Definition: ena.h:14
const char * opaque
Opaque part.
Definition: uri.h:70
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
struct refcnt refcnt
Reference count.
Definition: uri.h:66
struct uri * uri_dup(const struct uri *uri)
Duplicate URI.
Definition: uri.c:594
Reference counting.
const char * password
Password.
Definition: uri.h:74
const char * epath
Path (with original URI encoding)
Definition: uri.h:82
__be32 raw[7]
Definition: CIB_PRM.h:28
const char * user
User name.
Definition: uri.h:72
A Uniform Resource Identifier.
Definition: uri.h:64
signed long ssize_t
Definition: stdint.h:7
struct uri * pxe_uri(struct sockaddr *sa_server, const char *filename)
Construct URI from server address and filename.
Definition: uri.c:808
char * format_uri_alloc(const struct uri *uri)
Format URI.
Definition: uri.c:540
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
static int uri_has_opaque(const struct uri *uri)
URI has an opaque part.
Definition: uri.h:145
size_t uri_encode(unsigned int field, const void *raw, size_t raw_len, char *buf, ssize_t len)
Encode URI field.
Definition: uri.c:200
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106