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