urlapi.h 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. #ifndef CURLINC_URLAPI_H
  2. #define CURLINC_URLAPI_H
  3. /***************************************************************************
  4. * _ _ ____ _
  5. * Project ___| | | | _ \| |
  6. * / __| | | | |_) | |
  7. * | (__| |_| | _ <| |___
  8. * \___|\___/|_| \_\_____|
  9. *
  10. * Copyright (C) Daniel Stenberg, <[email protected]>, 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. #include "curl.h"
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30. /* the error codes for the URL API */
  31. typedef enum {
  32. CURLUE_OK,
  33. CURLUE_BAD_HANDLE, /* 1 */
  34. CURLUE_BAD_PARTPOINTER, /* 2 */
  35. CURLUE_MALFORMED_INPUT, /* 3 */
  36. CURLUE_BAD_PORT_NUMBER, /* 4 */
  37. CURLUE_UNSUPPORTED_SCHEME, /* 5 */
  38. CURLUE_URLDECODE, /* 6 */
  39. CURLUE_OUT_OF_MEMORY, /* 7 */
  40. CURLUE_USER_NOT_ALLOWED, /* 8 */
  41. CURLUE_UNKNOWN_PART, /* 9 */
  42. CURLUE_NO_SCHEME, /* 10 */
  43. CURLUE_NO_USER, /* 11 */
  44. CURLUE_NO_PASSWORD, /* 12 */
  45. CURLUE_NO_OPTIONS, /* 13 */
  46. CURLUE_NO_HOST, /* 14 */
  47. CURLUE_NO_PORT, /* 15 */
  48. CURLUE_NO_QUERY, /* 16 */
  49. CURLUE_NO_FRAGMENT, /* 17 */
  50. CURLUE_NO_ZONEID, /* 18 */
  51. CURLUE_BAD_FILE_URL, /* 19 */
  52. CURLUE_BAD_FRAGMENT, /* 20 */
  53. CURLUE_BAD_HOSTNAME, /* 21 */
  54. CURLUE_BAD_IPV6, /* 22 */
  55. CURLUE_BAD_LOGIN, /* 23 */
  56. CURLUE_BAD_PASSWORD, /* 24 */
  57. CURLUE_BAD_PATH, /* 25 */
  58. CURLUE_BAD_QUERY, /* 26 */
  59. CURLUE_BAD_SCHEME, /* 27 */
  60. CURLUE_BAD_SLASHES, /* 28 */
  61. CURLUE_BAD_USER, /* 29 */
  62. CURLUE_LACKS_IDN, /* 30 */
  63. CURLUE_TOO_LARGE, /* 31 */
  64. CURLUE_LAST
  65. } CURLUcode;
  66. typedef enum {
  67. CURLUPART_URL,
  68. CURLUPART_SCHEME,
  69. CURLUPART_USER,
  70. CURLUPART_PASSWORD,
  71. CURLUPART_OPTIONS,
  72. CURLUPART_HOST,
  73. CURLUPART_PORT,
  74. CURLUPART_PATH,
  75. CURLUPART_QUERY,
  76. CURLUPART_FRAGMENT,
  77. CURLUPART_ZONEID /* added in 7.65.0 */
  78. } CURLUPart;
  79. #define CURLU_DEFAULT_PORT (1<<0) /* return default port number */
  80. #define CURLU_NO_DEFAULT_PORT (1<<1) /* act as if no port number was set,
  81. if the port number matches the
  82. default for the scheme */
  83. #define CURLU_DEFAULT_SCHEME (1<<2) /* return default scheme if
  84. missing */
  85. #define CURLU_NON_SUPPORT_SCHEME (1<<3) /* allow non-supported scheme */
  86. #define CURLU_PATH_AS_IS (1<<4) /* leave dot sequences */
  87. #define CURLU_DISALLOW_USER (1<<5) /* no user+password allowed */
  88. #define CURLU_URLDECODE (1<<6) /* URL decode on get */
  89. #define CURLU_URLENCODE (1<<7) /* URL encode on set */
  90. #define CURLU_APPENDQUERY (1<<8) /* append a form style part */
  91. #define CURLU_GUESS_SCHEME (1<<9) /* legacy curl-style guessing */
  92. #define CURLU_NO_AUTHORITY (1<<10) /* Allow empty authority when the
  93. scheme is unknown. */
  94. #define CURLU_ALLOW_SPACE (1<<11) /* Allow spaces in the URL */
  95. #define CURLU_PUNYCODE (1<<12) /* get the host name in punycode */
  96. #define CURLU_PUNY2IDN (1<<13) /* punycode => IDN conversion */
  97. #define CURLU_GET_EMPTY (1<<14) /* allow empty queries and fragments
  98. when extracting the URL or the
  99. components */
  100. typedef struct Curl_URL CURLU;
  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. * curl_url_cleanup() frees the CURLU handle and related resources used for
  108. * the URL parsing. It will not free strings previously returned with the URL
  109. * API.
  110. */
  111. CURL_EXTERN void curl_url_cleanup(CURLU *handle);
  112. /*
  113. * curl_url_dup() duplicates a CURLU handle and returns a new copy. The new
  114. * handle must also be freed with curl_url_cleanup().
  115. */
  116. CURL_EXTERN CURLU *curl_url_dup(const CURLU *in);
  117. /*
  118. * curl_url_get() extracts a specific part of the URL from a CURLU
  119. * handle. Returns error code. The returned pointer MUST be freed with
  120. * curl_free() afterwards.
  121. */
  122. CURL_EXTERN CURLUcode curl_url_get(const CURLU *handle, CURLUPart what,
  123. char **part, unsigned int flags);
  124. /*
  125. * curl_url_set() sets a specific part of the URL in a CURLU handle. Returns
  126. * error code. The passed in string will be copied. Passing a NULL instead of
  127. * a part string, clears that part.
  128. */
  129. CURL_EXTERN CURLUcode curl_url_set(CURLU *handle, CURLUPart what,
  130. const char *part, unsigned int flags);
  131. /*
  132. * curl_url_strerror() turns a CURLUcode value into the equivalent human
  133. * readable error string. This is useful for printing meaningful error
  134. * messages.
  135. */
  136. CURL_EXTERN const char *curl_url_strerror(CURLUcode);
  137. #ifdef __cplusplus
  138. } /* end of extern "C" */
  139. #endif
  140. #endif /* CURLINC_URLAPI_H */