libtranscript
 All Data Structures Functions Variables Enumerations Enumerator Modules
transcript.h
1 /* Copyright (C) 2011,2013 G.P. Halkes
2  This program is free software: you can redistribute it and/or modify
3  it under the terms of the GNU General Public License version 3, as
4  published by the Free Software Foundation.
5 
6  This program is distributed in the hope that it will be useful,
7  but WITHOUT ANY WARRANTY; without even the implied warranty of
8  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9  GNU General Public License for more details.
10 
11  You should have received a copy of the GNU General Public License
12  along with this program. If not, see <http://www.gnu.org/licenses/>.
13 */
14 #ifndef TRANSCRIPT_H
15 #define TRANSCRIPT_H
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20 
21 #include <stdlib.h>
22 #include <stdint.h>
23 
24 #include <transcript/api.h>
25 
43 #define TRANSCRIPT_VERSION 0
44 
48 typedef struct transcript_t transcript_t;
49 
60  /* These are only valid as argument to transcript_from_unicode and transcript_to_unicode. */
86 
87  /* NOTE: internal flags are defined in transcript_internal.h and moduledefs.h. Make sure these don't overlap! */
88 };
89 
91 typedef enum {
119 
120 typedef enum {
121  TRANSCRIPT_UTF8 = 1,
122  TRANSCRIPT_UTF16,
123  TRANSCRIPT_UTF32,
124  TRANSCRIPT_UTF16BE,
125  TRANSCRIPT_UTF16LE,
126  TRANSCRIPT_UTF32BE,
127  TRANSCRIPT_UTF32LE,
128  _TRANSCRIPT_UTFLAST
129 } transcript_utf_t;
130 
131 
132 #ifndef _TRANSCRIPT_CONST
133 #define _TRANSCRIPT_CONST const
134 #endif
135 
139 typedef struct {
140  _TRANSCRIPT_CONST char *name;
141  int available;
146 
148 #define TRANSCRIPT_SAVE_STATE_SIZE 32
149 
150 TRANSCRIPT_API transcript_error_t transcript_init(void);
151 TRANSCRIPT_API void transcript_finalize(void);
152 TRANSCRIPT_API int transcript_probe_converter(const char *name);
153 TRANSCRIPT_API transcript_t *transcript_open_converter(const char *name, transcript_utf_t utf_type, int flags, transcript_error_t *error);
154 TRANSCRIPT_API void transcript_close_converter(transcript_t *handle);
155 TRANSCRIPT_API int transcript_equal(const char *name_a, const char *name_b);
156 TRANSCRIPT_API transcript_error_t transcript_to_unicode(transcript_t *handle, const char **inbuf,
157  const char *inbuflimit, char **outbuf, const char *outbuflimit, int flags);
158 TRANSCRIPT_API transcript_error_t transcript_from_unicode(transcript_t *handle, const char **inbuf,
159  const char *inbuflimit, char **outbuf, const char *outbuflimit, int flags);
160 TRANSCRIPT_API transcript_error_t transcript_to_unicode_skip(transcript_t *handle, const char **inbuf, const char *inbuflimit);
161 TRANSCRIPT_API transcript_error_t transcript_from_unicode_skip(transcript_t *handle, const char **inbuf, const char *inbuflimit);
162 TRANSCRIPT_API transcript_error_t transcript_from_unicode_flush(transcript_t *handle, char **outbuf, const char *outbuflimit);
163 TRANSCRIPT_API void transcript_to_unicode_reset(transcript_t *handle);
164 TRANSCRIPT_API void transcript_from_unicode_reset(transcript_t *handle);
165 TRANSCRIPT_API void transcript_save_state(transcript_t *handle, void *state);
166 /*FIXME: should we do loading (and perhaps saving) per direction?*/
167 TRANSCRIPT_API void transcript_load_state(transcript_t *handle, void *state);
168 TRANSCRIPT_API const char *transcript_strerror(transcript_error_t error);
169 TRANSCRIPT_API const transcript_name_t *transcript_get_names(int *count);
170 TRANSCRIPT_API void transcript_normalize_name(const char *name, char *normalized_name, size_t normalized_name_max);
171 TRANSCRIPT_API const char *transcript_get_codeset(void);
172 TRANSCRIPT_API long transcript_get_version(void);
173 
175 #define TRANSCRIPT_MIN_UNICODE_BUFFER_SIZE (4*20)
176 
177 #define TRANSCRIPT_MIN_CODEPAGE_BUFFER_SIZE (32)
178 
180 #define TRANSCRIPT_MIN_BUFFER_SIZE TRANSCRIPT_MIN_UNICODE_BUFFER_SIZE
181 
184 #if defined(TRANSCRIPT_ICONV_API) || defined(TRANSCRIPT_ICONV)
185 
199 typedef struct _transcript_iconv_t *transcript_iconv_t;
200 
201 TRANSCRIPT_API transcript_iconv_t transcript_iconv_open(const char *tocode, const char *fromcode);
202 TRANSCRIPT_API int transcript_iconv_close(transcript_iconv_t cd);
203 TRANSCRIPT_API size_t transcript_iconv(transcript_iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
204 
207 #ifdef TRANSCRIPT_ICONV
208 typedef transcript_iconv_t iconv_t;
209 #define iconv(_a, _b, _c, _d, _e) transcript_iconv((_a), (_b), (_c), (_d), (_e))
210 #define iconv_open(_a, _b) transcript_iconv_open((_a), (_b))
211 #define iconv_close(_a) transcript_iconv_close(_a)
212 #endif
213 #endif
214 
215 #ifdef __cplusplus
216 }
217 #endif
218 
219 #endif
Invalid format while reading conversion map.
Definition: transcript.h:106
int available
A boolean indicating whether the converter is available.
Definition: transcript.h:141
transcript_error_t transcript_init(void)
Initialize the library.
Definition: transcript.c:434
The end of the input does not form a valid sequence.
Definition: transcript.h:99
Out of memory.
Definition: transcript.h:105
void transcript_from_unicode_reset(transcript_t *handle)
Reset the from-Unicode conversion to its initial state.
Definition: transcript.c:289
transcript_error_t transcript_from_unicode_flush(transcript_t *handle, char **outbuf, const char *outbuflimit)
Write out any bytes required to create a legal output in a character set.
Definition: transcript.c:262
void transcript_save_state(transcript_t *handle, void *state)
Save a converter's state.
Definition: transcript.c:297
The converter name references a converter package file, not an actual converter.
Definition: transcript.h:112
transcript_error_t transcript_from_unicode_skip(transcript_t *handle, const char **inbuf, const char *inbuflimit)
Skip the next character in Unicode encoding.
Definition: transcript.c:240
transcript_error_t transcript_from_unicode(transcript_t *handle, const char **inbuf, const char *inbuflimit, char **outbuf, const char *outbuflimit, int flags)
Convert a buffer from Unicode to a chararcter set.
Definition: transcript.c:207
transcript_error_t
Error values.
Definition: transcript.h:91
Automatically insert a substitution character on illegal input.
Definition: transcript.h:57
int transcript_equal(const char *name_a, const char *name_b)
Check if two names describe the same converter.
Definition: transcript.c:131
Automatically replace unmappable characters by substitute characters.
Definition: transcript.h:56
transcript_flags_t
Flags for converters and conversions.
Definition: transcript.h:51
const transcript_name_t * transcript_get_names(int *count)
Retrieve the list of display names known to this instantiation of the library.
Definition: aliases.c:270
The begining of the input buffer is the begining of a file and a BOM should be expected/generated.
Definition: transcript.h:61
The end of the input buffer is the end of the text.
Definition: transcript.h:70
An opaque handle representing the transcript_iconv state.
A structure holding a display name and availability information about a converter.
Definition: transcript.h:139
Only convert the next character, then return (useful for handling fallback/unassigned characters etc)...
Definition: transcript.h:75
Do not use 1:N conversions.
Definition: transcript.h:85
Include fallback characters in the conversion.
Definition: transcript.h:52
Conversion map is of an unsupported version.
Definition: transcript.h:108
transcript_error_t transcript_to_unicode(transcript_t *handle, const char **inbuf, const char *inbuflimit, char **outbuf, const char *outbuflimit, int flags)
Convert a buffer from a chararcter set to Unicode.
Definition: transcript.c:174
The transcript library screwed up; no recovery possible.
Definition: transcript.h:100
transcript_init has not been called yet.
Definition: transcript.h:114
An opaque structure describing a converter and its state.
Definition: handle.h:28
Could not initialize dynamic module loading functionality.
Definition: transcript.h:113
Opening if the plugin failed.
Definition: transcript.h:110
There was no space left in the output buffer.
Definition: transcript.h:93
transcript_error_t transcript_to_unicode_skip(transcript_t *handle, const char **inbuf, const char *inbuflimit)
Skip the next character in character set encoding.
Definition: transcript.c:224
The converter has been explicitly disabled.
Definition: transcript.h:111
The input is an illegal sequence.
Definition: transcript.h:98
All OK.
Definition: transcript.h:92
void transcript_to_unicode_reset(transcript_t *handle)
Reset the to-Unicode conversion to its initial state.
Definition: transcript.c:280
The next character to convert maps to a private use codepoint.
Definition: transcript.h:101
transcript_iconv_t transcript_iconv_open(const char *tocode, const char *fromcode)
Open a converter (iconv compatibility interface).
Definition: transcript_iconv.c:35
int transcript_probe_converter(const char *name)
Check if a named converter is available.
Definition: transcript.c:71
_TRANSCRIPT_CONST char * name
The (display) name of the converter.
Definition: transcript.h:140
The next character to convert is a fallback mapping.
Definition: transcript.h:96
Do not use M:N conversions.
Definition: transcript.h:80
void transcript_normalize_name(const char *name, char *normalized_name, size_t normalized_name_max)
Normalize a character set name.
Definition: transcript.c:371
const char * transcript_strerror(transcript_error_t error)
Get a localized descriptive string for an error code.
Definition: transcript.c:313
Allow private-use mappings.
Definition: transcript.h:58
Highest error code which indicates success or end-of-buffer.
Definition: transcript.h:116
long transcript_get_version(void)
Get the value of TRANSCRIPT_VERSION corresponding to the actually used library.
Definition: transcript.c:421
size_t transcript_iconv(transcript_iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft)
Perform conversion (iconv compatibility interface).
Definition: transcript_iconv.c:108
Tried to load a table that is for internal use only.
Definition: transcript.h:109
Bad argument.
Definition: transcript.h:104
transcript_t * transcript_open_converter(const char *name, transcript_utf_t utf_type, int flags, transcript_error_t *error)
Open a converter.
Definition: transcript.c:94
void transcript_finalize(void)
Finalize the library use.
Definition: transcript.c:491
Tried to read a truncated conversion map.
Definition: transcript.h:107
void transcript_close_converter(transcript_t *handle)
Close a converter.
Definition: transcript.c:115
void transcript_load_state(transcript_t *handle, void *state)
Restore a converter's state.
Definition: transcript.c:305
const char * transcript_get_codeset(void)
Get a character string describing the current character set indicated by the environment.
Definition: transcript.c:400
See errno for error code.
Definition: transcript.h:103
The next character to convert is an unassigned sequence.
Definition: transcript.h:97
The buffer ended with an incomplete sequence, or more data was needed to verify a M:N conversion...
Definition: transcript.h:94
int transcript_iconv_close(transcript_iconv_t cd)
Close a converter (iconv compatibility interface).
Definition: transcript_iconv.c:79