include/curl/urlapi.h

0001 #ifndef CURLINC_URLAPI_H
0002 #define CURLINC_URLAPI_H
0003 /***************************************************************************
0004  *                                  _   _ ____  _
0005  *  Project                     ___| | | |  _ \| |
0006  *                             / __| | | | |_) | |
0007  *                            | (__| |_| |  _ <| |___
0008  *                             \___|\___/|_| \_\_____|
0009  *
0010  * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
0011  *
0012  * This software is licensed as described in the file COPYING, which
0013  * you should have received as part of this distribution. The terms
0014  * are also available at https://curl.se/docs/copyright.html.
0015  *
0016  * You may opt to use, copy, modify, merge, publish, distribute and/or sell
0017  * copies of the Software, and permit persons to whom the Software is
0018  * furnished to do so, under the terms of the COPYING file.
0019  *
0020  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
0021  * KIND, either express or implied.
0022  *
0023  * SPDX-License-Identifier: curl
0024  *
0025  ***************************************************************************/
0026
0027 #include "curl.h"
0028
0029 #ifdef  __cplusplus
0030 extern "C" {
0031 #endif
0032
0033 /* the error codes for the URL API */
0034 typedef enum {
0035   CURLUE_OK,
0036   CURLUE_BAD_HANDLE,          /* 1 */
0037   CURLUE_BAD_PARTPOINTER,     /* 2 */
0038   CURLUE_MALFORMED_INPUT,     /* 3 */
0039   CURLUE_BAD_PORT_NUMBER,     /* 4 */
0040   CURLUE_UNSUPPORTED_SCHEME,  /* 5 */
0041   CURLUE_URLDECODE,           /* 6 */
0042   CURLUE_OUT_OF_MEMORY,       /* 7 */
0043   CURLUE_USER_NOT_ALLOWED,    /* 8 */
0044   CURLUE_UNKNOWN_PART,        /* 9 */
0045   CURLUE_NO_SCHEME,           /* 10 */
0046   CURLUE_NO_USER,             /* 11 */
0047   CURLUE_NO_PASSWORD,         /* 12 */
0048   CURLUE_NO_OPTIONS,          /* 13 */
0049   CURLUE_NO_HOST,             /* 14 */
0050   CURLUE_NO_PORT,             /* 15 */
0051   CURLUE_NO_QUERY,            /* 16 */
0052   CURLUE_NO_FRAGMENT,         /* 17 */
0053   CURLUE_NO_ZONEID,           /* 18 */
0054   CURLUE_BAD_FILE_URL,        /* 19 */
0055   CURLUE_BAD_FRAGMENT,        /* 20 */
0056   CURLUE_BAD_HOSTNAME,        /* 21 */
0057   CURLUE_BAD_IPV6,            /* 22 */
0058   CURLUE_BAD_LOGIN,           /* 23 */
0059   CURLUE_BAD_PASSWORD,        /* 24 */
0060   CURLUE_BAD_PATH,            /* 25 */
0061   CURLUE_BAD_QUERY,           /* 26 */
0062   CURLUE_BAD_SCHEME,          /* 27 */
0063   CURLUE_BAD_SLASHES,         /* 28 */
0064   CURLUE_BAD_USER,            /* 29 */
0065   CURLUE_LACKS_IDN,           /* 30 */
0066   CURLUE_TOO_LARGE,           /* 31 */
0067   CURLUE_LAST
0068 } CURLUcode;
0069
0070 typedef enum {
0071   CURLUPART_URL,
0072   CURLUPART_SCHEME,
0073   CURLUPART_USER,
0074   CURLUPART_PASSWORD,
0075   CURLUPART_OPTIONS,
0076   CURLUPART_HOST,
0077   CURLUPART_PORT,
0078   CURLUPART_PATH,
0079   CURLUPART_QUERY,
0080   CURLUPART_FRAGMENT,
0081   CURLUPART_ZONEID /* added in 7.65.0 */
0082 } CURLUPart;
0083
0084 #define CURLU_DEFAULT_PORT (1<<0)       /* return default port number */
0085 #define CURLU_NO_DEFAULT_PORT (1<<1)    /* act as if no port number was set,
0086                                            if the port number matches the
0087                                            default for the scheme */
0088 #define CURLU_DEFAULT_SCHEME (1<<2)     /* return default scheme if
0089                                            missing */
0090 #define CURLU_NON_SUPPORT_SCHEME (1<<3) /* allow non-supported scheme */
0091 #define CURLU_PATH_AS_IS (1<<4)         /* leave dot sequences */
0092 #define CURLU_DISALLOW_USER (1<<5)      /* no user+password allowed */
0093 #define CURLU_URLDECODE (1<<6)          /* URL decode on get */
0094 #define CURLU_URLENCODE (1<<7)          /* URL encode on set */
0095 #define CURLU_APPENDQUERY (1<<8)        /* append a form style part */
0096 #define CURLU_GUESS_SCHEME (1<<9)       /* legacy curl-style guessing */
0097 #define CURLU_NO_AUTHORITY (1<<10)      /* Allow empty authority when the
0098                                            scheme is unknown. */
0099 #define CURLU_ALLOW_SPACE (1<<11)       /* Allow spaces in the URL */
0100 #define CURLU_PUNYCODE (1<<12)          /* get the hostname in punycode */
0101 #define CURLU_PUNY2IDN (1<<13)          /* punycode => IDN conversion */
0102 #define CURLU_GET_EMPTY (1<<14)         /* allow empty queries and fragments
0103                                            when extracting the URL or the
0104                                            components */
0105 #define CURLU_NO_GUESS_SCHEME (1<<15)   /* for get, do not accept a guess */
0106
0107 typedef struct Curl_URL CURLU;
0108
0109 /*
0110  * curl_url() creates a new CURLU handle and returns a pointer to it.
0111  * Must be freed with curl_url_cleanup().
0112  */
0113 CURL_EXTERN CURLU *curl_url(void);
0114
0115 /*
0116  * curl_url_cleanup() frees the CURLU handle and related resources used for
0117  * the URL parsing. It will not free strings previously returned with the URL
0118  * API.
0119  */
0120 CURL_EXTERN void curl_url_cleanup(CURLU *handle);
0121
0122 /*
0123  * curl_url_dup() duplicates a CURLU handle and returns a new copy. The new
0124  * handle must also be freed with curl_url_cleanup().
0125  */
0126 CURL_EXTERN CURLU *curl_url_dup(const CURLU *in);
0127
0128 /*
0129  * curl_url_get() extracts a specific part of the URL from a CURLU
0130  * handle. Returns error code. The returned pointer MUST be freed with
0131  * curl_free() afterwards.
0132  */
0133 CURL_EXTERN CURLUcode curl_url_get(const CURLU *handle, CURLUPart what,
0134                                    char **part, unsigned int flags);
0135
0136 /*
0137  * curl_url_set() sets a specific part of the URL in a CURLU handle. Returns
0138  * error code. The passed in string will be copied. Passing a NULL instead of
0139  * a part string, clears that part.
0140  */
0141 CURL_EXTERN CURLUcode curl_url_set(CURLU *handle, CURLUPart what,
0142                                    const char *part, unsigned int flags);
0143
0144 /*
0145  * curl_url_strerror() turns a CURLUcode value into the equivalent human
0146  * readable error string. This is useful for printing meaningful error
0147  * messages.
0148  */
0149 CURL_EXTERN const char *curl_url_strerror(CURLUcode);
0150
0151 #ifdef __cplusplus
0152 } /* end of extern "C" */
0153 #endif
0154
0155 #endif /* CURLINC_URLAPI_H */