# Довідник з розробки для додатка каналів &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» (для лівописних систем запису)