Cluepackets
"Adam Rifkin" <[email protected]> Tue, 22 Jul 2003 23:51:00 -0700
| Newsgroups | gmane.comp.web.mod-pubsub.devel |
|---|---|
| Message-ID | <[email protected]> |
I don't know why but I can't stop thinking of Dashboard
http://www.nat.org/dashboard/
and how it could benefit from mod_pubsub. Looking at the
bits they send over the wire ("cluepackets") I'm reminded
of something Mike D was working on...
http://cvs.gnome.org/lxr/source/dashboard/doc/cluepacket.txt
1 Cluepacket Documentation
2
3 Nat Friedman <[email protected]>
4 Last updated: Fri Jul 6 01:16:18 2003
5
6 Introduction
7 ------------
8
9 This file documents the format of a cluepacket.
10
11 Before reading this file, please go through summary.txt, which
12 explains the general design of the dashboard and takes very little
13 time to read. That file is here:
14
15 http://cvs.gnome.org/lxr/source/dashboard/doc/summary.txt
16
17 A cluepacket is what a frontend application (whatever app the user is
18 interacting with at a given time) sends to the dashboard whenever the
19 user begins interacting with some kind of object (mail, web page,
20 spreadsheet), or whenever the active object changes.
21
22 Overview
23 --------
24
25 A cluepacket is a little XML block sent by a frontend application (web
26 browser, email client, editor) to the dashboard. The cluepacket is
27 sent over TCP to port 5913 on localhost. See dashboard-frontend.c
28 for some sample code that does this:
29
30 http://cvs.gnome.org/lxr/source/dashboard/frontends/dashboard-frontend.c
31
32 Form of a Cluepacket
33 --------------------
34
35 A cluepacket is made up of a set of "clues" and a small amount of
36 information about the identity and state of the application sending
37 the cluepacket.
38
39 Here is an example cluepacket:
40
41 <CluePacket>
42 <Frontend>Epiphany</Frontend>
43 <Context>Tab 1</Context>
44 <Focused>True</Focused>
45 <Additive>False</Additive>
46
47 <Clue Type="url" Relevance="10">
48 http://www.nat.org/dashboard
49 </Clue>
50
51 <Clue Type="htmlblock" Relevance="10">
52 ... full html of page ...
53 </Clue>
54 </CluePacket>
55
56 This cluepacket might be sent by the Epiphany web browser to the
57 dashboard when the user visits the dashboard blog in tab 1 of his
58 browser.
59
60 Clues
61 -----
62
63 * Definition
64
65 A clue is a single piece of information that partially describes the
66 user-interactable object in the frontend application. The dashboard
67 uses the clues to try to find objects that the user is not interacting
68 with which might be relevant to what he's doing.
69
70 * Non-additivity
71
72 Taken together, the clues in a single cluepacket should offer as
73 complete as possible a representation of all the interesting data
74 about the object being described.
75
76 That is, if you want to send clues to the dashboard about a mail the
77 user is reading, you should bundle all the relevant clues -- sender,
78 subject, to, cc, body -- into a single cluepacket. Do not send them
79 as separate cluepackets.
80
81 When the dashboard receives a new cluepacket about an object, it
82 forgets everything it knew about that object before (modulo some
83 caching for performance).
84
85 * Types
86
87 The Clue.Type property is a hint which the Dashboard's indexing and
88 querying backends can use to try to improve the quality of the matches
89 they generate. It is not necessary to specify the type for your clue,
90 but it may be helpful.
91
92 There is no limit to the number of types that you can use; you are
93 free to invent your own, but of course they will only be effective if
94 the backends recognize them. We have created a list of standard clue
95 types that frontends can apply to clues and that backends can use to
96 improve their matching. Examples include: email, url, date,
97 textblock. Please see cluetypes.txt for the canonical list:
98
99 http://cvs.gnome.org/lxr/source/dashboard/doc/cluetypes.txt
100
101 If no type is specified, the backends will treat the clue as a block
102 of text (the "textblock" clue type specifies this explicitly).
103
104 * Relevance
105
106 Frontends frequently have an idea of how relevant a clue is to the
107 object being described, and this information can help the Dashboard
108 only display the best matches.
109
110 For example, the From address on an email is usually more important
111 for generating relevant matches than an address on the Cc line.
112
113 As another example, the Gaim frontend sends the last 20 lines of an IM
114 conversation to the dashboard, but they are chunked so that as the
115 lines get older, their relevance declines.
116
117 Relevance is a number from 1 to 10. If Relevance is not specified,
118 the dashboard assumes it is 10.
119
120 Frontend Information
121 --------------------
122
123 The cluepacket contains some identifying information about the
124 frontend application that's sending it so that the dashboard can
125 distinguish between cluepacket sent from various applications.
126
127 * Frontend
128
129 The frontend tag specifies the name of the application that's sending
130 the cluepacket. This should be specific enough to be useful for
131 debugging, and also in case someone wanted to write a backend that did
132 some interesting processing of the cluepacket logs.
133
134 Here are some examples:
135
136 <Frontend>Epiphany</Frontend>
137 <Frontend>Gaim</Frontend>
138 <Frontend>Evolution Mail</Frontend>
139 <Frontend>Evolution Calendar</Frontend>
140 <Frontend>Emacs</Frontend>
141 <Frontend>Joe's Shell Script</Frontend>
142
143 You get the idea.
144
145 * Focused
146
147 The focused tag tells the dashboard whether or not the object being
148 described has focus in your windowing system. Objects that don't have
149 focus because they are obscured, iconified or not selected should set
150 Focused to false.
151
152 This is critical information for the dashboard to have so that it
153 doesn't repopulate the matchlist with matches that aren't relevant to
154 whatever the user is doing at the time.
155
156 There is also a focus-changed cluepacket that frontends can send when
157 their focus changes, even if the active object does not change. This
158 is described below; keep reading.
159
160 The Focused tag is required. If it is not found in a CluePacket, the
161 Dashboard will discard that packet.
162
163 * Context
164
165 Some frontend applications can have multiple user-interactable objects
166 displayed at one time, though the user only interacts with one at a
167 time.
168
169 Gaim is a good example of this; it is a single application which can
170 have multiple IM conversation windows up at once. Cluepackets
171 relevant to one conversation are probably not relevant to another
172 conversation. There are other examples too: your web browser can have
173 tabs, your mailer can have separate windows, etc.
174
175 Context is an opaque string which you use to represent the user's
176 current interaction context. Here's an example:
177
178 <CluePacket>
179 <Frontend>Gaim</Frontend>
180 <Context>Conversation with SeanEgn</Context>
181 <Focused>True</Focused>
182
183 <Clue Type="aim" Relevance="10">SeanEgn</Clue>
184
185 <Clue Type="textblock" Relevance="8">
186 Hey Sean, how's it going?
187 Not bad, busy with school.
188 </Clue>
189
190 <Clue Type="textblock" Relevance="10">
191 School - fun. Hey can you give me a hand with this
192 plugin I'm writing?
193 </Clue>
194
195 </CluePacket>
196
197 This is a pretty good example because the specified Context is also
198 descriptive. Now, if the user were to click on another IM window --
199 say, "Conversation with NatFriedman" -- then the dashboard would know
200 that the newly active frontend context has nothing to do with the
201 cluepacket above.
202
203 The Context doesn't have to be descriptive, it just has to be unique
204 between user Contexts. An example of an opaque context might be:
205
206 <CluePacket>
207 <Frontend>Emacs</Frontend>
208 <Context>WINDOWID-0x2c000d8</Context>
209 <Focused>TRUE</Focused>
210
211 ... CLUES GO HERE ...
212
213 </CluePacket>
214
215 You can put whatever you want in Context as long as it uniquely
216 identifies the context. The Context tag is optional but highly
217 preferred. If the Context tag is omitted, the Dashboard will assume a
218 global context within that Frontend.
219
220 * Additive
221
222 Normally a new CluePacket signifies a context switch of sorts, usually
223 resulting from a change in focus of a frontend. Under certain
224 circumstances, though, you want a new incoming CluePacket to augment
225 the currently displayed matches of the most recent CluePacket. For
226 those, you want to set the Additive tag.
227
228 A good example of this is the accessibility frontend, which creates
229 CluePackets containing text that you've recently typed. You obviously
230 don't want your existing matches to be removed as you type, but you do
231 want to see additional matches related to what you're typing at the time.
232
233 Focus-In Cluepackets
234 --------------------
235
236 The dashboard needs to know when an interaction context with an
237 interesting object gains focus, so that it can display matches
238 relevant to the new object, instead of leaving stale matches around.
239
240 So, basically, when your window gets focus, you can send a cluepacket
241 to the dashboard that just contains:
242
243 <CluePacket>
244 <Frontend>Epiphany</Frontend>
245 <Context>Tab 1</Context>
246 <Focused>True</Focused>
247 </CluePacket>
248
249 The dashboard will remember the clues that you gave it before, while
250 the window was unfocused, so you don't need to resend them. This can
251 make implementing frontends easier.
252
253 Of course, you don't have to send focus-only cluepackets; you can
254 build a full cluepacket and send it to the dashboard whenever you get
255 focus, too. There's no need to send a focus-out cluepacket.
256
257 Syntax
258 ------
259
260 The dashboard performs some basic XML validation on the cluepacket
261 before processing it. If validator fails, the cluepacket is thrown
262 away.
263
264 You should make sure your frontend does the following things:
265
266 - All attributes should be quoted. So this is legal:
267
268 <Clue Type=\"aim_name\" Relevance=\"10\">natfriedman</Clue>
269
270 and this is not:
271
272 <Clue Type=\"aim_name\" Relevance=10>natfriedman</Clue>
273
274 - Tags and attributes must be capitalized. Not only does this
275 look really cool, it seems to help Mono's XML Serializer.
276
277 - All node content must be escaped.
278
279 If you use one of the frontend libraries or modules, none of this
280 should be a problem for you.
281
282 Please see the DTD for a more rigorous syntax definition:
283
284 http://cvs.gnome.org/lxr/source/dashboard/doc/cluepacket.dtd
285
286 Implementation
287 --------------
288
289 Cluepackets are designed to be easy to build and send. To make it
290 even easier, the dashboard ships with helper code, libaries and
291 modules that help you construct and send cluepackets. You can also
292 use some of the existing frontend code as examples.
293
294 Check out the frontends/ directory for more information:
295
296 http://cvs.gnome.org/lxr/source/dashboard/frontends/
297
298 If you're writing in C, I recommend reading the Evolution mail patch
299 for a particularly gorgeous example ;-).
300
-------------------------------------------------------
This SF.net email is sponsored by: VM Ware
With VMware you can run multiple operating systems on a single machine.
WITHOUT REBOOTING! Mix Linux / Windows / Novell virtual machines at the
same time. Free trial click here: http://www.vmware.com/wl/offer/345/0