qemu/roms/ipxe/src/include/ipxe/uri.h

   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 );
  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  */
 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_encode ( const char *string, unsigned int field,
 195                            char *buf, ssize_t len );
 196 extern struct uri * parse_uri ( const char *uri_string );
 197 extern size_t format_uri ( const struct uri *uri, char *buf, size_t len );
 198 extern char * format_uri_alloc ( const struct uri *uri );
 199 extern unsigned int uri_port ( const struct uri *uri,
 200                                unsigned int default_port );
 201 extern struct uri * uri_dup ( const struct uri *uri );
 202 extern char * resolve_path ( const char *base_path,
 203                              const char *relative_path );
 204 extern struct uri * resolve_uri ( const struct uri *base_uri,
 205                                   struct uri *relative_uri );
 206 extern struct uri * tftp_uri ( struct in_addr next_server,
 207                                const char *filename );
 208 extern void churi ( struct uri *uri );
 209
 210 #endif /* _IPXE_URI_H */