Type definitions, constants and functions for the oficonv module. More...

Classes
struct	iconv_allocation_t
	space holder type for OFiconv_open_into(). More...

struct	iconv_hooks
	callback data struct for OFiconvctl() with ICONV_SET_HOOKS operation More...

struct	iconv_locale_allocation_t
	space holder type for OFlocale_charset(). More...

Macros
#define	_ICONV_VERSION 0x0108
	iconv library version constant, indicating that we have iconvctl()

#define	ICONV_TRIVIALP 0
	OFiconvctl() request macro. More...

#define	ICONV_GET_TRANSLITERATE 1
	OFiconvctl() request macro. More...

#define	ICONV_SET_TRANSLITERATE 2
	OFiconvctl() request macro. More...

#define	ICONV_GET_DISCARD_ILSEQ 3
	OFiconvctl() request macro. More...

#define	ICONV_SET_DISCARD_ILSEQ 4
	OFiconvctl() request macro. More...

#define	ICONV_SET_HOOKS 5
	OFiconvctl() request macro. More...

#define	ICONV_SET_FALLBACKS 6
	OFiconvctl() request macro. More...

#define	ICONV_GET_ILSEQ_INVALID 128
	OFiconvctl() request macro. More...

#define	ICONV_SET_ILSEQ_INVALID 129
	OFiconvctl() request macro. More...

Typedefs
typedef void(*	iconv_unicode_char_hook) (unsigned int mbr, void *data)
	callback function type for unicode char hook

typedef void(*	iconv_wide_char_hook) (_citrus_wc_t wc, void *data)
	callback function type for wide char hook

typedef void(*	oficonv_logger_callback_t) (int level, const char text1, const char text2, const char *text3)
	logger callback function pointer type More...

Functions
BEGIN_EXTERN_C DCMTK_OFICONV_EXPORT iconv_t	OFiconv_open (const char dstname, const char srcname)
	open a converter from the codeset srcname to the codeset dstname and returns its descriptor. More...

DCMTK_OFICONV_EXPORT size_t	OFiconv (iconv_t cd, char *src, size_t srcleft, char *dst, size_t dstleft)
	convert the string in the buffer src of length srcleft bytes and stores the converted string in the buffer dst of size dstleft bytes. More...

DCMTK_OFICONV_EXPORT int	OFiconv_close (iconv_t cd)
	close the specified converter cd More...

DCMTK_OFICONV_EXPORT int	OF__iconv_get_list (char **names, size_t count, __iconv_bool paired)
	obtain a list of character encodings that are supported by the OFiconv() call. More...

DCMTK_OFICONV_EXPORT void	OF__iconv_free_list (char **names, size_t count)
	free the allocated memory during the call of OF__iconv_get_list(). More...

DCMTK_OFICONV_EXPORT size_t	OF__iconv (iconv_t cd, char *src, size_t srcleft, char *dst, size_t dstleft, uint32_t flags, size_t *invalids)
	The OF__iconv() function works just like iconv() but if iconv() fails, the invalid character count is lost there. More...

DCMTK_OFICONV_EXPORT int	OFiconv_open_into (const char dstname, const char srcname, iconv_allocation_t *ptr)
	create a conversion descriptor on a preallocated space. More...

DCMTK_OFICONV_EXPORT int	OFiconv_close_in (iconv_allocation_t *ptr)
	close the converter cd allocated in ptr More...

DCMTK_OFICONV_EXPORT void	OFiconvlist (int(do_one)(unsigned int count, const char const names, void arg), void *arg)
	The iconvlist() function obtains a list of character encodings that are supported by the OFiconv() call. More...

DCMTK_OFICONV_EXPORT const char *	OFiconv_canonicalize (const char *name)
	resolve the character encoding name specified by the name argument to its canonical form. More...

DCMTK_OFICONV_EXPORT int	OFiconvctl (iconv_t cd, int request, void *argument)
	This function can retrieve or set specific conversion setting from the cd conversion descriptor. More...

DCMTK_OFICONV_EXPORT const char *	OFlocale_charset (iconv_locale_allocation_t *buf)
	Determine the current locale's character encoding, and canonicalize it. More...

DCMTK_OFICONV_EXPORT void	set_oficonv_logger_callback (oficonv_logger_callback_t callback)
	set the logger callback to be used by the oficonv module. More...

DCMTK_OFICONV_EXPORT oficonv_logger_callback_t	get_oficonv_logger_callback ()
	get the current logger callback used by the oficonv module More...

DCMTK_OFICONV_EXPORT void	set_oficonv_log_level (int level)
	set the log level to be used as long as direct logging to stderr is active More...

Variables
int	_iconv_version
	iconv library version constant, value defaults to _ICONV_VERSION

Detailed Description

Type definitions, constants and functions for the oficonv module.

Class Documentation

◆ iconv_allocation_t

struct iconv_allocation_t

space holder type for OFiconv_open_into().

◆ iconv_hooks

struct iconv_hooks

callback data struct for OFiconvctl() with ICONV_SET_HOOKS operation

◆ iconv_locale_allocation_t

struct iconv_locale_allocation_t

space holder type for OFlocale_charset().

Macro Definition Documentation

◆ ICONV_GET_DISCARD_ILSEQ

#define ICONV_GET_DISCARD_ILSEQ 3

OFiconvctl() request macro.

Determines if illegal sequences are discarded or not. The answer is stored in argument, which is of int *. It will be set to 1 if this feature is enabled or set to 0 otherwise.

◆ ICONV_GET_ILSEQ_INVALID

#define ICONV_GET_ILSEQ_INVALID 128

OFiconvctl() request macro.

Determines if a character in the input buffer that is valid, but for which an identical character does not exist in the target codeset returns EILSEQ or not. The answer is stored in argument, which is of int *. It will be set to 1 if this feature is enabled or set to 0 otherwise.

◆ ICONV_GET_TRANSLITERATE

#define ICONV_GET_TRANSLITERATE 1

OFiconvctl() request macro.

Determines if transliteration is enabled. The answer is stored in argument, which is of int *. It will be set to 1 if this feature is enabled or set to 0 otherwise.

◆ ICONV_SET_DISCARD_ILSEQ

#define ICONV_SET_DISCARD_ILSEQ 4

OFiconvctl() request macro.

Sets whether illegal sequences are discarded or not. argument, which is of int * set to 1 or disables it if argument is set to 0.

◆ ICONV_SET_FALLBACKS

#define ICONV_SET_FALLBACKS 6

OFiconvctl() request macro.

Currently unsupported, will always return an error

◆ ICONV_SET_HOOKS

#define ICONV_SET_HOOKS 5

OFiconvctl() request macro.

Sets callback functions, which will be called back after successful conversions. The callback functions are stored in a struct iconv_hooks variable, which is passed to iconvctl via argument by its address.

◆ ICONV_SET_ILSEQ_INVALID

#define ICONV_SET_ILSEQ_INVALID 129

OFiconvctl() request macro.

Sets whether a character in the input buffer that is valid, but for which an identical character does not exist in the target codeset returns EILSEQ or not. If argument, which is of int * is set to 1 it will be enabled, and if argument is set to 0 it will be disabled.

◆ ICONV_SET_TRANSLITERATE

#define ICONV_SET_TRANSLITERATE 2

OFiconvctl() request macro.

Enables transliteration if argument, which is of int * set to 1 or disables it if argument is set to 0.

◆ ICONV_TRIVIALP

#define ICONV_TRIVIALP 0

OFiconvctl() request macro.

The argument is an int * variable, which is set to 1 if the encoding is trivial one, i.e. the input and output encodings are the same. Otherwise, the variable will be 0.

Typedef Documentation

◆ oficonv_logger_callback_t

typedef void(* oficonv_logger_callback_t) (int level, const char *text1, const char *text2, const char *text3)

logger callback function pointer type

Parameters

level	log level, 0=trace, 1=debug, 2=info, 3=warn, 4=error, 5=fatal
text1	first part of the string to be logged, must not be NULL
text2	second part of the string to be logged, must not be NULL
text3	third part of the string to be logged, must not be NULL

Function Documentation

◆ get_oficonv_logger_callback()

DCMTK_OFICONV_EXPORT oficonv_logger_callback_t get_oficonv_logger_callback ( )

get the current logger callback used by the oficonv module

Returns: pointer to logger function, may be NULL

◆ OF__iconv()

DCMTK_OFICONV_EXPORT size_t OF__iconv	(	iconv_t	cd,
		char **	src,
		size_t *	srcleft,
		char **	dst,
		size_t *	dstleft,
		uint32_t	flags,
		size_t *	invalids
	)

The OF__iconv() function works just like iconv() but if iconv() fails, the invalid character count is lost there.

This is a not bug, rather a limitation of IEEE Std 1003.1-2008 (POSIX.1), so OF__iconv() is provided as an alternative but non-standard interface.

Parameters

cd	conversion descriptor returned by OFiconv_open()
src	address of pointer to first byte in source buffer
srcleft	address of variable containing the number of bytes left in the source buffer
src	address of pointer to first byte in destination buffer
srcleft	address of variable containing the number of bytes left in the destination buffer
flags	conversion flags. Currently only zero (default) or __ICONV_F_HIDE_INVALID can be passed. If __ICONV_F_HIDE_INVALID is passed, invalid characters are skipped instead of returning with an error.
invalids	address of variable in which the number of conversions to "invalid character" is returned upon success or failure

Returns: number of characters converted to "invalid character" upon success, or (size_t)(-1) in case of error, in which case errno is set

◆ OF__iconv_free_list()

DCMTK_OFICONV_EXPORT void OF__iconv_free_list	(	char **	names,
		size_t	count
	)

free the allocated memory during the call of OF__iconv_get_list().

Parameters

names	address of char pointer array created by OF__iconv_get_list()
count	number of entries in char pointer array

◆ OF__iconv_get_list()

DCMTK_OFICONV_EXPORT int OF__iconv_get_list	(	char ***	names,
		size_t *	count,
		__iconv_bool	paired
	)

obtain a list of character encodings that are supported by the OFiconv() call.

The list of the encoding names will be stored in names and the number of the entries is stored in count.

Parameters

names	address of char pointer array returned in this parameter
count	number of entries in char pointer array returned in this parameter
paired	if true, the list will be arranged into canonical/alias name pairs.

Returns: 0 if successful, -1 otherwise, in which case errno is set

◆ OFiconv()

DCMTK_OFICONV_EXPORT size_t OFiconv	(	iconv_t	cd,
		char **	src,
		size_t *	srcleft,
		char **	dst,
		size_t *	dstleft
	)

convert the string in the buffer *src of length *srcleft bytes and stores the converted string in the buffer *dst of size *dstleft bytes.

After calling iconv(), the values pointed to by src, srcleft, dst, and dstleft are updated as follows:

*src: Pointer to the byte just after the last character fetched.
*srcleft: Number of remaining bytes in the source buffer.
*dst: Pointer to the byte just after the last character stored.
*dstleft: Number of remainder bytes in the destination buffer.

If the string pointed to by *src contains a byte sequence which is not a valid character in the source codeset, the conversion stops just after the last successful conversion. If the output buffer is too small to store the converted character, the conversion also stops in the same way. In these cases, the values pointed to by src, srcleft, dst, and dstleft are updated to the state just after the last successful conversion.

If the string pointed to by *src contains a character which is valid under the source codeset but can not be converted to the destination codeset, the character is replaced by an "invalid character" which depends on the destination codeset, e.g., '?', and the conversion is continued. iconv() returns the number of such "invalid conversions".

Parameters

cd	conversion descriptor returned by OFiconv_open()
src	address of pointer to first byte in source buffer
srcleft	address of variable containing the number of bytes left in the source buffer
src	address of pointer to first byte in destination buffer
srcleft	address of variable containing the number of bytes left in the destination buffer

Returns: number of characters converted to "invalid character" upon success, or (size_t)(-1) in case of error, in which case errno is set

◆ OFiconv_canonicalize()

DCMTK_OFICONV_EXPORT const char * OFiconv_canonicalize ( const char * name )

resolve the character encoding name specified by the name argument to its canonical form.

Parameters

name	encoding name

Returns: canonical encoding name, NULL if unknown

◆ OFiconv_close()

DCMTK_OFICONV_EXPORT int OFiconv_close ( iconv_t cd )

close the specified converter cd

Parameters

cd	converter ID returned by OFiconv_open()

Returns: 0 if successful, -1 otherwise, in which case errno is set

◆ OFiconv_close_in()

DCMTK_OFICONV_EXPORT int OFiconv_close_in ( iconv_allocation_t * ptr )

close the converter cd allocated in ptr

Parameters

ptr	pointer to conversion descriptor created with OFiconv_open_into()

Returns: 0 if successful, -1 otherwise, in which case errno is set

◆ OFiconv_open()

BEGIN_EXTERN_C DCMTK_OFICONV_EXPORT iconv_t OFiconv_open	(	const char *	dstname,
		const char *	srcname
	)

open a converter from the codeset srcname to the codeset dstname and returns its descriptor.

The arguments srcname and dstname accept "" and "char", which refer to the current locale encoding.

Parameters

dstname	name of the destination codeset
srcname	name of the source codeset

Returns: a freshly allocated conversion descriptor. In case of error, errno is set and the function returns (iconv_t)(-1).

◆ OFiconv_open_into()

DCMTK_OFICONV_EXPORT int OFiconv_open_into	(	const char *	dstname,
		const char *	srcname,
		iconv_allocation_t *	ptr
	)

create a conversion descriptor on a preallocated space.

The iconv_allocation_t is used as a spaceholder type when allocating such space. The dstname and srcname arguments are the same as in the case of iconv_open(). The ptr argument is a pointer of iconv_allocation_t to the preallocated space.

Note: This function is a GNU libiconv extension, and should be avoided since in this implementation it may keep shared resources unnecessarily allocated since there is no way to properly close the conversion descriptor.

Parameters

dstname	name of the destination codeset
srcname	name of the source codeset
ptr	pointer to block of memory in which the conversion descriptor is allocated After successful completion of this function, ptr can be safely casted to iconv_t and used with OFiconv(). The conversion descriptor must be closed using OFiconv_close_in(), not with OFiconv_close().

Returns: 0 if successful, -1 otherwise, in which case errno is set

◆ OFiconvctl()

DCMTK_OFICONV_EXPORT int OFiconvctl	(	iconv_t	cd,
		int	request,
		void *	argument
	)

This function can retrieve or set specific conversion setting from the cd conversion descriptor.

The request parameter specifies the operation to accomplish and argument is an operation-specific argument.

Parameters

cd	conversion description
request	OFiconvctl() request macro defining the operation to be performed
argument	pointer to data for the the requested operation, see description of request macros

Returns: 0 if successful, -1 otherwise, in which case errno is set

◆ OFiconvlist()

DCMTK_OFICONV_EXPORT void OFiconvlist	(	int()(unsigned int count, const char const names, void arg)	do_one,
		void *	arg
	)

The iconvlist() function obtains a list of character encodings that are supported by the OFiconv() call.

The do_one() callback function will be called, where the count argument will be set to the number of the encoding names found, the names argument will be the list of the supported encoding names and the arg argument will be the arg argument of the iconvlist() function. This argument can be used to interchange custom data between the caller of iconvlist() and the callback function. If an error occurs, names will be NULL when calling do_one().

Parameters

do_one	callback function
arg	opaque pointer that will be passed to the callback function

◆ OFlocale_charset()

DCMTK_OFICONV_EXPORT const char * OFlocale_charset ( iconv_locale_allocation_t * buf )

Determine the current locale's character encoding, and canonicalize it.

The result must not be freed; it is statically allocated. If the canonical name cannot be determined, the result is a non-canonical name.

Parameters

buf	buffer to which the current encoding is written on Windows

Returns: current locale's character encoding (on Windows, this is the current output code page)

◆ set_oficonv_log_level()

DCMTK_OFICONV_EXPORT void set_oficonv_log_level ( int level )

set the log level to be used as long as direct logging to stderr is active

Parameters

level log level, 0=trace, 1=debug, 2=info, 3=warn, 4=error, 5=fatal (default: 3=warn)

◆ set_oficonv_logger_callback()

DCMTK_OFICONV_EXPORT void set_oficonv_logger_callback ( oficonv_logger_callback_t callback )

set the logger callback to be used by the oficonv module.

This function is thread UNSAFE.

Parameters

callback pointer to callback function, NULL for direct logging to stderr

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Class Documentation

◆ iconv_allocation_t

◆ iconv_hooks

◆ iconv_locale_allocation_t

Macro Definition Documentation

◆ ICONV_GET_DISCARD_ILSEQ

◆ ICONV_GET_ILSEQ_INVALID

◆ ICONV_GET_TRANSLITERATE

◆ ICONV_SET_DISCARD_ILSEQ

◆ ICONV_SET_FALLBACKS

◆ ICONV_SET_HOOKS

◆ ICONV_SET_ILSEQ_INVALID

◆ ICONV_SET_TRANSLITERATE

◆ ICONV_TRIVIALP

Typedef Documentation

◆ oficonv_logger_callback_t

Function Documentation

◆ get_oficonv_logger_callback()

◆ OF__iconv()

◆ OF__iconv_free_list()

◆ OF__iconv_get_list()

◆ OFiconv()

◆ OFiconv_canonicalize()

◆ OFiconv_close()

◆ OFiconv_close_in()

◆ OFiconv_open()

◆ OFiconv_open_into()

◆ OFiconvctl()

◆ OFiconvlist()

◆ OFlocale_charset()

◆ set_oficonv_log_level()

◆ set_oficonv_logger_callback()