1 /* Character set conversion with error handling. 2 Copyright (C) 2001-2007, 2009-2020 Free Software Foundation, Inc. 3 Written by Bruno Haible and Simon Josefsson. 4 5 This program is free software: you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 3 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program. If not, see <https://www.gnu.org/licenses/>. */ 17 18 #ifndef _STRICONVEH_H 19 #define _STRICONVEH_H 20 21 #include <stddef.h> 22 #if HAVE_ICONV 23 #include <iconv.h> 24 #endif 25 26 #include "iconveh.h" 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 34 #if HAVE_ICONV 35 36 /* A conversion descriptor for use by the iconveh functions. */ 37 typedef struct 38 { 39 /* Conversion descriptor from FROM_CODESET to TO_CODESET, or (iconv_t)(-1) 40 if the system does not support a direct conversion from FROM_CODESET to 41 TO_CODESET. */ 42 iconv_t cd; 43 /* Conversion descriptor from FROM_CODESET to UTF-8 (or (iconv_t)(-1) if 44 FROM_CODESET is UTF-8). */ 45 iconv_t cd1; 46 /* Conversion descriptor from UTF-8 to TO_CODESET (or (iconv_t)(-1) if 47 TO_CODESET is UTF-8). */ 48 iconv_t cd2; 49 } 50 iconveh_t; 51 52 /* Open a conversion descriptor for use by the iconveh functions. 53 If successful, fills *CDP and returns 0. Upon failure, return -1 with errno 54 set. */ 55 extern int 56 iconveh_open (const char *to_codeset, const char *from_codeset, 57 iconveh_t *cdp); 58 59 /* Close a conversion descriptor created by iconveh_open(). 60 Return value: 0 if successful, otherwise -1 and errno set. */ 61 extern int 62 iconveh_close (const iconveh_t *cd); 63 64 /* Convert an entire string from one encoding to another, using iconv. 65 The original string is at [SRC,...,SRC+SRCLEN-1]. 66 CD points to the conversion descriptor from FROMCODE to TOCODE, created by 67 the function iconveh_open(). 68 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this 69 array is filled with offsets into the result, i.e. the character starting 70 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]], 71 and other offsets are set to (size_t)(-1). 72 *RESULTP and *LENGTH should initially be a scratch buffer and its size, 73 or *RESULTP can initially be NULL. 74 May erase the contents of the memory at *RESULTP. 75 Return value: 0 if successful, otherwise -1 and errno set. 76 If successful: The resulting string is stored in *RESULTP and its length 77 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is 78 unchanged if no dynamic memory allocation was necessary. */ 79 extern int 80 mem_cd_iconveh (const char *src, size_t srclen, 81 const iconveh_t *cd, 82 enum iconv_ilseq_handler handler, 83 size_t *offsets, 84 char **resultp, size_t *lengthp); 85 86 /* Convert an entire string from one encoding to another, using iconv. 87 The original string is the NUL-terminated string starting at SRC. 88 CD points to the conversion descriptor from FROMCODE to TOCODE, created by 89 the function iconveh_open(). 90 Both the "from" and the "to" encoding must use a single NUL byte at the end 91 of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32). 92 Allocate a malloced memory block for the result. 93 Return value: the freshly allocated resulting NUL-terminated string if 94 successful, otherwise NULL and errno set. */ 95 extern char * 96 str_cd_iconveh (const char *src, 97 const iconveh_t *cd, 98 enum iconv_ilseq_handler handler); 99 100 #endif 101 102 /* Convert an entire string from one encoding to another, using iconv. 103 The original string is at [SRC,...,SRC+SRCLEN-1]. 104 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this 105 array is filled with offsets into the result, i.e. the character starting 106 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]], 107 and other offsets are set to (size_t)(-1). 108 *RESULTP and *LENGTH should initially be a scratch buffer and its size, 109 or *RESULTP can initially be NULL. 110 May erase the contents of the memory at *RESULTP. 111 Return value: 0 if successful, otherwise -1 and errno set. 112 If successful: The resulting string is stored in *RESULTP and its length 113 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is 114 unchanged if no dynamic memory allocation was necessary. */ 115 extern int 116 mem_iconveh (const char *src, size_t srclen, 117 const char *from_codeset, const char *to_codeset, 118 enum iconv_ilseq_handler handler, 119 size_t *offsets, 120 char **resultp, size_t *lengthp); 121 122 /* Convert an entire string from one encoding to another, using iconv. 123 The original string is the NUL-terminated string starting at SRC. 124 Both the "from" and the "to" encoding must use a single NUL byte at the 125 end of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32). 126 Allocate a malloced memory block for the result. 127 Return value: the freshly allocated resulting NUL-terminated string if 128 successful, otherwise NULL and errno set. */ 129 extern char * 130 str_iconveh (const char *src, 131 const char *from_codeset, const char *to_codeset, 132 enum iconv_ilseq_handler handler); 133 134 135 #ifdef __cplusplus 136 } 137 #endif 138 139 140 #endif /* _STRICONVEH_H */ 141