# &kopete; torude plugina teostamise juhend

Alates &kopete; versioonist 1.0 pakub &kopete; pluginat, mis kannab nimetust Torud. See võimaldab suunata saabuvaid või väljuvaid sõnumeid välise skripti või käivitatava faili kaudu. Saabuv sõnum suunatakse käivitatavale failile, enne kui ta saabub vestlusaknasse, väljuv sõnum aga enne, kui ta saadetakse interneti kaudu teele. Torud võivad teksti saada kolmel kujul:

lihttekst

  sõnumi põhiosa puhta &ascii; tekstina

&html; tekst

  sõnumi põhiosa &html;-ina, nagu oleks sinu vestluskaaslane saatnud sulle HTML-i, mida renderdatakse vestlusaknas

&xml;-is täielik sõnum

  &xml;-dokument, mis kirjeldab kogu sõnumit, kaasa arvatud &html;-is põhiosa.

Käesolev dokument kirjeldab &xml;-vormingu spetsiifikat ning selgitab, kuidas kirjutada programm, mis suudab seda käsitseda.

## &xml;-väljund

Toome näite, mida programm saab standardse sisendvoona:

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

Selle &xml;-i aluseks on XSD, mida kasutatakse vestlusstiilide puhul ja mille leiab Kopete veebileheküljelt. Kood vastab ühele sõnumile. Siin tasub tähele panna mõnda asja:

- Atribuut "timestamp" elemendis "message" on ISO 8601 standardile vastavas vormingus.

- Atribuut "protocolIcon" elemendis "contact" valitakse järgmiselt:

  1. Kui objektile Contact on määratud foto omadus, kasutatakse seda asukohta.

  2. Kui see puudub, kasutatakse pildi asukohtana kontakti metakontakti sõltumata sellest, kas selle väärtus on null või mitte.

- Atribuudid "color" and "bgcolor" elemendis "body" on tühjad stringid, kui nad ei ole Kopetes määratud. Need on veebivärvide vormingus.

- Elemendi "body" sisu on varjestatud "<" abil, nii et seda ei aeta segi tegelikult &xml;-i struktuuriga. Loomulikult peab selleks, et sõnumi põhiosa interpreteeritaks korrektselt HTML-ina, muutma kõik "&lt;" "<".

## &xml;-sisend

Sinu programm saab &xml;-i standardse sisendvoona, tal on seda võimalik muuta ning seejärel tuleb see anda &kopete;le tagasi programmi standardse väljundvoona. Kui sinu programm muudab järgmisi elemente, muudetakse vastavalt sellele ka sõnumit &kopete;s.

- elemendi "message" atribuut "timestamp", aga mitte muud aja atribuudid

- elemendi "message" atribuut "subject"

- elemendi "message" atribuut "type"

- elemendi "message" atribuut "importance"

- elemendi "body" atribuut "color". See määratakse tavaliselt veebivärvi arvuna, kuid võib olla ka nimi. Nimesid, mida määrab SVG, tunnustab Qt4 QColor, nii et need on ka ainsad nimed, mida saab kasutada.

- elemendi "body" atribuut "bgcolor" — sama, mis atribuudi "color" korral

- elemendi "body" sisu

Kui muudad elemente või atribuute, mida pole eespool mainitud, ei võeta nende elementide muudatusi arvesse.

## Aktsepteeritavad väärtused

Mõnel atribuudil on teatud aktsepteeritavad väärtused. Torude plugina väljundil on alati legaalsed väärtused. Kui sinu programm otsustab neid atribuute muuta, peavad nad jääma legaalseks. Vastasel juhul jääb &kopete; käitumine defineerimata.

Atribuut "route" elemendis "message"

  Peab olema "inbound", "outbound" või "internal"

Atribuut "type" elemendis "message"

  Peab olema "action" või "normal"

Atribuut "importance" elemendis "message"

  Peab olema "0" väikese, "1" tavalise ja "2" suure puhul

Atribuut "dir" paljudes elementides

  Peab olema "ltr" vasakult paremale või "rtl" paremalt vasakule puhul