<!-- Copyright (c) 2008 by Charles Connell <charles@connells.org > --> <!-- Licensed under the GNU Free Documentation License --> <appendix id="pipes"> <title >Guia de Implementação de 'Plugins' de Canais do &kopete;</title> <para >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: <variablelist > <varlistentry > <term >Corpo em texto simples</term > <listitem ><para >O corpo da mensagem, em texto &ascii; simples</para ></listitem > </varlistentry > <varlistentry > <term >Corpo de texto em &html;</term > <listitem ><para >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</para ></listitem > </varlistentry > <varlistentry > <term >Mensagem completa em &xml;</term > <listitem ><para >Um documento em &xml; que descreve todas as características da mensagem, incluindo o corpo em &html;.</para ></listitem > </varlistentry > </variablelist >. Este documento descreve os detalhes específicos do formato &xml;, assim como criar um programa que possa lidar com este. </para> <sect1 id="xml-output"> <title >Resultado em &xml;</title> <para >Aqui está um exemplo do que um programa irá receber no seu descritor de 'stdin': <literallayout> <?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="tiago" protocolIcon="aim_protocol" userPhoto="/home/kde-devel/.kde4/share/apps/kopete/oscarpictures/tiago.jpg" > <contactDisplayName dir="ltr" text="tiago" /> <metaContactDisplayName dir="ltr" text="Tiago" /> </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> </literallayout > Este &xml; baseia-se de certa forma no XSD usado para os estilos de conversação disponíveis na <ulink url="http://kopete.kde.org/files/kopetemessage.xsd" >página Web do Kopete</ulink >. Este código representa uma mensagem. Existem algumas notas a fazer: <itemizedlist> <listitem ><para >O atributo "timestamp" do elemento "message" está no formato-padrão ISO 8601.</para ></listitem> <listitem ><para >O atributo "protocolIcon" do elemento "contact" é escolhido da seguinte forma: <orderedlist> <listitem ><para >Se o objecto Contact tiver a propriedade 'photo' definida, é usado esse local.</para ></listitem> <listitem ><para >Caso contrário, é pedida ao Meta-Contacto do Contacto a localização de uma imagem, sendo esta usada se for nula ou não.</para ></listitem> </orderedlist> </para ></listitem> <listitem ><para >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.</para ></listitem> <listitem ><para >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.</para ></listitem> </itemizedlist> </para> </sect1> <sect1 id="xml-input"> <title >Dados de Entrada em &xml;</title> <para >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. <itemizedlist > <listitem ><para >o atributo "timestamp" de "message", mas sem outros atributos de tempo</para ></listitem > <listitem ><para >o atributo "subject" de "message"</para ></listitem > <listitem ><para >o atributo "type" de "message"</para ></listitem > <listitem ><para >o atributo "importance" de "message"</para ></listitem > <listitem ><para >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 <ulink url="http://www.w3.org/TR/SVG/types.html#ColorKeywords" >SVG</ulink > são aceites pelo QColor no Qt 4, por isso são os únicos nomes que poderão ser usados.</para ></listitem > <listitem ><para >o atributo "bgcolor" do "body" — o mesmo comportamento que o "color"</para ></listitem > <listitem ><para >o conteúdo do elemento "body"</para ></listitem > </itemizedlist > 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. </para> </sect1> <sect1 id="acceptable-values"> <title >Valores Aceitáveis</title> <para >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. <variablelist> <varlistentry ><term >Atributo "route" no elemento "message"</term ><listitem ><para >Deverá ser "inbound", "outbound", ou "internal"</para ></listitem ></varlistentry> <varlistentry ><term >Atributo "type" no elemento "message"</term ><listitem ><para >Deverá ser igual a "action" ou "normal"</para ></listitem ></varlistentry> <varlistentry ><term >Atributo "importance" no elemento "message"</term ><listitem ><para >Deverá ser "0" para baixa, "1" para normal e "2" para alta</para ></listitem ></varlistentry> <varlistentry ><term >Atributo "dir" em vários elementos</term ><listitem ><para >Deverá ser "ltr" para esquerda-para-direita ou "rtl" para direita-para-esquerda</para ></listitem ></varlistentry> </variablelist> </para> </sect1> </appendix>