root/opal/util/uri.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 /*
   2  * Copyright (c) 2012      Los Alamos National Security, LLC.
   3  *                         All rights reserved.
   4  * $COPYRIGHT$
   5  *
   6  * Additional copyrights may follow
   7  *
   8  * $HEADER$
   9  *
  10  * @file
  11  */
  12 
  13 /*
  14   Per RFC3986:
  15   The generic URI syntax consists of a hierarchical sequence of
  16    components referred to as the scheme, authority, path, query, and
  17    fragment.
  18 
  19       URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
  20 
  21       hier-part   = "//" authority path-abempty
  22                   / path-absolute
  23                   / path-rootless
  24                   / path-empty
  25 
  26    The scheme and path components are required, though the path may be
  27    empty (no characters).  When authority is present, the path must
  28    either be empty or begin with a slash ("/") character.  When
  29    authority is not present, the path cannot begin with two slash
  30    characters ("//").  These restrictions result in five different ABNF
  31    rules for a path (Section 3.3), only one of which will match any
  32    given URI reference.
  33 
  34    The following are two example URIs and their component parts:
  35 
  36          foo://example.com:8042/over/there?name=ferret#nose
  37          \_/   \______________/\_________/ \_________/ \__/
  38           |           |            |            |        |
  39        scheme     authority       path        query   fragment
  40           |   _____________________|__
  41          / \ /                        \
  42          urn:example:animal:ferret:nose
  43 
  44    Initially, this code supports only part of the first example - a scheme
  45    followed by an authority and a path. Queries and fragments are
  46    not supported. The APIs are modeled on the Gnome equivalent functions,
  47    though the code is NOT in any way based on thoat code.
  48 */
  49 
  50 #ifndef OPAL_URI_H
  51 #define OPAL_URI_H
  52 
  53 #include "opal_config.h"
  54 
  55 #ifdef HAVE_UNISTD_H
  56 #include <unistd.h>
  57 #endif
  58 
  59 BEGIN_C_DECLS
  60 
  61 /**
  62  * Parse a uri to retrieve the scheme
  63  *
  64  * The caller is responsible for freeing the returned string.
  65  */
  66 OPAL_DECLSPEC char *opal_uri_get_scheme(const char *uri) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__;
  67 
  68 /**
  69  *  Create a uri from a hostname and filename
  70  *
  71  * The caller is responsible for freeing the returned string.
  72  */
  73 OPAL_DECLSPEC char *opal_filename_to_uri(const char *filename,
  74                                          const char *hostname) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__;
  75 /**
  76  * Extract the filename (and hostname) from a uri
  77  *
  78  * @param uri : a uri describing a filename (escaped, encoded in ASCII).
  79  * @param hostname : Location to store hostname for the URI, or NULL.
  80  *                   If there is no hostname in the URI, NULL will be
  81  *                   stored in this location.
  82  * @retval a newly-allocated string holding the resulting filename, or NULL on an error.
  83  *
  84  * The caller is responsible for freeing the returned string.
  85  */
  86 OPAL_DECLSPEC char *opal_filename_from_uri(const char *uri,
  87                                            char **hostname) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__;
  88 
  89 END_C_DECLS
  90 #endif /* OPAL_URI_H */

/* [<][>][^][v][top][bottom][index][help] */