00001 #ifndef PROTON_URL_H 00002 #define PROTON_URL_H 00003 /* 00004 * Licensed to the Apache Software Foundation (ASF) under one 00005 * or more contributor license agreements. See the NOTICE file 00006 * distributed with this work for additional information 00007 * regarding copyright ownership. The ASF licenses this file 00008 * to you under the Apache License, Version 2.0 (the 00009 * "License"); you may not use this file except in compliance 00010 * with the License. You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, 00015 * software distributed under the License is distributed on an 00016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00017 * KIND, either express or implied. See the License for the 00018 * specific language governing permissions and limitations 00019 * under the License. 00020 */ 00021 00022 #include <proton/import_export.h> 00023 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif 00027 00028 00029 /** @file 00030 * URL API for parsing URLs. 00031 * 00032 * @defgroup url URL 00033 * @{ 00034 */ 00035 00036 /** A parsed URL */ 00037 typedef struct pn_url_t pn_url_t; 00038 00039 /** Create an empty URL */ 00040 PN_EXTERN pn_url_t *pn_url(void); 00041 00042 /** Parse a string URL as a pn_url_t. 00043 * 00044 * URL syntax: 00045 * 00046 * [ <scheme> :// ] [ <user> [ : <password> ] @ ] <host> [ : <port> ] [ / <path> ] 00047 * 00048 * `scheme`, `user`, `password`, `port` cannot contain any of '@', ':', '/' 00049 * 00050 * If the first character of `host` is '[' then it can contain any character up 00051 * to ']' (this is to allow IPv6 literal syntax). Otherwise it also cannot 00052 * contain '@', ':', '/' 00053 * 00054 * `path` can contain any character 00055 * 00056 *@param[in] url A URL string. 00057 *@return The parsed pn_url_t or NULL if url is not a valid URL string. 00058 */ 00059 PN_EXTERN pn_url_t *pn_url_parse(const char *url); 00060 00061 /** Free a URL */ 00062 PN_EXTERN void pn_url_free(pn_url_t *url); 00063 00064 /** Clear the contents of the URL. */ 00065 PN_EXTERN void pn_url_clear(pn_url_t *url); 00066 00067 /** 00068 * Return the string form of a URL. 00069 * 00070 * The returned string is owned by the pn_url_t and will become invalid if it 00071 * is modified. 00072 */ 00073 PN_EXTERN const char *pn_url_str(pn_url_t *url); 00074 00075 /** 00076 *@name Getters for parts of the URL. 00077 * 00078 *Values belong to the URL. May return NULL if the value is not set. 00079 * 00080 *@{ 00081 */ 00082 PN_EXTERN const char *pn_url_get_scheme(pn_url_t *url); 00083 PN_EXTERN const char *pn_url_get_username(pn_url_t *url); 00084 PN_EXTERN const char *pn_url_get_password(pn_url_t *url); 00085 PN_EXTERN const char *pn_url_get_host(pn_url_t *url); 00086 PN_EXTERN const char *pn_url_get_port(pn_url_t *url); 00087 PN_EXTERN const char *pn_url_get_path(pn_url_t *url); 00088 ///@} 00089 00090 /** 00091 *@name Setters for parts of the URL. 00092 * 00093 *Values are copied. Value can be NULL to indicate the part is not set. 00094 * 00095 *@{ 00096 */ 00097 PN_EXTERN void pn_url_set_scheme(pn_url_t *url, const char *scheme); 00098 PN_EXTERN void pn_url_set_username(pn_url_t *url, const char *username); 00099 PN_EXTERN void pn_url_set_password(pn_url_t *url, const char *password); 00100 PN_EXTERN void pn_url_set_host(pn_url_t *url, const char *host); 00101 PN_EXTERN void pn_url_set_port(pn_url_t *url, const char *port); 00102 PN_EXTERN void pn_url_set_path(pn_url_t *url, const char *path); 00103 ///@} 00104 00105 ///@} 00106 00107 #ifdef __cplusplus 00108 } 00109 #endif 00110 00111 #endif