uri.h

Go to the documentation of this file.

#ifndef _IPXE_URI_H
#define _IPXE_URI_H

/** @file
 *
 * Uniform Resource Identifiers
 *
 */

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );

#include <stddef.h>
#include <stdlib.h>
#include <ipxe/refcnt.h>
#include <ipxe/in.h>

struct parameters;

/** A Uniform Resource Identifier
 *
 * Terminology for this data structure is as per uri(7), except that
 * "path" is defined to include the leading '/' for an absolute path.
 *
 * Note that all fields within a URI are optional and may be NULL.
 *
 * The pointers to the various fields are packed together so they can
 * be accessed in array fashion in some places in uri.c where doing so
 * saves significant code size.
 *
 * Some examples are probably helpful:
 *
 *   http://www.ipxe.org/wiki :
 *
 *   scheme = "http", host = "www.ipxe.org", path = "/wiki"
 *
 *   /var/lib/tftpboot :
 *
 *   path = "/var/lib/tftpboot"
 *
 *   mailto:bob@nowhere.com :
 *
 *   scheme = "mailto", opaque = "bob@nowhere.com"
 *
 *   ftp://joe:secret@insecure.org:8081/hidden/path/to?what=is#this
 *
 *   scheme = "ftp", user = "joe", password = "secret",
 *   host = "insecure.org", port = "8081", path = "/hidden/path/to",
 *   query = "what=is", fragment = "this"
 *
 * The URI syntax includes a percent-encoding mechanism that can be
 * used to represent characters that would otherwise not be possible,
 * such as a '/' character within the password field.  These encodings
 * are decoded during the URI parsing stage, thereby allowing protocol
 * implementations to consume the raw field values directly without
 * further decoding.
 *
 * Some protocols (such as HTTP) communicate using URI-encoded values.
 * For these protocols, the original encoded substring must be
 * retained verbatim since the choice of whether or not to encode a
 * particular character may have significance to the receiving
 * application.  We therefore retain the originally-encoded substrings
 * for the path, query, and fragment fields.
 */
struct uri {
        /** Reference count */
        struct refcnt refcnt;
        /** Scheme */
        const char *scheme;
        /** Opaque part */
        const char *opaque;
        /** User name */
        const char *user;
        /** Password */
        const char *password;
        /** Host name */
        const char *host;
        /** Port number */
        const char *port;
        /** Path (after URI decoding) */
        const char *path;
        /** Path (with original URI encoding) */
        const char *epath;
        /** Query (with original URI encoding) */
        const char *equery;
        /** Fragment (with original URI encoding) */
        const char *efragment;
        /** Request parameters */
        struct parameters *params;
} __attribute__ (( packed ));

/**
 * Access URI field
 *
 * @v uri               URI
 * @v field             URI field index
 * @ret field           URI field (as an lvalue)
 */
#define uri_field( uri, field ) (&uri->scheme)[field]

/**
 * Calculate index of a URI field
 *
 * @v name              URI field name
 * @ret field           URI field index
 */
#define URI_FIELD( name )                                               \
        ( ( offsetof ( struct uri, name ) -                             \
            offsetof ( struct uri, scheme ) ) / sizeof ( void * ) )

/** URI fields */
enum uri_fields {
        URI_SCHEME = URI_FIELD ( scheme ),
        URI_OPAQUE = URI_FIELD ( opaque ),
        URI_USER = URI_FIELD ( user ),
        URI_PASSWORD = URI_FIELD ( password ),
        URI_HOST = URI_FIELD ( host ),
        URI_PORT = URI_FIELD ( port ),
        URI_PATH = URI_FIELD ( path ),
        URI_EPATH = URI_FIELD ( epath ),
        URI_EQUERY = URI_FIELD ( equery ),
        URI_EFRAGMENT = URI_FIELD ( efragment ),
        URI_FIELDS
};

/**
 * URI is an absolute URI
 *
 * @v uri                       URI
 * @ret is_absolute             URI is absolute
 *
 * An absolute URI begins with a scheme, e.g. "http:" or "mailto:".
 * Note that this is a separate concept from a URI with an absolute
 * path.
 */
static inline int uri_is_absolute ( const struct uri *uri ) {
        return ( uri->scheme != NULL );
}

/**
 * URI has an opaque part
 *
 * @v uri                       URI
 * @ret has_opaque              URI has an opaque part
 */
static inline int uri_has_opaque ( const struct uri *uri ) {
        return ( uri->opaque && ( uri->opaque[0] != '\0' ) );
}

/**
 * URI has a path
 *
 * @v uri                       URI
 * @ret has_path                URI has a path
 */
static inline int uri_has_path ( const struct uri *uri ) {
        return ( uri->path && ( uri->path[0] != '\0' ) );
}

/**
 * URI has an absolute path
 *
 * @v uri                       URI
 * @ret has_absolute_path       URI has an absolute path
 *
 * An absolute path begins with a '/'.  Note that this is a separate
 * concept from an absolute URI.  Note also that a URI may not have a
 * path at all.
 */
static inline int uri_has_absolute_path ( const struct uri *uri ) {
        return ( uri->path && ( uri->path[0] == '/' ) );
}

/**
 * URI has a relative path
 *
 * @v uri                       URI
 * @ret has_relative_path       URI has a relative path
 *
 * A relative path begins with something other than a '/'.  Note that
 * this is a separate concept from a relative URI.  Note also that a
 * URI may not have a path at all.
 */
static inline int uri_has_relative_path ( const struct uri *uri ) {
        return ( uri->path && ( uri->path[0] != '/' ) );
}

/**
 * Increment URI reference count
 *
 * @v uri               URI, or NULL
 * @ret uri             URI as passed in
 */
static inline __attribute__ (( always_inline )) struct uri *
uri_get ( struct uri *uri ) {
        ref_get ( &uri->refcnt );
        return uri;
}

/**
 * Decrement URI reference count
 *
 * @v uri               URI, or NULL
 */
static inline __attribute__ (( always_inline )) void
uri_put ( struct uri *uri ) {
        ref_put ( &uri->refcnt );
}

extern struct uri *cwuri;

extern size_t uri_decode ( const char *encoded, void *buf, size_t len );
extern size_t uri_encode ( unsigned int field, const void *raw, size_t raw_len,
                           char *buf, ssize_t len );
extern size_t uri_encode_string ( unsigned int field, const char *string,
                                  char *buf, ssize_t len );
extern struct uri * parse_uri ( const char *uri_string );
extern size_t format_uri ( const struct uri *uri, char *buf, size_t len );
extern char * format_uri_alloc ( const struct uri *uri );
extern unsigned int uri_port ( const struct uri *uri,
                               unsigned int default_port );
extern struct uri * uri_dup ( const struct uri *uri );
extern char * resolve_path ( const char *base_path,
                             const char *relative_path );
extern struct uri * resolve_uri ( const struct uri *base_uri,
                                  struct uri *relative_uri );
extern struct uri * pxe_uri ( struct sockaddr *sa_server,
                              const char *filename );
extern void churi ( struct uri *uri );

#endif /* _IPXE_URI_H */