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