Asterisk - The Open Source Telephony Project  21.4.1
uri.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2014, Digium, Inc.
5  *
6  * Kevin Harwell <kharwell@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 #ifndef _ASTERISK_URI_H
20 #define _ASTERISK_URI_H
21 
22 /*! \brief Opaque structure that stores uri information. */
23 struct ast_uri;
24 
25 /*!
26  * \brief Create a uri with the given parameters
27  *
28  * \param scheme the uri scheme (ex: http)
29  * \param user_info user credentials (ex: <name>\@<pass>)
30  * \param host host name or ip address
31  * \param port the port
32  * \param path the path
33  * \param query query parameters
34  * \return a structure containing parsed uri data.
35  * \retval NULL on error
36  * \since 13
37  */
38 struct ast_uri *ast_uri_create(const char *scheme, const char *user_info,
39  const char *host, const char *port,
40  const char *path, const char *query);
41 
42 /*!
43  * \brief Copy the given uri replacing any value in the new uri with
44  * any given.
45  *
46  * \param uri the uri object to copy
47  * \param scheme the uri scheme (ex: http)
48  * \param user_info user credentials (ex: <name>\@<pass>)
49  * \param host host name or ip address
50  * \param port the port
51  * \param path the path
52  * \param query query parameters
53  * \return a copy of the given uri with specified values replaced.
54  * \retval NULL on error
55  * \since 13
56  */
57 struct ast_uri *ast_uri_copy_replace(const struct ast_uri *uri, const char *scheme,
58  const char *user_info, const char *host,
59  const char *port, const char *path,
60  const char *query);
61 /*!
62  * \brief Retrieve the uri scheme.
63  *
64  * \return the uri scheme.
65  * \since 13
66  */
67 const char *ast_uri_scheme(const struct ast_uri *uri);
68 
69 /*!
70  * \brief Retrieve the uri user information.
71  *
72  * \return the uri user information.
73  * \since 13
74  */
75 const char *ast_uri_user_info(const struct ast_uri *uri);
76 
77 /*!
78  * \brief Retrieve the uri host.
79  *
80  * \return the uri host.
81  * \since 13
82  */
83 const char *ast_uri_host(const struct ast_uri *uri);
84 
85 /*!
86  * \brief Retrieve the uri port
87  *
88  * \return the uri port.
89  * \since 13
90  */
91 const char *ast_uri_port(const struct ast_uri *uri);
92 
93 /*!
94  * \brief Retrieve the uri path.
95  *
96  * \return the uri path.
97  * \since 13
98  */
99 const char *ast_uri_path(const struct ast_uri *uri);
100 
101 /*!
102  * \brief Retrieve the uri query parameters.
103  *
104  * \return the uri query parameters.
105  * \since 13
106  */
107 const char *ast_uri_query(const struct ast_uri *uri);
108 
109 /*!
110  * \brief Retrieve if the uri is of a secure type
111  *
112  * \note Secure types are recognized by an 's' at the end
113  * of the scheme.
114  *
115  * \retval True if secure.
116  * \retval False otherwise.
117  * \since 13
118  */
119 int attribute_pure ast_uri_is_secure(const struct ast_uri *uri);
120 
121 /*!
122  * \brief Parse the given uri into a structure.
123  *
124  * \note Expects the following form:
125  * \verbatim <scheme>://[user:pass@]<host>[:port][/<path>] \endverbatim
126  *
127  * \param uri a string uri to parse
128  * \return a structure containing parsed uri data.
129  * \retval NULL on error
130  * \since 13
131  */
132 struct ast_uri *ast_uri_parse(const char *uri);
133 
134 /*!
135  * \brief Parse the given http uri into a structure.
136  *
137  * \note Expects the following form:
138  * \verbatim [http[s]://][user:pass@]<host>[:port][/<path>] \endverbatim
139  *
140  * \note If no scheme is given it defaults to 'http' and if
141  * no port is specified it will default to 443 if marked
142  * secure, otherwise to 80.
143  *
144  * \param uri an http string uri to parse
145  * \return a structure containing parsed http uri data.
146  * \retval NULL on error
147  * \since 13
148  */
149 struct ast_uri *ast_uri_parse_http(const char *uri);
150 
151 /*!
152  * \brief Parse the given websocket uri into a structure.
153  *
154  * \note Expects the following form:
155  * [ws[s]://][user:pass@]<host>[:port][/<path>]
156  *
157  * \note If no scheme is given it defaults to 'ws' and if
158  * no port is specified it will default to 443 if marked
159  * secure, otherwise to 80.
160  *
161  * \param uri a websocket string uri to parse
162  * \return a structure containing parsed http uri data.
163  * \retval NULL on error
164  * \since 13
165  */
166 struct ast_uri *ast_uri_parse_websocket(const char *uri);
167 
168 /*!
169  * \brief Retrieve a string of the host and port.
170  *
171  * Combine the host and port (<host>:<port>) if the port
172  * is available, otherwise just return the host.
173  *
174  * \note Caller is responsible for release the returned string.
175  *
176  * \param uri the uri object
177  * \return a string value of the host and optional port.
178  * \since 13
179  */
180 char *ast_uri_make_host_with_port(const struct ast_uri *uri);
181 
182 #endif /* _ASTERISK_URI_H */
char * scheme
Definition: uri.c:32
Stores parsed uri information.
Definition: uri.c:30
char * user_info
Definition: uri.c:34
char * port
Definition: uri.c:38
char * path
Definition: uri.c:40
char * query
Definition: uri.c:42
char uri[0]
Definition: uri.c:44
char * host
Definition: uri.c:36