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

A partir do &kopete; 1.0, o &kopete; vem com um plugin chamado Canais. Ele permite 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 você, 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;, bem como a maneira de criar um programa que possa lidar com este formato.

## Saída &xml;

Aqui está um exemplo do que um programa irá receber no seu descritor de '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="macacoespaco1234"
            time="11:06 am" >
            <from>
                    <contact contactId="marcus"
                            protocolIcon="aim_protocol"
                            userPhoto="/home/kde-devel/.kde4/share/apps/kopete/oscarpictures/marcus.jpg" >
                            <contactDisplayName dir="ltr" text="marcus" />
                            <metaContactDisplayName dir="ltr"
                                    text="Marcus" />
                    </contact>
            </from>
            <to>
                    <contact contactId="macacoespaco1234"
                            protocolIcon="aim_protocol"
                            userPhoto="/home/kde-devel/.kde4/share/apps/kopete/avatars/User/7e542903e0ac7519a7496e85f5a5b99d.png" >
                            <contactDisplayName dir="ltr" text="macacoespaco1234" />
                            <metaContactDisplayName dir="ltr" text="Roberto Pires" />
                    </contact>
                    </to>
            <body dir="ltr"
                    bgcolor="#000000"
                    color="#000000" >
                    &lt;span style=" color:#000000;"
    >olá&lt;/span
    ></body>
    </message>

Este &xml; baseia-se de certa forma no XSD usado para os estilos de conversação disponíveis na página Web do Kopete. Este código representa uma mensagem. Existem algumas notas a fazer:

- 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 objeto Contact tiver a propriedade 'photo' definida, é usado esse local.

  2. Caso contrário, é pedida ao Meta-Contato do Contato 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 atual em &xml;. Obviamente, para interpretar corretamente o conteúdo como HTML, você terá que 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 modificá-lo, passando-o finalmente de volta para o &kopete; pelo seu canal-padrão de saída ('stdout'). Se o seu programa modificar os elementos a seguir, o conhecimento interno que o &kopete; terá da mensagem será modificado para refletir 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 aceitos 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 terão efeito.

## Valores Aceitáveis

Alguns atributos possuem 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 que 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