CURLOPT_CONV_FROM_UTF8_FUNCTION(3)

1CURLOPT_CONV_FROM_UTF8_FUNCTcIuOrNl(_3e)asy_setopt oCpUtRiLoOnPsT_CONV_FROM_UTF8_FUNCTION(3)
2
3
4

NAME

6       CURLOPT_CONV_FROM_UTF8_FUNCTION - convert data from UTF8 to host encod‐
7       ing
8

SYNOPSIS

10       #include <curl/curl.h>
11
12       CURLcode conv_callback(char *ptr, size_t length);
13
14       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION,
15                                 conv_callback);
16

DESCRIPTION

18       Pass a pointer to your callback function, which should match the proto‐
19       type shown above.
20
21       Applies  to  non-ASCII  platforms. curl_version_info(3) will return the
22       CURL_VERSION_CONV feature bit set if this option is provided.
23
24       The data to be converted is in a buffer pointed to by the  ptr  parame‐
25       ter.   The amount of data to convert is indicated by the length parame‐
26       ter.  The converted data overlays the input data in the buffer  pointed
27       to by the ptr parameter. CURLE_OK must be returned upon successful con‐
28       version.   A  CURLcode  return  value  defined  by  curl.h,   such   as
29       CURLE_CONV_FAILED, should be returned if an error was encountered.
30
31       CURLOPT_CONV_FROM_UTF8_FUNCTION converts to host encoding from UTF8 en‐
32       coding. It is required only for SSL processing.
33
34       If you set a callback pointer to NULL, or don't  set  it  at  all,  the
35       built-in  libcurl  iconv functions will be used.  If HAVE_ICONV was not
36       defined when libcurl was built, and no callback has  been  established,
37       conversion will return the CURLE_CONV_REQD error code.
38
39       If  HAVE_ICONV  is defined, CURL_ICONV_CODESET_OF_HOST must also be de‐
40       fined.  For example:
41
42        #define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
43
44       The iconv code in libcurl will default the  network  and  UTF8  codeset
45       names as follows:
46
47        #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
48
49        #define CURL_ICONV_CODESET_FOR_UTF8   "UTF-8"
50
51       You  will  need  to override these definitions if they are different on
52       your system.
53

DEFAULT

55       NULL
56

PROTOCOLS

58       TLS-based protocols.
59

EXAMPLE

61       static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length)
62       {
63         char *tempptrin, *tempptrout;
64         size_t bytes = length;
65         int rc;
66         tempptrin = tempptrout = buffer;
67         rc = platform_u2e(&tempptrin, &bytes, &tempptrout, &bytes);
68         if(rc == PLATFORM_CONV_OK) {
69           return CURLE_OK;
70         }
71         else {
72           return CURLE_CONV_FAILED;
73         }
74       }
75
76       curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION,
77                        my_conv_from_utf8_to_ebcdic);
78

AVAILABILITY

80       Available only if CURL_DOES_CONVERSIONS was defined  when  libcurl  was
81       built.
82

RETURN VALUE

84       Returns  CURLE_OK  if the option is supported, and CURLE_UNKNOWN_OPTION
85       if not.
86