Utilities/cmcurl/include/curl/urlapi.h

   1 #ifndef CURLINC_URLAPI_H
   2 #define CURLINC_URLAPI_H
   3 /***************************************************************************
   4  *                                  _   _ ____  _
   5  *  Project                     ___| | | |  _ \| |
   6  *                             / __| | | | |_) | |
   7  *                            | (__| |_| |  _ <| |___
   8  *                             \___|\___/|_| \_\_____|
   9  *
  10  * Copyright (C) 2018 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al.
  11  *
  12  * This software is licensed as described in the file COPYING, which
  13  * you should have received as part of this distribution. The terms
  14  * are also available at https://curl.se/docs/copyright.html.
  15  *
  16  * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  17  * copies of the Software, and permit persons to whom the Software is
  18  * furnished to do so, under the terms of the COPYING file.
  19  *
  20  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  21  * KIND, either express or implied.
  22  *
  23  * SPDX-License-Identifier: curl
  24  *
  25  ***************************************************************************/
  26
  27 #include "curl.h"
  28
  29 #ifdef  __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /* the error codes for the URL API */
  34 typedef enum {
  35   CURLUE_OK,
  36   CURLUE_BAD_HANDLE,          /* 1 */
  37   CURLUE_BAD_PARTPOINTER,     /* 2 */
  38   CURLUE_MALFORMED_INPUT,     /* 3 */
  39   CURLUE_BAD_PORT_NUMBER,     /* 4 */
  40   CURLUE_UNSUPPORTED_SCHEME,  /* 5 */
  41   CURLUE_URLDECODE,           /* 6 */
  42   CURLUE_OUT_OF_MEMORY,       /* 7 */
  43   CURLUE_USER_NOT_ALLOWED,    /* 8 */
  44   CURLUE_UNKNOWN_PART,        /* 9 */
  45   CURLUE_NO_SCHEME,           /* 10 */
  46   CURLUE_NO_USER,             /* 11 */
  47   CURLUE_NO_PASSWORD,         /* 12 */
  48   CURLUE_NO_OPTIONS,          /* 13 */
  49   CURLUE_NO_HOST,             /* 14 */
  50   CURLUE_NO_PORT,             /* 15 */
  51   CURLUE_NO_QUERY,            /* 16 */
  52   CURLUE_NO_FRAGMENT,         /* 17 */
  53   CURLUE_NO_ZONEID,           /* 18 */
  54   CURLUE_BAD_FILE_URL,        /* 19 */
  55   CURLUE_BAD_FRAGMENT,        /* 20 */
  56   CURLUE_BAD_HOSTNAME,        /* 21 */
  57   CURLUE_BAD_IPV6,            /* 22 */
  58   CURLUE_BAD_LOGIN,           /* 23 */
  59   CURLUE_BAD_PASSWORD,        /* 24 */
  60   CURLUE_BAD_PATH,            /* 25 */
  61   CURLUE_BAD_QUERY,           /* 26 */
  62   CURLUE_BAD_SCHEME,          /* 27 */
  63   CURLUE_BAD_SLASHES,         /* 28 */
  64   CURLUE_BAD_USER,            /* 29 */
  65   CURLUE_LAST
  66 } CURLUcode;
  67
  68 typedef enum {
  69   CURLUPART_URL,
  70   CURLUPART_SCHEME,
  71   CURLUPART_USER,
  72   CURLUPART_PASSWORD,
  73   CURLUPART_OPTIONS,
  74   CURLUPART_HOST,
  75   CURLUPART_PORT,
  76   CURLUPART_PATH,
  77   CURLUPART_QUERY,
  78   CURLUPART_FRAGMENT,
  79   CURLUPART_ZONEID /* added in 7.65.0 */
  80 } CURLUPart;
  81
  82 #define CURLU_DEFAULT_PORT (1<<0)       /* return default port number */
  83 #define CURLU_NO_DEFAULT_PORT (1<<1)    /* act as if no port number was set,
  84                                            if the port number matches the
  85                                            default for the scheme */
  86 #define CURLU_DEFAULT_SCHEME (1<<2)     /* return default scheme if
  87                                            missing */
  88 #define CURLU_NON_SUPPORT_SCHEME (1<<3) /* allow non-supported scheme */
  89 #define CURLU_PATH_AS_IS (1<<4)         /* leave dot sequences */
  90 #define CURLU_DISALLOW_USER (1<<5)      /* no user+password allowed */
  91 #define CURLU_URLDECODE (1<<6)          /* URL decode on get */
  92 #define CURLU_URLENCODE (1<<7)          /* URL encode on set */
  93 #define CURLU_APPENDQUERY (1<<8)        /* append a form style part */
  94 #define CURLU_GUESS_SCHEME (1<<9)       /* legacy curl-style guessing */
  95 #define CURLU_NO_AUTHORITY (1<<10)      /* Allow empty authority when the
  96                                            scheme is unknown. */
  97 #define CURLU_ALLOW_SPACE (1<<11)       /* Allow spaces in the URL */
  98
  99 typedef struct Curl_URL CURLU;
 100
 101 /*
 102  * curl_url() creates a new CURLU handle and returns a pointer to it.
 103  * Must be freed with curl_url_cleanup().
 104  */
 105 CURL_EXTERN CURLU *curl_url(void);
 106
 107 /*
 108  * curl_url_cleanup() frees the CURLU handle and related resources used for
 109  * the URL parsing. It will not free strings previously returned with the URL
 110  * API.
 111  */
 112 CURL_EXTERN void curl_url_cleanup(CURLU *handle);
 113
 114 /*
 115  * curl_url_dup() duplicates a CURLU handle and returns a new copy. The new
 116  * handle must also be freed with curl_url_cleanup().
 117  */
 118 CURL_EXTERN CURLU *curl_url_dup(CURLU *in);
 119
 120 /*
 121  * curl_url_get() extracts a specific part of the URL from a CURLU
 122  * handle. Returns error code. The returned pointer MUST be freed with
 123  * curl_free() afterwards.
 124  */
 125 CURL_EXTERN CURLUcode curl_url_get(CURLU *handle, CURLUPart what,
 126                                    char **part, unsigned int flags);
 127
 128 /*
 129  * curl_url_set() sets a specific part of the URL in a CURLU handle. Returns
 130  * error code. The passed in string will be copied. Passing a NULL instead of
 131  * a part string, clears that part.
 132  */
 133 CURL_EXTERN CURLUcode curl_url_set(CURLU *handle, CURLUPart what,
 134                                    const char *part, unsigned int flags);
 135
 136 /*
 137  * curl_url_strerror() turns a CURLUcode value into the equivalent human
 138  * readable error string.  This is useful for printing meaningful error
 139  * messages.
 140  */
 141 CURL_EXTERN const char *curl_url_strerror(CURLUcode);
 142
 143 #ifdef __cplusplus
 144 } /* end of extern "C" */
 145 #endif
 146
 147 #endif /* CURLINC_URLAPI_H */