Difference between revisions of "XML Decoders/ru"
m |
(→Получение декодера: improved translation) |
||
Line 24: | Line 24: | ||
Вот краткое описание: | Вот краткое описание: | ||
− | ==== | + | ==== Функция GetDecoder ==== |
function GetDecoder(const AEncoding: string; out Decoder: TDecoder): Boolean; stdcall; | function GetDecoder(const AEncoding: string; out Decoder: TDecoder): Boolean; stdcall; | ||
− | Во время инициализации программы декодер | + | Во время инициализации программы декодер необходимо зарегистрировать путем вызова процедуры <code>XMLRead.RegisterDecoder</code>, которой в качестве параметра передаётся функция <code>GetDecoder</code>. |
− | + | Если в процессе чтения XMLReader обнаруживает кодировку, которую он не может обработать сам, то он вызывает все зарегистрированные функции <code>GetDecoder</code> в том же порядке, в котором они были зарегистрированы, до тех пор, пока одна из них не возвратит ''True''. | |
− | Параметры функции <code>GetDecoder</code> - | + | Параметры функции <code>GetDecoder</code> - название кодировки и запись типа <code>TDecoder</code>, которую должна заполнить функция. Название кодировки содержит только символамы из множества ['A'..'Z', 'a'..'z', '0'.. '9', '.', '-,' _'], сравнивать названия кодировок следует независимо от регистра. Если декодер поддерживает данную кодировку, функция должна установить по крайней мере поле <code>Decode</code> в записи Decoder и возвратить ''True''. Установка остальных полей записи <code>Decoder</code> не является обязательной. |
==== Очистка ==== | ==== Очистка ==== |
Revision as of 15:17, 18 January 2010
│
English (en) │
español (es) │
русский (ru) │
中文(中国大陆) (zh_CN) │
XML декодеры
Дополнение к XML_Tutorial/ru.
Начиная с ревизии SVN 12582, XMLReader в состоянии обработать данные в любой кодировке при использовании внешних декодеров. Эта статья - краткое описание, как оно работает.
Доступные декодеры
В настоящее время доступен декодер, который использует libiconv. У него есть две различные реализации:
1. Модуль xmliconv.pas, который использует существующий пакет iconvenc и предназначен для операционных систем Linux, FreeBSD и Darwin.
2. Модуль xmliconv_windows.pas для Windows. Он связан с библиотекой iconv.dll, которую Вы должны распространить вместе с приложением.
Структура декодера
Интерфейс с внешними декодерами сделан в простом процедурном стиле. Для написания декодера по существу используют следующие три процедуры:
GetDecoder
Decode
Cleanup
(опционально)
Вот краткое описание:
Функция GetDecoder
function GetDecoder(const AEncoding: string; out Decoder: TDecoder): Boolean; stdcall;
Во время инициализации программы декодер необходимо зарегистрировать путем вызова процедуры XMLRead.RegisterDecoder
, которой в качестве параметра передаётся функция GetDecoder
.
Если в процессе чтения XMLReader обнаруживает кодировку, которую он не может обработать сам, то он вызывает все зарегистрированные функции GetDecoder
в том же порядке, в котором они были зарегистрированы, до тех пор, пока одна из них не возвратит True.
Параметры функции GetDecoder
- название кодировки и запись типа TDecoder
, которую должна заполнить функция. Название кодировки содержит только символамы из множества ['A'..'Z', 'a'..'z', '0'.. '9', '.', '-,' _'], сравнивать названия кодировок следует независимо от регистра. Если декодер поддерживает данную кодировку, функция должна установить по крайней мере поле Decode
в записи Decoder и возвратить True. Установка остальных полей записи Decoder
не является обязательной.
Очистка
procedure Cleanup(Context: Pointer); stdcall;
Если функция GetDecoder
установила поле Decoder.Cleanup
, то Reader вызывается один раз, после чего текущий процесс завершается. Как видно из названия, декодер должен освободить все занятые ресурсы.
Значение Decoder.Context
устанавливается для Decode
и Cleanup
процедур при каждом вызове. Reader сам не присваивает значение этому полю.
Декодирование
function Decode(Context: Pointer; InBuf: PChar; var InCnt: Cardinal; OutBuf: PWideChar; var OutCnt: Cardinal): Integer; stdcall;
Функция Decode
выполняет основную работу. Она должна преобразовать входные данные, которые содержаться в InBuf
в UTF-16 и помещает перевод в OutBuf
. Размер входного буфера указывается в
InCnt
, а размер выделенный для буфера вывода находится в OutCnt
.
Важное замечание: значение InCnt
выражено в bytes, в то время как OutCnt
- в 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.
Нельзя делать никаких предположений о начальном размере буферов: для примера, Reader может вызвать декодер только для нескольких байт во входном буфере. Функция decoder тогда должна возвратить 0, индицируя о том, что процесс не произошёл, тогда reader затребует больший размер данных и вызовет decoder снова.
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.