# Podręcznik implementacji potoków w &kopete;

Począwszy od wersji 1.0 &kopete;, &kopete; dostarczane jest z wtyczką nazywaną Potoki. Potoki pozwalają przetworzyć przychodzące lub wychodzące wiadomości przez zewnętrzny skrypt lub program. Przychodząca wiadomość będzie przetworzona przez program zanim zostanie wyświetlona w oknie rozmowy, wychodzące wiadomości będą przetworzone zanim zostaną wysłane do internetu. Potoki mogą otrzymywać tekst w jednej z trzech postaci:

Zwykły tekst

- Treść wiadomości w czystym &ascii;

&html;

- Treść wiadomości w formacie &html;, taka jak wysłana przez kontakt, z którym rozmawiasz, i jaka jest wyświetlona w oknie rozmowy

Pełna wiadomość &xml;

- Dokument &xml; opisujący wszystkie charakterystyki wiadomości, wraz z jej zawartością w formacie &html;.

Ten dokument opisuje specyfikę formatu &xml; oraz przedstawia sposoby pisania programów, które będą mogły go obsługiwać.

## Wyjście &xml;

Poniżej znajduje się przykład tekstu, który program otrzyma na swoim standardowym wejściu:

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

Ten tekst &xml; bazuje luźno na definicji XSD używanej dla stylów rozmowy, którą można znaleźć na stronie domowej Kopete. Ten kod dotyczy jednej wiadomości. Należy w nim zwrócić uwagę na kilka kwestii:

- Atrybut "timestamp" w elemencie "message" zapisywany jest w standardzie ISO 8601.

- Atrybut "protocolIcon" w elemencie "contact" zawiera następującą treść:

  1. Jeżeli kontakt posiada ustawioną fotografię, to wpisywana jest tu ścieżka do pliku.

  2. Jeżeli nie, to procedura MetaContact dla kontaktu jest poproszona o ścieżkę do pliku, która tu zostanie wpisana (niezależnie czy będzie miała wartość "null" czy też nie).

- Atrybuty "color" oraz "bgcolor" elementu "body" są pustymi napisami jeżeli nie są ustawione w Kopete. Ich wartość zapisana jest w formacie kolorów używanych w sieci WWW.

- Zawartość elementu "body" zapisuje znak "<" w postaci sekwencji specjalnej, tak aby nie został uznany za element strukturalny pliku &xml;. Żeby więc poprawnie zinterpretować zawartość jako format HTML, niezbędna będzie konwersja wszystkich "&lt;" na "<".

## Wejście &xml;

Twój program otrzyma treść &xml; na standardowe wejście, można dokonać modyfikacji tej treści, i wysłać z powrotem do &kopete; zapisując ją na standardowym wyjściu. Jeżeli twój program, dokona modyfikacji wymienionych elementów, dane zapisane w &kopete; zostaną zmodyfikowane tak aby odpowiadały twoim oczekiwaniom.

- element "message" atrybut "timestamp" ale żadne inne atrybuty związane z czasem

- "message" atrybut "subject"

- "message" atrybut "type"

- "message" atrybut "importance"

- "body" atrybut "color". Jest on zwykle numerem koloru używanym w sieci, ale może zostać podany jako nazwa. Nazwy określone w dokumentacji formatuSVG są akceptowane przez funkcję QColor biblioteki Qt 4, są więc to jedyne nazwy, których można używać.

- "body" atrybut "bgcolor" — takie samo zachowanie jak "color"

- zawartość elementu "body"

Jeżeli zmodyfikujesz elementy lub atrybuty nie opisane tutaj, twoje zmiany nie wywołają żadnego efektu.

## Dopuszczalne wartości

Niektóre atrybuty posiadają pewne dopuszczalne wartości. Wyjście wtyczki Potoki zawsze będzie zgodne z wartościami dopuszczalnymi. Jednak jeżeli twój program zmieni któreś z nich, to także muszą być zgodna z wartościami dopuszczalnymi.Jeżeli tak nie będzie, to &kopete; może zachować się w sposób nieokreślony.

Atrybut "route" w elemencie "message"

- Dopuszczalne wartości to "inbound", "outbound", lub "internal"

Atrybut "type" w elemencie "message"

- Dopuszczalne wartości to "action" lub "normal"

Atrybut "importance" w elemencie "message"

- Ważność wiadomości: "0" niska, "1" normalna, oraz "2" wysoka

Atrybut "dir" w wielu różnych elementach

- Przyjmuje wartości "ltr" dla tekstu od lewej do prawej, lub "rtl" dla tekstu od prawej do lewej