# Guia de Implementação de 'Plugins' de Canais do &kopete;

Desde o &kopete; 1.0, o &kopete; vem com um 'plugin' chamado Canais. Este permite-lhe encaminhar as mensagens recebidas ou enviadas por um programa externo. Uma mensagem recebida será encaminhada pelo executável antes de atingir a sua janela de conversação, enquanto as mensagens enviadas serão encaminhadas pelo executável antes de serem enviadas para a Internet. Os canais poderão receber o texto num de três formatos:

Corpo em texto simples

  O corpo da mensagem, em texto &ascii; simples

Corpo de texto em &html;

  O corpo da mensagem, em &html;, como apareceria se o seu parceiro tivesse enviado HTML para si, o qual será apresentado na janela de conversação

Mensagem completa em &xml;

  Um documento em &xml; que descreve todas as características da mensagem, incluindo o corpo em &html;.

. Este documento descreve os detalhes específicos do formato &xml;, assim como criar um programa que possa lidar com este.

## Resultado em &xml;

Aqui está um exemplo do que um programa irá receber no seu canal de entrada padrão ('stdin'):

    <?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="macacoEspacial1234"
            time="11:06 am" >
            <from>
                    <contact contactId="to"
                            protocolIcon="aim_protocol"
                            userPhoto="/home/kde-devel/.kde4/share/apps/kopete/oscarpictures/tdurden.jpg" >
                            <contactDisplayName dir="ltr" text="to" />
                            <metaContactDisplayName dir="ltr"
                                    text="Tó" />
                    </contact>
            </from>
            <to>
                    <contact contactId="macacoEspacial1234"
                            protocolIcon="aim_protocol"
                            userPhoto="/home/kde-devel/.kde4/share/apps/kopete/avatars/User/7e542903e0ac7519a7496e85f5a5b99d.png" >
                            <contactDisplayName dir="ltr" text="macacoEspacial1234" />
                            <metaContactDisplayName dir="ltr" text="Macaco do Espaço" />
                    </contact>
                    </to>
            <body dir="ltr"
                    bgcolor="#000000"
                    color="#000000" >
                    &lt;span style=" color:#000000;"
    >oi&lt;/span
    ></body>
    </message>

Este &xml; baseia-se de certa forma no XSD que é usado para os estilos de conversação, que se encontra na página Web do Kopete. Este código representa uma mensagem. Existem algumas coisas a notar:

- O atributo "timestamp" do elemento "message" está no formato-padrão ISO 8601.

- O atributo "protocolIcon" do elemento "contact" é escolhido da seguinte forma:

  1. Se o objecto Contact tiver a propriedade 'photo' definida, é usado esse local.

  2. Caso contrário, é pedida ao Meta-Contacto do Contacto a localização de uma imagem, sendo esta usada se for nula ou não.

- Os atributos "color" e "bgcolor" do elemento "body" são cadeias de caracteres vazias se não estiverem definidas no Kopete. Estão no formato de cores da Web.

- O conteúdo dentro do elemento "body" tem o "<" escapado, para que não seja confundido com a estrutura actual em &xml;. Obviamente, para interpretar correctamente o conteúdo como HTML, terá de converter os "&lt;"s para "<"s.

## Dados de Entrada em &xml;

O seu programa irá receber o &xml; no seu canal-padrão de entrada ('stdin'), tendo a oportunidade para o modificar, passando-o finalmente de volta para o &kopete; pelo seu canal-padrão de saída ('stdout'). Se o seu programa modificar os elementos seguintes, o conhecimento interno que o &kopete; terá da mensagem será modificado para reflectir as suas alterações.

- o atributo "timestamp" de "message", mas sem outros atributos de tempo

- o atributo "subject" de "message"

- o atributo "type" de "message"

- o atributo "importance" de "message"

- o atributo "color" do "body". Normalmente está definido como um número de cor da Web, mas poderá ser definido com um nome. Os nomes definidos pelo SVG são aceites pelo QColor no Qt 4, por isso são os únicos nomes que poderão ser usados.

- o atributo "bgcolor" do "body" — o mesmo comportamento que o "color"

- o conteúdo do elemento "body"

Se modificar elementos ou os seus atributos que não estiverem mencionados acima, as suas alterações a esses elementos não farão efeito.

## Valores Aceitáveis

Alguns atributos têm determinados valores aceitáveis. O resultado do 'plugin' de Canais terão sempre valores válidos. Se o seu programa optar por alterar estes atributos, os mesmos terão de permanecer válidos. Caso contrário, o comportamento do &kopete; é indefinido.

Atributo "route" no elemento "message"

  Deverá ser "inbound", "outbound", ou "internal"

Atributo "type" no elemento "message"

  Deverá ser igual a "action" ou "normal"

Atributo "importance" no elemento "message"

  Deverá ser "0" para baixa, "1" para normal e "2" para alta

Atributo "dir" em vários elementos

  Deverá ser "ltr" para esquerda-para-direita ou "rtl" para direita-para-esquerda