<!-- Copyright (c) 2008 by Charles Connell <charles@connells.org> -->
<!-- Licensed under the GNU Free Documentation License  -->

<appendix id="pipes">
<title>&kopete; Pipes Plugin Implementation Guide</title>
<para>
Beginning with &kopete; 1.0, &kopete; ships with a plugin called Pipes. Pipes allows you to pipe incoming or outgoing messages through an external script or executable. An incoming message will be piped through the executable before it reaches your chat window, while outgoing messages will be piped through the executable before they are sent over the internet. Pipes can receive text in one of three forms:
<variablelist>
<varlistentry>
<term>Plain text body</term>
<listitem><para>The body of the message, in plain &ascii; text</para></listitem>
</varlistentry>
<varlistentry>
<term>&html; text body</term>
<listitem><para>The body of the message, in &html;, as it would be if your chat peer had sent HTML to you, which will be rendered in the chat window</para></listitem>
</varlistentry>
<varlistentry>
<term>&xml; full message</term>
<listitem><para>An &xml; document that describes all the characteristics of the message, including the &html; body.</para></listitem>
</varlistentry>
</variablelist>
This document describes the specifics of the &xml; format, and how to write a program that can handle it.
</para>

<sect1 id="xml-output">
<title>&xml; Output</title>
<para>
Here's an example of what a program will receive in its standard input stream:
<literallayout>
&lt;?xml version="1.0" encoding="ISO-8859-1"?>
&lt;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" >
	&lt;from>
		&lt;contact contactId="tdurden"
			protocolIcon="aim_protocol"
			userPhoto="/home/kde-devel/.kde4/share/apps/kopete/oscarpictures/tdurden.jpg" >
			&lt;contactDisplayName dir="ltr" text="tdurden" />
			&lt;metaContactDisplayName dir="ltr"
				text="Tyler" />
		&lt;/contact>
	&lt;/from>
	&lt;to>
		&lt;contact contactId="spacemonkey1234"
			protocolIcon="aim_protocol"
			userPhoto="/home/kde-devel/.kde4/share/apps/kopete/avatars/User/7e542903e0ac7519a7496e85f5a5b99d.png" >
			&lt;contactDisplayName dir="ltr" text="spacemonkey1234" />
			&lt;metaContactDisplayName dir="ltr" text="Robert Paulson" />
		&lt;/contact>
		&lt;/to>
	&lt;body dir="ltr"
		bgcolor="#000000"
		color="#000000" >
		&amp;lt;span style=" color:#000000;">hey&amp;lt;/span>&lt;/body>
&lt;/message>
</literallayout>

This &xml; is loosely based on the XSD used for chatstyles found at <ulink url="http://kopete.kde.org/files/kopetemessage.xsd">the Kopete website</ulink>. This code represents one message.
There are a few things to note:
<itemizedlist>
<listitem><para>The "timestamp" attribute in the "message" element is in ISO 8601 standard format.</para></listitem>
<listitem><para>The "protocolIcon" attribute in the "contact" element is chosen like this:
<orderedlist>
<listitem><para>If the Contact object has the photo property set, that path is used.</para></listitem>
<listitem><para>If not, the Contact's MetaContact is asked for a picture path, and that is used regardless of being null or not.</para></listitem>
</orderedlist>
</para></listitem>
<listitem><para>The "color" and "bgcolor" attributes in the "body" element are empty strings if they are not set in Kopete. They are in web color format.</para></listitem>
<listitem><para>The content inside the "body" element has "&lt;" escaped, so it is not confused with the actual &xml; structure. Obviously, to correctly interpret the body as HTML, one would have to convert the "&amp;lt;"s to "&lt;"s.</para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="xml-input">
<title>&xml; Input</title>
<para>
Your program will receive &xml; in its standard input stream, it will have the opportunity to modify it, and then it must hand it back to &kopete; by way of its standard output stream. If your program modifies the following elements, the internal knowledge that &kopete; has of the message will be modified to reflect your changes.
<itemizedlist>
<listitem><para>"message" attribute "timestamp" but not other time attributes</para></listitem>
<listitem><para>"message" attribute "subject"</para></listitem>
<listitem><para>"message" attribute "type"</para></listitem>
<listitem><para>"message" attribute "importance"</para></listitem>
<listitem><para>"body" attribute "color". This is usually set to a web color number, but can be set to a name. The names defined by <ulink url="http://www.w3.org/TR/SVG/types.html#ColorKeywords">SVG</ulink> are accepted by QColor in Qt 4, so they are the only names that may be used.</para></listitem>
<listitem><para>"body" attribute "bgcolor" &mdash; same behaviour as "color"</para></listitem>
<listitem><para>content of element "body"</para></listitem>
</itemizedlist>
If you modify elements or their attributes not mentioned above, your changes to those elements will have no effect.
</para>
</sect1>

<sect1 id="acceptable-values">
<title>Acceptable Values</title>
<para>
Some attributes have certain acceptable values. The Pipes plugin's output will always have legal values. If your program chooses to change these attributes, they must remain legal. If not, &kopete;'s behavior is undefined.
<variablelist>
<varlistentry><term>Attribute "route" in element "message"</term><listitem><para>Must be "inbound", "outbound", or "internal"</para></listitem></varlistentry>
<varlistentry><term>Attribute "type" in element "message"</term><listitem><para>Must be "action" or "normal"</para></listitem></varlistentry>
<varlistentry><term>Attribute "importance" in element "message"</term><listitem><para>Must be "0" for low, "1" for normal, and "2" for high</para></listitem></varlistentry>
<varlistentry><term>Attribute "dir" in many elements</term><listitem><para>Must be "ltr" for left-to-right or "rtl" for right-to-left</para></listitem></varlistentry>
</variablelist>
</para>
</sect1>

</appendix>