# Довідник з розробки для додатка каналів &kopete;

Починаючи з версії &kopete; 1.0, &kopete; постачається з додатком під назвою «Канал». Канали надають вам змогу пропускати ваші вхідні і вихідні повідомлення через зовнішній скрипт або виконуваний файл. Вхідне повідомлення буде пропущено через виконуваний файл до того, як потрапити до вікна спілкування, а вихідне повідомлення — до надсилання цього повідомлення мережею Інтернет. Канали можуть отримувати текст у одній з трьох форм:

Звичайний текст

- Текст повідомлення у вигляді тексту &ascii;

Текст повідомлення у &HTML;

- Текст повідомлення як код &HTML; у тому вигляді, як його було надіслано як HTML вашим співрозмовником, і у якому його буде показано у вікні спілкування

Повідомлення у вигляді повноцінного &XML;

- Документ &XML;, у якому описано всі характеристики повідомлення, зокрема код &HTML;.

У цьому документі описано специфічні особливості формату &XML; та подано настанови щодо написання програм для його обробки.

## Вихідний &XML;

Ось приклад того, що програма отримає у стандартному вхідному потоці:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <message subject=""
            route="outbound"
            importance="1"
            formattedTimestamp="11:06:46 am"
            timestamp="Sat Dec 1 11:06:46 2007"
            type="normal"
            mainContactId="spacemonkey1234"
            time="11:06 am" >
            <from>
                    <contact contactId="tdurden"
                            protocolIcon="aim_protocol"
                            userPhoto="/home/kde-devel/.kde4/share/apps/kopete/oscarpictures/tdurden.jpg" >
                            <contactDisplayName dir="ltr" text="tdurden" />
                            <metaContactDisplayName dir="ltr"
                                    text="Tyler" />
                    </contact>
            </from>
            <to>
                    <contact contactId="spacemonkey1234"
                            protocolIcon="aim_protocol"
                            userPhoto="/home/kde-devel/.kde4/share/apps/kopete/avatars/User/7e542903e0ac7519a7496e85f5a5b99d.png" >
                            <contactDisplayName dir="ltr" text="spacemonkey1234" />
                            <metaContactDisplayName dir="ltr" text="Robert Paulson" />
                    </contact>
                    </to>
            <body dir="ltr"
                    bgcolor="#000000"
                    color="#000000" >
                    &lt;span style=" color:#000000;"
    >hey&lt;/span
    ></body>
    </message>

Цей код &XML; у загальних рисах засновано на XSD, що використовується у стилях спілкування і знаходиться на сайті Kopete. У коді подано одне повідомлення. Існує декілька речей, які слід зауважити:

- Атрибут «timestamp» у елементі «message» подано у стандартному форматі ISO 8601.

- Атрибут «protocolIcon» у елементі «contact» буде вибрано у такий спосіб:

  1. Якщо об’єкт контакту має встановлену властивість «фотографія», буде використано шлях до фотографії.

  2. Якщо такої властивості не встановлено, буде проведено пошук зображення у метаконтакті контакту. Результат буде використано незалежно від того, чи буде він нульовим, чи ні.

- Атрибути «color» і «bgcolor» у елементі «body» є порожніми рядками, якщо їх не встановлено у Kopete. Ці атрибути буде подано у форматі вебкольорів.

- Вміст елемента «body» слід екранувати символом «<», щоб його не можна було сплутати з справжньою структурою &XML;. Очевидно, щоб правильно розпізнати текст повідомлення як HTML, слід перетворити всі «amp;lt;» на «<».

## Вхідний &XML;

Ваша програма отримуватиме &XML; у потоці вхідної інформації, зможе змінити цю інформацію, а потім передати змінену інформацію до &kopete; за посередництва стандартного вихідного потоку інформації. Якщо ваша програма змінить перелічені нижче елементи, внутрішні дані, які отримає &kopete; щодо зміненого повідомлення, відображатимуть внесені вами зміни.

- атрибут «timestamp» елемента «message», але не інші часові атрибути

- атрибут «subject» елемента «message»

- атрибут «type» елемента «message»

- атрибут «importance» елемента «message»

- атрибут «color» елемента «body». Зазвичай значенням такого атрибута є вебномер кольору, але можна встановити і назву кольору. Назви кольорів, які визначаються у стандарті SVG, є прийнятними для параметра QColor у Qt 4, отже, можна використовувати лише ці назви.

- атрибут «color» елемента «bgbody», — ті самі зауваження, що і для «color»

- вміст елемента "body"

Якщо ви зміните елементи або їх атрибути, які не було згадано вище за текстом, ці зміни не вплинуть на показ повідомлень.

## Прийнятні значення

Деякі з атрибутів мають обмежену множину прийнятних значень. У вихідному потоці додатка «Канали» завжди будуть коректні значення. Якщо ваша програма намагатиметься змінити ці атрибути, їх значення має залишатися коректним. Якщо цю вимогу не буде виконано, поведінка &kopete; може бути непередбачуваною.

Атрибут «route» елемента «message»

- Повинен мати значення «inbound», «outbound» або «internal»

Атрибут «type» елемента «message»

- Повинен мати значення «action» або «normal»

Атрибут «importance» елемента «message»

- Повинен мати значення «0» (низька важливість), «1» (звичайна важливість) або «2» (підвищена важливість)

Атрибут «dir» у багатьох елементах

- Повинен мати значення «ltr» (для правописних систем запису) або «rtl» (для лівописних систем запису)