• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 #ifndef CURLINC_URLAPI_H
2 #define CURLINC_URLAPI_H
3 /***************************************************************************
4  *                                  _   _ ____  _
5  *  Project                     ___| | | |  _ \| |
6  *                             / __| | | | |_) | |
7  *                            | (__| |_| |  _ <| |___
8  *                             \___|\___/|_| \_\_____|
9  *
10  * Copyright (C) 2018 - 2021, 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  ***************************************************************************/
24 
25 #include "curl.h"
26 
27 #ifdef  __cplusplus
28 extern "C" {
29 #endif
30 
31 /* the error codes for the URL API */
32 typedef enum {
33   CURLUE_OK,
34   CURLUE_BAD_HANDLE,          /* 1 */
35   CURLUE_BAD_PARTPOINTER,     /* 2 */
36   CURLUE_MALFORMED_INPUT,     /* 3 */
37   CURLUE_BAD_PORT_NUMBER,     /* 4 */
38   CURLUE_UNSUPPORTED_SCHEME,  /* 5 */
39   CURLUE_URLDECODE,           /* 6 */
40   CURLUE_OUT_OF_MEMORY,       /* 7 */
41   CURLUE_USER_NOT_ALLOWED,    /* 8 */
42   CURLUE_UNKNOWN_PART,        /* 9 */
43   CURLUE_NO_SCHEME,           /* 10 */
44   CURLUE_NO_USER,             /* 11 */
45   CURLUE_NO_PASSWORD,         /* 12 */
46   CURLUE_NO_OPTIONS,          /* 13 */
47   CURLUE_NO_HOST,             /* 14 */
48   CURLUE_NO_PORT,             /* 15 */
49   CURLUE_NO_QUERY,            /* 16 */
50   CURLUE_NO_FRAGMENT          /* 17 */
51 } CURLUcode;
52 
53 typedef enum {
54   CURLUPART_URL,
55   CURLUPART_SCHEME,
56   CURLUPART_USER,
57   CURLUPART_PASSWORD,
58   CURLUPART_OPTIONS,
59   CURLUPART_HOST,
60   CURLUPART_PORT,
61   CURLUPART_PATH,
62   CURLUPART_QUERY,
63   CURLUPART_FRAGMENT,
64   CURLUPART_ZONEID /* added in 7.65.0 */
65 } CURLUPart;
66 
67 #define CURLU_DEFAULT_PORT (1<<0)       /* return default port number */
68 #define CURLU_NO_DEFAULT_PORT (1<<1)    /* act as if no port number was set,
69                                            if the port number matches the
70                                            default for the scheme */
71 #define CURLU_DEFAULT_SCHEME (1<<2)     /* return default scheme if
72                                            missing */
73 #define CURLU_NON_SUPPORT_SCHEME (1<<3) /* allow non-supported scheme */
74 #define CURLU_PATH_AS_IS (1<<4)         /* leave dot sequences */
75 #define CURLU_DISALLOW_USER (1<<5)      /* no user+password allowed */
76 #define CURLU_URLDECODE (1<<6)          /* URL decode on get */
77 #define CURLU_URLENCODE (1<<7)          /* URL encode on set */
78 #define CURLU_APPENDQUERY (1<<8)        /* append a form style part */
79 #define CURLU_GUESS_SCHEME (1<<9)       /* legacy curl-style guessing */
80 #define CURLU_NO_AUTHORITY (1<<10)      /* Allow empty authority when the
81                                            scheme is unknown. */
82 #define CURLU_ALLOW_SPACE (1<<11)       /* Allow spaces in the URL */
83 
84 typedef struct Curl_URL CURLU;
85 
86 /*
87  * curl_url() creates a new CURLU handle and returns a pointer to it.
88  * Must be freed with curl_url_cleanup().
89  */
90 CURL_EXTERN CURLU *curl_url(void);
91 
92 /*
93  * curl_url_cleanup() frees the CURLU handle and related resources used for
94  * the URL parsing. It will not free strings previously returned with the URL
95  * API.
96  */
97 CURL_EXTERN void curl_url_cleanup(CURLU *handle);
98 
99 /*
100  * curl_url_dup() duplicates a CURLU handle and returns a new copy. The new
101  * handle must also be freed with curl_url_cleanup().
102  */
103 CURL_EXTERN CURLU *curl_url_dup(CURLU *in);
104 
105 /*
106  * curl_url_get() extracts a specific part of the URL from a CURLU
107  * handle. Returns error code. The returned pointer MUST be freed with
108  * curl_free() afterwards.
109  */
110 CURL_EXTERN CURLUcode curl_url_get(CURLU *handle, CURLUPart what,
111                                    char **part, unsigned int flags);
112 
113 /*
114  * curl_url_set() sets a specific part of the URL in a CURLU handle. Returns
115  * error code. The passed in string will be copied. Passing a NULL instead of
116  * a part string, clears that part.
117  */
118 CURL_EXTERN CURLUcode curl_url_set(CURLU *handle, CURLUPart what,
119                                    const char *part, unsigned int flags);
120 
121 
122 #ifdef __cplusplus
123 } /* end of extern "C" */
124 #endif
125 
126 #endif /* CURLINC_URLAPI_H */
127