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 struct uri {
51 /** Reference count */
52 struct refcnt refcnt;
53 /** Scheme */
54 const char *scheme;
55 /** Opaque part */
56 const char *opaque;
57 /** User name */
58 const char *user;
59 /** Password */
60 const char *password;
61 /** Host name */
62 const char *host;
63 /** Port number */
64 const char *port;
65 /** Path */
66 const char *path;
67 /** Query */
68 const char *query;
69 /** Fragment */
70 const char *fragment;
71 /** Form parameters */
72 struct parameters *params;
73 } __attribute__ (( packed ));
74
75 /**
76 * Access URI field
77 *
78 * @v uri URI
79 * @v field URI field index
80 * @ret field URI field (as an lvalue)
81 */
82 #define uri_field( uri, field ) (&uri->scheme)[field]
83
84 /**
85 * Calculate index of a URI field
86 *
87 * @v name URI field name
88 * @ret field URI field index
89 */
90 #define URI_FIELD( name ) \
91 ( ( offsetof ( struct uri, name ) - \
92 offsetof ( struct uri, scheme ) ) / sizeof ( void * ) )
93
94 /** URI fields */
95 enum uri_fields {
96 URI_SCHEME = URI_FIELD ( scheme ),
97 URI_OPAQUE = URI_FIELD ( opaque ),
98 URI_USER = URI_FIELD ( user ),
99 URI_PASSWORD = URI_FIELD ( password ),
100 URI_HOST = URI_FIELD ( host ),
101 URI_PORT = URI_FIELD ( port ),
102 URI_PATH = URI_FIELD ( path ),
103 URI_QUERY = URI_FIELD ( query ),
104 URI_FRAGMENT = URI_FIELD ( fragment ),
105 URI_FIELDS
106 };
107
108 /**
109 * URI is an absolute URI
110 *
111 * @v uri URI
112 * @ret is_absolute URI is absolute
113 *
114 * An absolute URI begins with a scheme, e.g. "http:" or "mailto:".
115 * Note that this is a separate concept from a URI with an absolute
116 * path.
117 */
uri_is_absolute(const struct uri * uri)118 static inline int uri_is_absolute ( const struct uri *uri ) {
119 return ( uri->scheme != NULL );
120 }
121
122 /**
123 * URI has an opaque part
124 *
125 * @v uri URI
126 * @ret has_opaque URI has an opaque part
127 */
uri_has_opaque(const struct uri * uri)128 static inline int uri_has_opaque ( const struct uri *uri ) {
129 return ( uri->opaque && ( uri->opaque[0] != '\0' ) );
130 }
131
132 /**
133 * URI has a path
134 *
135 * @v uri URI
136 * @ret has_path URI has a path
137 */
uri_has_path(const struct uri * uri)138 static inline int uri_has_path ( const struct uri *uri ) {
139 return ( uri->path && ( uri->path[0] != '\0' ) );
140 }
141
142 /**
143 * URI has an absolute path
144 *
145 * @v uri URI
146 * @ret has_absolute_path URI has an absolute path
147 *
148 * An absolute path begins with a '/'. Note that this is a separate
149 * concept from an absolute URI. Note also that a URI may not have a
150 * path at all.
151 */
uri_has_absolute_path(const struct uri * uri)152 static inline int uri_has_absolute_path ( const struct uri *uri ) {
153 return ( uri->path && ( uri->path[0] == '/' ) );
154 }
155
156 /**
157 * URI has a relative path
158 *
159 * @v uri URI
160 * @ret has_relative_path URI has a relative path
161 *
162 * A relative path begins with something other than a '/'. Note that
163 * this is a separate concept from a relative URI. Note also that a
164 * URI may not have a path at all.
165 */
uri_has_relative_path(const struct uri * uri)166 static inline int uri_has_relative_path ( const struct uri *uri ) {
167 return ( uri->path && ( uri->path[0] != '/' ) );
168 }
169
170 /**
171 * Increment URI reference count
172 *
173 * @v uri URI, or NULL
174 * @ret uri URI as passed in
175 */
176 static inline __attribute__ (( always_inline )) struct uri *
uri_get(struct uri * uri)177 uri_get ( struct uri *uri ) {
178 ref_get ( &uri->refcnt );
179 return uri;
180 }
181
182 /**
183 * Decrement URI reference count
184 *
185 * @v uri URI, or NULL
186 */
187 static inline __attribute__ (( always_inline )) void
uri_put(struct uri * uri)188 uri_put ( struct uri *uri ) {
189 ref_put ( &uri->refcnt );
190 }
191
192 extern struct uri *cwuri;
193
194 extern size_t uri_decode ( const char *encoded, void *buf, size_t len );
195 extern size_t uri_encode ( unsigned int field, const void *raw, size_t raw_len,
196 char *buf, ssize_t len );
197 extern size_t uri_encode_string ( unsigned int field, const char *string,
198 char *buf, ssize_t len );
199 extern struct uri * parse_uri ( const char *uri_string );
200 extern size_t format_uri ( const struct uri *uri, char *buf, size_t len );
201 extern char * format_uri_alloc ( const struct uri *uri );
202 extern unsigned int uri_port ( const struct uri *uri,
203 unsigned int default_port );
204 extern struct uri * uri_dup ( const struct uri *uri );
205 extern char * resolve_path ( const char *base_path,
206 const char *relative_path );
207 extern struct uri * resolve_uri ( const struct uri *base_uri,
208 struct uri *relative_uri );
209 extern struct uri * pxe_uri ( struct sockaddr *sa_server,
210 const char *filename );
211 extern void churi ( struct uri *uri );
212
213 #endif /* _IPXE_URI_H */
214