uri_get(NULL) and uri_put(NULL) are explicitly allowed.
[people/xl0/gpxe.git] / src / include / gpxe / uri.h
1 #ifndef _GPXE_URI_H
2 #define _GPXE_URI_H
3
4 /** @file
5  *
6  * Uniform Resource Identifiers
7  *
8  */
9
10 #include <stdlib.h>
11 #include <gpxe/refcnt.h>
12
13 /** A Uniform Resource Identifier
14  *
15  * Terminology for this data structure is as per uri(7), except that
16  * "path" is defined to include the leading '/' for an absolute path.
17  *
18  * Note that all fields within a URI are optional and may be NULL.
19  *
20  * Some examples are probably helpful:
21  *
22  *   http://www.etherboot.org/wiki :
23  *
24  *   scheme = "http", host = "www.etherboot.org", path = "/wiki"
25  *
26  *   /var/lib/tftpboot :
27  *
28  *   path = "/var/lib/tftpboot"
29  *
30  *   mailto:bob@nowhere.com :
31  *
32  *   scheme = "mailto", opaque = "bob@nowhere.com"
33  *
34  *   ftp://joe:secret@insecure.org:8081/hidden/path/to?what=is#this
35  *
36  *   scheme = "ftp", user = "joe", password = "secret",
37  *   host = "insecure.org", port = "8081", path = "/hidden/path/to",
38  *   query = "what=is", fragment = "this"
39  */
40 struct uri {
41         /** Reference count */
42         struct refcnt refcnt;
43         /** Scheme */
44         const char *scheme;
45         /** Opaque part */
46         const char *opaque;
47         /** User name */
48         const char *user;
49         /** Password */
50         const char *password;
51         /** Host name */
52         const char *host;
53         /** Port number */
54         const char *port;
55         /** Path */
56         const char *path;
57         /** Query */
58         const char *query;
59         /** Fragment */
60         const char *fragment;
61 };
62
63 /**
64  * URI is an absolute URI
65  *
66  * @v uri                       URI
67  * @ret is_absolute             URI is absolute
68  *
69  * An absolute URI begins with a scheme, e.g. "http:" or "mailto:".
70  * Note that this is a separate concept from a URI with an absolute
71  * path.
72  */
73 static inline int uri_is_absolute ( struct uri *uri ) {
74         return ( uri->scheme != NULL );
75 }
76
77 /**
78  * URI has an absolute path
79  *
80  * @v uri                       URI
81  * @ret has_absolute_path       URI has an absolute path
82  *
83  * An absolute path begins with a '/'.  Note that this is a separate
84  * concept from an absolute URI.  Note also that a URI may not have a
85  * path at all.
86  */
87 static inline int uri_has_absolute_path ( struct uri *uri ) {
88         return ( uri->path && ( uri->path[0] == '/' ) );
89 }
90
91 /**
92  * URI has a relative path
93  *
94  * @v uri                       URI
95  * @ret has_relative_path       URI has a relative path
96  *
97  * A relative path begins with something other than a '/'.  Note that
98  * this is a separate concept from a relative URI.  Note also that a
99  * URI may not have a path at all.
100  */
101 static inline int uri_has_relative_path ( struct uri *uri ) {
102         return ( uri->path && ( uri->path[0] != '/' ) );
103 }
104
105 /**
106  * Increment URI reference count
107  *
108  * @v uri               URI, or NULL
109  * @ret uri             URI as passed in
110  */
111 static inline __attribute__ (( always_inline )) struct uri *
112 uri_get ( struct uri *uri ) {
113         ref_get ( &uri->refcnt );
114         return uri;
115 }
116
117 /**
118  * Decrement URI reference count
119  *
120  * @v uri               URI, or NULL
121  */
122 static inline __attribute__ (( always_inline )) void
123 uri_put ( struct uri *uri ) {
124         ref_put ( &uri->refcnt );
125 }
126
127 extern struct uri *cwuri;
128
129 extern struct uri * parse_uri ( const char *uri_string );
130 extern unsigned int uri_port ( struct uri *uri, unsigned int default_port );
131 extern int unparse_uri ( char *buf, size_t size, struct uri *uri );
132 extern struct uri * uri_dup ( struct uri *uri );
133 extern char * resolve_path ( const char *base_path,
134                              const char *relative_path );
135 extern struct uri * resolve_uri ( struct uri *base_uri,
136                                   struct uri *relative_uri );
137 extern void churi ( struct uri *uri );
138
139 #endif /* _GPXE_URI_H */