proton  0
url.h
Go to the documentation of this file.
1 #ifndef PROTON_URL_H
2 #define PROTON_URL_H
3 /*
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  */
21 
22 #include <proton/import_export.h>
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 
29 /** @file
30  * URL API for parsing URLs.
31  *
32  * @defgroup url URL
33  * @{
34  */
35 
36 /** A parsed URL */
37 typedef struct pn_url_t pn_url_t;
38 
39 /** Create an empty URL */
41 
42 /** Parse a string URL as a pn_url_t.
43  *
44  * URL syntax:
45  *
46  * [ <scheme> :// ] [ <user> [ : <password> ] @ ] <host> [ : <port> ] [ / <path> ]
47  *
48  * `scheme`, `user`, `password`, `port` cannot contain any of '@', ':', '/'
49  *
50  * If the first character of `host` is '[' then it can contain any character up
51  * to ']' (this is to allow IPv6 literal syntax). Otherwise it also cannot
52  * contain '@', ':', '/'
53  *
54  * `path` can contain any character
55  *
56  *@param[in] url A URL string.
57  *@return The parsed pn_url_t or NULL if url is not a valid URL string.
58  */
59 PN_EXTERN pn_url_t *pn_url_parse(const char *url);
60 
61 /** Free a URL */
62 PN_EXTERN void pn_url_free(pn_url_t *url);
63 
64 /** Clear the contents of the URL. */
66 
67 /**
68  * Return the string form of a URL.
69  *
70  * The returned string is owned by the pn_url_t and will become invalid if it
71  * is modified.
72  */
73 PN_EXTERN const char *pn_url_str(pn_url_t *url);
74 
75 /**
76  *@name Getters for parts of the URL.
77  *
78  *Values belong to the URL. May return NULL if the value is not set.
79  *
80  *@{
81  */
82 PN_EXTERN const char *pn_url_get_scheme(pn_url_t *url);
83 PN_EXTERN const char *pn_url_get_username(pn_url_t *url);
84 PN_EXTERN const char *pn_url_get_password(pn_url_t *url);
85 PN_EXTERN const char *pn_url_get_host(pn_url_t *url);
86 PN_EXTERN const char *pn_url_get_port(pn_url_t *url);
87 PN_EXTERN const char *pn_url_get_path(pn_url_t *url);
88 ///@}
89 
90 /**
91  *@name Setters for parts of the URL.
92  *
93  *Values are copied. Value can be NULL to indicate the part is not set.
94  *
95  *@{
96  */
97 PN_EXTERN void pn_url_set_scheme(pn_url_t *url, const char *scheme);
98 PN_EXTERN void pn_url_set_username(pn_url_t *url, const char *username);
99 PN_EXTERN void pn_url_set_password(pn_url_t *url, const char *password);
100 PN_EXTERN void pn_url_set_host(pn_url_t *url, const char *host);
101 PN_EXTERN void pn_url_set_port(pn_url_t *url, const char *port);
102 PN_EXTERN void pn_url_set_path(pn_url_t *url, const char *path);
103 ///@}
104 
105 ///@}
106 
107 #ifdef __cplusplus
108 }
109 #endif
110 
111 #endif
PN_EXTERN const char * pn_url_get_path(pn_url_t *url)
PN_EXTERN const char * pn_url_str(pn_url_t *url)
Return the string form of a URL.
PN_EXTERN void pn_url_set_port(pn_url_t *url, const char *port)
PN_EXTERN void pn_url_set_host(pn_url_t *url, const char *host)
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN const char * pn_url_get_password(pn_url_t *url)
PN_EXTERN void pn_url_set_path(pn_url_t *url, const char *path)
struct pn_url_t pn_url_t
A parsed URL.
Definition: url.h:37
PN_EXTERN pn_url_t * pn_url_parse(const char *url)
Parse a string URL as a pn_url_t.
PN_EXTERN void pn_url_clear(pn_url_t *url)
Clear the contents of the URL.
PN_EXTERN void pn_url_set_username(pn_url_t *url, const char *username)
PN_EXTERN const char * pn_url_get_port(pn_url_t *url)
PN_EXTERN const char * pn_url_get_username(pn_url_t *url)
PN_EXTERN const char * pn_url_get_scheme(pn_url_t *url)
PN_EXTERN pn_url_t * pn_url(void)
Create an empty URL.
PN_EXTERN void pn_url_free(pn_url_t *url)
Free a URL.
PN_EXTERN void pn_url_set_scheme(pn_url_t *url, const char *scheme)
PN_EXTERN const char * pn_url_get_host(pn_url_t *url)
PN_EXTERN void pn_url_set_password(pn_url_t *url, const char *password)