Difference between revisions of "XML Decoders/ru"
Line 4: | Line 4: | ||
=== Доступные декодеры === | === Доступные декодеры === | ||
− | |||
− | |||
В настоящее время доступен декодер, который использует libiconv. У него есть две различные реализации: | В настоящее время доступен декодер, который использует libiconv. У него есть две различные реализации: |
Revision as of 10:13, 17 January 2010
XML декодеры
Начиная с ревизии SVN 12582, XMLReader в состоянии обработать данные в любой кодировке при использовании внешних декодеров. Эта статья - краткое описание, как оно работает.
Доступные декодеры
В настоящее время доступен декодер, который использует libiconv. У него есть две различные реализации:
1. Модуль xmliconv.pas, который использует существующий пакет iconvenc и предназначен для операционных систем Linux, FreeBSD и Darwin.
2. Модуль xmliconv_windows.pas для Windows. Он связан с библиотекой iconv.dll, которую Вы должны распространить вместе с приложением.
Структура декодера
Interfacing with the external decoders is done in a plain procedural style. Writing the decoder is essentially implementing the following three procedures:
GetDecoder
Decode
Cleanup
(optional)
Here is the brief desription of external decoder operation:
Получение декодера
function GetDecoder(const AEncoding: string; out Decoder: TDecoder): Boolean; stdcall;
At the program initialization time, decoder registers itself by calling XMLRead.RegisterDecoder
procedure, supplying its GetDecoder
function as the argument.
Whenever the reader encounters the encoding label which it does not handle internally, it calls all registered GetDecoder
functions in the same order they were registered, until one of them returns True.
The GetDecoder
function arguments are the name of encoding and the TDecoder
record that the function should fill. The encoding name is restricted to characters in range ['A'..'Z', 'a'..'z', '0'..'9', '.', '-', '_'], and must be compared case-insensitive. If the decoder supports given encoding, the function should set at least the Decode
member of the supplied record and return True. Setting other members of Decoder
is optional.
Очистка
procedure Cleanup(Context: Pointer); stdcall;
If GetDecoder
sets the Decoder.Cleanup
member, it is called by reader once, after processing of the current entity is finished. As the name suggests, the decoder should then free all resources it allocated.
The value of Decoder.Context
is passed to Decode
and Cleanup
procedures each time they are called. The reader does not assign any meaning to this value.
Декодирование
function Decode(Context: Pointer; InBuf: PChar; var InCnt: Cardinal; OutBuf: PWideChar; var OutCnt: Cardinal): Integer; stdcall;
The Decode
function does the main job. It should convert the input data pointed by InBuf
into UTF-16 in the current platform endianness and place it into OutBuf
. The size of input buffer is supplied in
InCnt
, the space avaliable in output buffer is in OutCnt
.
The important difference to note is that InCnt
is given in bytes, while OutCnt
is in WideChars.
The function must decrement InCnt
and OutCnt
according to the amount of data it processes. Each processed character decrements OutCnt
by one (or by two in case the surrogate pair is written); the amount of InCnt
decrement depends on the actual encoding.
No assumptions should be made about initial size of buffers: for example, the reader may call decoder with only a few bytes in input buffer. The decoder function then should return zero indicating nothing is processed, and the reader will fetch more input and call decoder again.
The function should return positive value if it had processed something, zero if it had not (e.g. because no space available in either input or output buffer), and negative value in cause the input data contains illegal sequence. In the future, there may be attempt to categorize the decoding errors, but currently any negative return simply aborts the reader with the 'Decoding error' message.
In case of error in input data the decoder should still decrement OutCnt
to reflect the number of successfully processed characters. This will be used by reader to provide location information in the exception error message.