1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_CONV_FROM_NETWORK_FUNCTION 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) 9 - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) 10Protocol: 11 - All 12--- 13 14# NAME 15 16CURLOPT_CONV_FROM_NETWORK_FUNCTION - convert data from network 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_NETWORK_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 35**CURL_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_NETWORK_FUNCTION(3) converts to host encoding from the 45network encoding. It is used when commands or ASCII data are received over the 46network. 47 48If you set a callback pointer to NULL, or do not set it at all, the built-in 49libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl 50was built, and no callback has been established, the conversion returns the 51**CURLE_CONV_REQD** error code. 52 53If **HAVE_ICONV** is defined, **CURL_ICONV_CODESET_OF_HOST** must also be 54defined. For example: 55 56~~~c 57#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" 58~~~ 59 60The iconv code in libcurl defaults the network and UTF8 codeset names as 61follows: 62 63~~~ 64#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" 65 66#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" 67~~~ 68 69You need to override these definitions if they are different on your system. 70 71# DEFAULT 72 73NULL 74 75# EXAMPLE 76 77~~~c 78static CURLcode my_conv_from_ascii_to_ebcdic(char *buffer, size_t length) 79{ 80 int rc = 0; 81 82 /* in-place convert 'buffer' from ASCII to EBCDIC */ 83 84 if(rc == 0) { 85 /* success */ 86 return CURLE_OK; 87 } 88 else { 89 return CURLE_CONV_FAILED; 90 } 91} 92 93int main(void) 94{ 95 CURL *curl = curl_easy_init(); 96 97 /* use platform-specific functions for codeset conversions */ 98 curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION, 99 my_conv_from_ascii_to_ebcdic); 100} 101~~~ 102 103# AVAILABILITY 104 105Not available and deprecated since 7.82.0. 106 107Available only if **CURL_DOES_CONVERSIONS** was defined when libcurl was 108built. 109 110# RETURN VALUE 111 112Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 113