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 */