Appendix C. Kopete Pipes Plugin Implementation Guide

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:

Plain text body

The body of the message, in plain ASCII text

HTML text body

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

XML full message

An XML document that describes all the characteristics of the message, including the HTML body.

This document describes the specifics of the XML format, and how to write a program that can handle it.

XML Output

Here's an example of what a program will receive in its standard input stream:


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

This XML is loosely based on the XSD used for chatstyles found at the Kopete website. This code represents one message. There are a few things to note:

  • The "timestamp" attribute in the "message" element is in ISO 8601 standard format.

  • The "protocolIcon" attribute in the "contact" element is chosen like this:

    1. If the Contact object has the photo property set, that path is used.

    2. If not, the Contact's MetaContact is asked for a picture path, and that is used regardless of being null or not.

  • 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.

  • The content inside the "body" element has "<" 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 "&lt;"s to "<"s.