Re: Cluepackets
"Mike Dierken" <[email protected]> Wed, 23 Jul 2003 21:32:54 -0700
| Newsgroups | gmane.comp.web.mod-pubsub.devel |
|---|---|
| Message-ID | <[email protected]> |
Why didn't they use HTTP with multipart? No difference in parsing speed than xml... User-agent replaces 'Frontend' multipart replace 'additive' content-type replaces <Clue type=...> I suppose without a cute name, existing technology doesn't stand a chance. (what was it I was doing that this reminded you of? sending soap to/from javascript? or an httpd apache server on the client that received events and exposed them via COM events?) ----- Original Message ----- From: "Adam Rifkin" <[email protected]> To: <[email protected]> Sent: Tuesday, July 22, 2003 11:51 PM Subject: Cluepackets 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 sponsored by: Free pre-built ASP.NET sites including Data Reports, E-commerce, Portals, and Forums are available now. Download today and enter to win an XBOX or Visual Studio .NET. http://aspnet.click-url.com/go/psa00100003ave/direct;at.aspnet_072303_01/01