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 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 ),
99  URI_PASSWORD = URI_FIELD ( password ),
100  URI_HOST = URI_FIELD ( host ),
102  URI_PATH = URI_FIELD ( path ),
103  URI_QUERY = URI_FIELD ( query ),
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  */
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  */
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  */
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  */
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  */
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 *
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
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 */
Definition: uri.h:100
#define __attribute__(x)
Definition: compiler.h:10
struct uri * cwuri
Current working URI.
Definition: cwuri.c:38
static void uri_put(struct uri *uri)
Decrement URI reference count.
Definition: uri.h:188
Definition: uri.h:96
static struct uri * uri_get(struct uri *uri)
Increment URI reference count.
Definition: uri.h:177
static int uri_is_absolute(const struct uri *uri)
URI is an absolute URI.
Definition: uri.h:118
#define URI_FIELD(name)
Calculate index of a URI field.
Definition: uri.h:90
static int uri_has_path(const struct uri *uri)
URI has a path.
Definition: uri.h:138
A fragment reassembly buffer.
Definition: fragment.h:21
static int uri_has_relative_path(const struct uri *uri)
URI has a relative path.
Definition: uri.h:166
A form parameter list.
Definition: params.h:16
struct uri * parse_uri(const char *uri_string)
Parse URI.
Definition: uri.c:295
Definition: uri.h:101
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:64
struct uri * resolve_uri(const struct uri *base_uri, struct uri *relative_uri)
Resolve base+relative URI.
Definition: uri.c:676
const char * scheme
Scheme.
Definition: uri.h:54
Definition: uri.h:102
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:614
const char * path
Path.
Definition: uri.h:66
uri_fields
URI fields.
Definition: uri.h:95
struct parameters * params
Form parameters.
Definition: uri.h:72
Definition: uri.h:97
static size_t raw_len
Definition: base16.h:50
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:457
unsigned int uri_port(const struct uri *uri, unsigned int default_port)
Get port from URI.
Definition: uri.c:441
Definition: uri.h:98
const char * host
Host name.
Definition: uri.h:62
void churi(struct uri *uri)
Change working URI.
Definition: cwuri.c:45
size_t uri_encode_string(unsigned int field, const char *string, char *buf, ssize_t len)
Encode URI field string.
Definition: uri.c:236
Definition: uri.h:103
const char * query
Query.
Definition: uri.h:68
static int uri_has_absolute_path(const struct uri *uri)
URI has an absolute path.
Definition: uri.h:152
uint32_t len
Length.
Definition: ena.h:14
const char * opaque
Opaque part.
Definition: uri.h:56
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
const char * fragment
Fragment.
Definition: uri.h:70
struct refcnt refcnt
Reference count.
Definition: uri.h:52
struct uri * uri_dup(const struct uri *uri)
Duplicate URI.
Definition: uri.c:576
Reference counting.
const char * password
Password.
Definition: uri.h:60
__be32 raw[7]
Definition: CIB_PRM.h:28
const char * user
User name.
Definition: uri.h:58
A Uniform Resource Identifier.
Definition: uri.h:50
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:774
char * format_uri_alloc(const struct uri *uri)
Format URI.
Definition: uri.c:522
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
static int uri_has_opaque(const struct uri *uri)
URI has an opaque part.
Definition: uri.h:128
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:201
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106