1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_CONV_TO_NETWORK_FUNCTION 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) 9 - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) 10Protocol: 11 - All 12Added-in: 7.15.4 13--- 14 15# NAME 16 17CURLOPT_CONV_TO_NETWORK_FUNCTION - convert data to network from host encoding 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode conv_callback(char *ptr, size_t length); 25 26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, 27 conv_callback); 28~~~ 29 30# DESCRIPTION 31 32Pass a pointer to your callback function, which should match the prototype 33shown above. 34 35Applies to non-ASCII platforms. curl_version_info(3) returns the 36CURL_VERSION_CONV feature bit set if this option is provided. 37 38The data to be converted is in a buffer pointed to by the *ptr* parameter. 39The amount of data to convert is indicated by the *length* parameter. The 40converted data overlays the input data in the buffer pointed to by the ptr 41parameter. *CURLE_OK* must be returned upon successful conversion. A CURLcode 42return value defined by curl.h, such as *CURLE_CONV_FAILED*, should be 43returned if an error was encountered. 44 45CURLOPT_CONV_TO_NETWORK_FUNCTION(3) converts from host encoding to the 46network encoding. It is used when commands or ASCII data are sent over the 47network. 48 49If you set a callback pointer to NULL, or do not set it at all, the built-in 50libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl 51was built, and no callback has been established, the conversion returns the 52CURLE_CONV_REQD error code. 53 54If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. 55For example: 56~~~c 57define 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~~~c 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# %PROTOCOLS% 76 77# EXAMPLE 78 79~~~c 80static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length) 81{ 82 int rc = 0; 83 /* in-place convert 'buffer' from EBCDIC to ASCII */ 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 curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION, 98 my_conv_from_ebcdic_to_ascii); 99} 100~~~ 101 102# DEPRECATED 103 104Not available and deprecated since 7.82.0. 105 106Available only if **CURL_DOES_CONVERSIONS** was defined when libcurl was 107built. 108 109# %AVAILABILITY% 110 111# RETURN VALUE 112 113curl_easy_setopt(3) returns a CURLcode indicating success or error. 114 115CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 116libcurl-errors(3). 117