DCMTK: oficonv/include/dcmtk/oficonv/iconv.h File Reference

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions | Variables
iconv.h File Reference

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.
#define | ICONV_GET_TRANSLITERATE 1
| OFiconvctl() request macro.
#define | ICONV_SET_TRANSLITERATE 2
| OFiconvctl() request macro.
#define | ICONV_GET_DISCARD_ILSEQ 3
| OFiconvctl() request macro.
#define | ICONV_SET_DISCARD_ILSEQ 4
| OFiconvctl() request macro.
#define | ICONV_SET_HOOKS 5
| OFiconvctl() request macro.
#define | ICONV_SET_FALLBACKS 6
| OFiconvctl() request macro.
#define | ICONV_GET_ILSEQ_INVALID 128
| OFiconvctl() request macro.
#define | ICONV_SET_ILSEQ_INVALID 129
| OFiconvctl() request macro.

## 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

## 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.
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.
DCMTK_OFICONV_EXPORT int | OFiconv_close (iconv_t cd)
| close the specified converter cd
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.
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().
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.
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.
DCMTK_OFICONV_EXPORT int | OFiconv_close_in (iconv_allocation_t *ptr)
| close the converter cd allocated in ptr
DCMTK_OFICONV_EXPORT void | OFiconv_cleanup ()
| free static memory allocated in the oficonv module.
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.
DCMTK_OFICONV_EXPORT const char * | OFiconv_canonicalize (const char *name)
| resolve the character encoding name specified by the name argument to its canonical form.
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.
DCMTK_OFICONV_EXPORT const char * | OFlocale_charset (iconv_locale_allocation_t *buf)
| Determine the current locale's character encoding, and canonicalize it.
DCMTK_OFICONV_EXPORT void | set_oficonv_logger_callback (oficonv_logger_callback_t callback)
| set the logger callback to be used by the oficonv module.
DCMTK_OFICONV_EXPORT oficonv_logger_callback_t | get_oficonv_logger_callback ()
| get the current logger callback used by the oficonv module
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

## 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_cleanup()

DCMTK_OFICONV_EXPORT void OFiconv_cleanup | ( |  | ) |

free static memory allocated in the oficonv module.

Calling this function will delete the csmapper area object. This function may be called at application exit in order to avoid reports of memory leaks when a memory leak checker is in use.

## ◆ 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(* | 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.

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

Generated on Wed Apr 30 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2