1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_CONV_FROM_UTF8_FUNCTION 5Section: 3 6Source: libcurl 7Protocol: 8 - All 9See-also: 10 - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) 11 - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) 12--- 13 14# NAME 15 16CURLOPT_CONV_FROM_UTF8_FUNCTION - convert data from UTF8 to host encoding 17 18# SYNOPSIS 19 20~~~c 21#include <curl/curl.h> 22 23CURLcode conv_callback(char *ptr, size_t length); 24 25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, 26 conv_callback); 27~~~ 28 29# DESCRIPTION 30 31Pass a pointer to your callback function, which should match the prototype 32shown above. 33 34Applies to non-ASCII platforms. curl_version_info(3) returns the 35CURL_VERSION_CONV feature bit set if this option is provided. 36 37The data to be converted is in a buffer pointed to by the *ptr* parameter. 38The amount of data to convert is indicated by the *length* parameter. The 39converted data overlays the input data in the buffer pointed to by the ptr 40parameter. *CURLE_OK* must be returned upon successful conversion. A 41CURLcode return value defined by curl.h, such as *CURLE_CONV_FAILED*, 42should be returned if an error was encountered. 43 44CURLOPT_CONV_FROM_UTF8_FUNCTION(3) converts to host encoding from UTF8 45encoding. It is required only for SSL processing. 46 47If you set a callback pointer to NULL, or do not set it at all, the built-in 48libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl 49was built, and no callback has been established, the conversion returns the 50CURLE_CONV_REQD error code. 51 52If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. 53For example: 54~~~c 55 #define CURL_ICONV_CODESET_OF_HOST "IBM-1047" 56~~~ 57 58The iconv code in libcurl defaults the network and UTF8 codeset names as 59follows: 60~~~c 61#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" 62 63#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" 64~~~ 65 66You need to override these definitions if they are different on your system. 67 68# DEFAULT 69 70NULL 71 72# EXAMPLE 73 74~~~c 75static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length) 76{ 77 int rc = 0; 78 /* in-place convert 'buffer' from UTF-8 to EBCDIC */ 79 if(rc == 0) { 80 /* success */ 81 return CURLE_OK; 82 } 83 else { 84 return CURLE_CONV_FAILED; 85 } 86} 87 88int main(void) 89{ 90 CURL *curl = curl_easy_init(); 91 curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION, 92 my_conv_from_utf8_to_ebcdic); 93} 94~~~ 95 96# AVAILABILITY 97 98Not available and deprecated since 7.82.0. 99 100Available only if **CURL_DOES_CONVERSIONS** was defined when libcurl was 101built. 102 103# RETURN VALUE 104 105Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 106