CURLOPT_CONV_TO_NETWORK_FUNCTION.3 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103
  1. .\" **************************************************************************
  2. .\" * _ _ ____ _
  3. .\" * Project ___| | | | _ \| |
  4. .\" * / __| | | | |_) | |
  5. .\" * | (__| |_| | _ <| |___
  6. .\" * \___|\___/|_| \_\_____|
  7. .\" *
  8. .\" * Copyright (C) 1998 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al.
  9. .\" *
  10. .\" * This software is licensed as described in the file COPYING, which
  11. .\" * you should have received as part of this distribution. The terms
  12. .\" * are also available at https://curl.se/docs/copyright.html.
  13. .\" *
  14. .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15. .\" * copies of the Software, and permit persons to whom the Software is
  16. .\" * furnished to do so, under the terms of the COPYING file.
  17. .\" *
  18. .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19. .\" * KIND, either express or implied.
  20. .\" *
  21. .\" **************************************************************************
  22. .\"
  23. .TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
  24. .SH NAME
  25. CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding
  26. .SH SYNOPSIS
  27. .nf
  28. #include <curl/curl.h>
  29. CURLcode conv_callback(char *ptr, size_t length);
  30. CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION,
  31. conv_callback);
  32. .SH DESCRIPTION
  33. Pass a pointer to your callback function, which should match the prototype
  34. shown above.
  35. Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
  36. CURL_VERSION_CONV feature bit set if this option is provided.
  37. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
  38. The amount of data to convert is indicated by the \fIlength\fP parameter. The
  39. converted data overlays the input data in the buffer pointed to by the ptr
  40. parameter. \fICURLE_OK\fP must be returned upon successful conversion. A
  41. CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP,
  42. should be returned if an error was encountered.
  43. \fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP converts from host encoding to the
  44. network encoding. It is used when commands or ASCII data are sent over the
  45. network.
  46. If you set a callback pointer to NULL, or do not set it at all, the built-in
  47. libcurl iconv functions will be used. If HAVE_ICONV was not defined when
  48. libcurl was built, and no callback has been established, conversion will
  49. return the CURLE_CONV_REQD error code.
  50. If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
  51. For example:
  52. \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
  53. The iconv code in libcurl will default the network and UTF8 codeset names as
  54. follows:
  55. \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
  56. \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
  57. You will need to override these definitions if they are different on your
  58. system.
  59. .SH DEFAULT
  60. NULL
  61. .SH PROTOCOLS
  62. FTP, SMTP, IMAP, POP3
  63. .SH EXAMPLE
  64. .nf
  65. static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length)
  66. {
  67. char *tempptrin, *tempptrout;
  68. size_t bytes = length;
  69. int rc;
  70. tempptrin = tempptrout = buffer;
  71. rc = platform_e2a(&tempptrin, &bytes, &tempptrout, &bytes);
  72. if(rc == PLATFORM_CONV_OK) {
  73. return CURLE_OK;
  74. }
  75. else {
  76. return CURLE_CONV_FAILED;
  77. }
  78. }
  79. curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION,
  80. my_conv_from_ebcdic_to_ascii);
  81. .fi
  82. .SH AVAILABILITY
  83. Not available since 7.82.0
  84. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was
  85. built.
  86. .SH RETURN VALUE
  87. Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
  88. .SH "SEE ALSO"
  89. .BR CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), " CURLOPT_CONV_FROM_UTF8_FUNCTION "(3), "