code.delx.au - pymsnt/blob - docs/developer.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
   6 <link rel="stylesheet" href="style.css" type="text/css"/>
   7 <title>PyMSNt Client Developer Guide</title>
   8 </head>
   9
  10 <body>
  11
  12 <h1>PyMSNt Client Developer Guide</h1>
  13
  14
  15 <p>Please visit <a href="http://delx.cjb.net/pymsnt">http://delx.cjb.net/pymsnt</a> to download the transport and see news updates</p>
  16 <p>If you have any insights or comments to add to this page please let me know by email or Jabber: james&#64;delx.cjb.net</p>
  17
  18 <hr/>
  19
  20
  21 <h2>Overview</h2>
  22 <p>
  23 All of this document applies to PyMSNt 0.11.
  24 </p>
  25 <p>
  26 This page documents the protocols that PyMSNt understands and uses
  27 to accomplish various tasks, such as registration sending avatars,
  28 dynamic nicknames and roster pushes.
  29 </p>
  30 <p>
  31 I don't have the time or inclination to submit all of these as JEPs.
  32 Anybody is welcome to write them up if they wish, and if a JEP comes
  33 along with equivalent functionality then I'll most likely depreciate
  34 these and implement the official standard.
  35 </p>
  36 <p>
  37 Note that with the exception of roster pushes, these protocols are not
  38 specific to gateway interaction, and SHOULD NOT be applied specially
  39 to MSN contacts.
  40 </p>
  41
  42 <hr/>
  43
  44 <h2>Required JEPs</h2>
  45 <p>
  46 To register with PyMSNt your client must support JEP-0077,
  47 (<a href="http://www.jabber.org/jeps/jep-0077.html">In-Band Registration</a>).
  48 <br/>
  49 It is also strongly recommended that you support:
  50 </p>
  51 <ul>
  52 <li>JEP-0022, (<a href="http://www.jabber.org/jeps/jep-0022.html">Message Events</a>)</li>
  53 <li>JEP-0030, (<a href="http://www.jabber.org/jeps/jep-0030.html">Service Discovery</a>)</li>
  54 <li>JEP-0045, (<a href="http://www.jabber.org/jeps/jep-0045.html">Multi-User Chat)</a>)</li>
  55 <li>JEP-0050, (<a href="http://www.jabber.org/jeps/jep-0050.html">Ad-Hoc Commands</a>)</li>
  56 <li>JEP-0054, (<a href="http://www.jabber.org/jeps/jep-0054.html">vcard-temp</a>)</li>
  57 <li>JEP-0065, (<a href="http://www.jabber.org/jeps/jep-0065.html">Socks5 Bytestreams</a>)</li>
  58 <li>JEP-0096, (<a href="http://www.jabber.org/jeps/jep-0096.html">File Transfer</a>)</li>
  59 <li>JEP-0115, (<a href="http://www.jabber.org/jeps/jep-0115.html">Entity Capabilities</a>)</li>
  60 <li>JEP-0153, (<a href="http://www.jabber.org/jeps/jep-0153.html">vCard-Based Avatars</a>)</li>
  61 </ul>
  62
  63 <hr/>
  64
  65 <h2>Basic Presence</h2>
  66 <p>
  67 You don't need to do anything special to support this section. It's just
  68 informational for those who want to know how it works.
  69 To log in, or set your status all you need to do is send a presence
  70 packet like the following:
  71 </p>
  72 <pre>
  73 &lt;presence&gt;
  74         &lt;show&gt;dnd&lt;/show&gt;
  75         &lt;status&gt;My Status Message&lt;/status&gt;
  76 &lt;/presence&gt;
  77 </pre>
  78 <p>
  79 The Jabber status message and show get mapped to the MSN7 personal message
  80 and status, respectively. The show tag is mapped to the most appropriate status
  81 code that MSN has available.
  82 </p>
  83 <p>
  84 This operates exactly in reverse. PyMSNt will send you presence packets
  85 with the same field mappings whenever MSN contacts change their status.
  86 So you'll get packets like:
  87 </p>
  88 <pre>
  89 &lt;presence from=&quot;friend%hotmail.com@msn.host.com&quot;&gt;
  90         &lt;show&gt;away&lt;/show&gt;
  91         &lt;status&gt;My Friend's Status Message&lt;/status&gt;
  92 &lt;/presence&gt;
  93 </pre>
  94
  95 <hr/>
  96
  97 <h2>Adding Contacts</h2>
  98 <p>
  99 To add a MSN contact you should follow the instructions given in
 100 section 6.3, (jabber:iq:gateway) of
 101 JEP-0100 (<a href="http://www.jabber.org/jeps/jep-0100.html#addressing-gateway">Gateway Interaction</a>).
 102 </p>
 103
 104 <hr/>
 105
 106 <h2>Typing notification</h2>
 107 <p>
 108 PyMSNt supports typing notification according to JEP-0022
 109 (<a href="http://www.jabber.org/jeps/jep-0022.html">Message Events</a>).
 110 Only the &lt;composing/&gt; tag is supported.
 111 </p>
 112
 113 <hr/>
 114
 115 <h2>Request no errors</h2>
 116 <p>
 117 You can ask PyMSNt to not send you errors in response to a &lt;message&gt;
 118 packet that you send. This should only ever be used by drone programs, clients
 119 that interact with users should always give users the error message.
 120 </p>
 121 <p>
 122 To tell PyMSNt you don't want to hear about any errors do this
 123 </p>
 124 <pre>
 125 &lt;message to=&quot;user%hotmail.com&quot;&gt;
 126         &lt;body&gt;
 127                 Hi friend! If you don't get this message then I won't be
 128                 told by my transport. It will be silently dropped.
 129         &lt;/body&gt;
 130         &lt;noerror xmlns=&quot;sapo:noerror&quot;/&gt;
 131 &lt;/message&gt;
 132 </pre>
 133
 134 <hr/>
 135
 136 <h2>Groupchat</h2>
 137 <p>
 138 PyMSNt only uses a subset of JEP-0045
 139 (<a href="http://www.jabber.org/jeps/jep-0045.html">Multi-User Chat</a>).
 140 This subset was originally known as &quot;Groupchat 1.0&quot;.
 141 If you follow the instructions given in JEP-0045 to join a room with
 142 any name not containing a % (percent) character, you will be able to
 143 invite multiple MSN users to the room and chat with them.
 144 </p>
 145
 146 <hr/>
 147
 148 <h2>Avatars</h2>
 149 <p>
 150 PyMSNt implements avatars using the vCard. See <a href="http://www.jabber.org/jeps/jep-0054.html">vcard-temp</a>.
 151 To get the vCard of a MSN contact you should do this:
 152 </p>
 153 <pre>
 154 &lt;iq type=&quot;get&quot; to=&quot;friend%hotmail.com@msn.host.com&quot; id=&quot;randomvalue&quot; &gt;
 155         &lt;vCard xmlns=&quot;vcard-temp&quot;/&gt;
 156 &lt;/iq&gt;
 157
 158 &lt;iq from=&quot;friend%hotmail.com@msn.host.com&quot; type=&quot;result&quot; id=&quot;randomvalue&quot;&gt;
 159         &lt;vCard xmlns=&quot;vcard-temp&quot;&gt;
 160                 &lt;NICKNAME&gt;Friend's nickname&lt;/NICKNAME&gt;
 161                 &lt;PHOTO&gt;
 162                         &lt;TYPE&gt;image/png&lt;/TYPE&gt;
 163                         &lt;BINVAL&gt;
 164                                 BASE64 PNG DATA GOES HERE
 165                         &lt;/BINVAL&gt;
 166                 &lt;/PHOTO&gt;
 167         &lt;/vCard&gt;
 168 &lt;/iq&gt;
 169 </pre>
 170 <p>
 171 Note the NICKNAME tag has the MSN contact's nickname in it.
 172 The BINVAL field contains the base64 image, the type is given in
 173 the TYPE field. For MSN users this type will always be &quot;image/png&quot;,
 174 but you MUST NOT assume this!
 175 </p>
 176 <p>
 177 Once again this protocol works in reverse. PyMSNt fetches your vCard once
 178 whenever a session is started. If it finds a NICKNAME tag it will set
 179 your MSN nickname to this value. If it finds a vCard then it will
 180 make that available to other MSN users.
 181 </p>
 182 <p>
 183 If you want to get avatars or nicknames to dynamically update when changed
 184 then you need to implement the next section.
 185 </p>
 186
 187 <hr/>
 188
 189 <h2>Dynamic vCard Updates</h2>
 190 <p>
 191 To signal an update of your avatar or nickname send a presence packet
 192 like below. Do this after you have updated your vCard.
 193 </p>
 194 <pre>
 195 &lt;presence&gt;
 196         &lt;show&gt;dnd&lt;/show&gt;
 197         &lt;status&gt;My Status Message&lt;/status&gt;
 198         &lt;x xmlns=&quot;vcard-temp:x:update&quot;&gt;
 199                 &lt;photo&gt;hex SHA1 hash of avatar&lt;/photo&gt;
 200                 &lt;nickname&gt;My Nickname Goes Here&lt;/nickname&gt;
 201         &lt;/x&gt;
 202 &lt;/presence&gt;
 203 </pre>
 204 <p>
 205 In the above example the nickname tag SHOULD be identical to the nickname
 206 you specify in your vCard's nickname field.
 207 </p>
 208 <p>
 209 This is because if the photo hash hasn't changed, but the nickname tag has, then PyMSNt
 210 will not fetch the vCard, it will use the value from that tag. However
 211 if the photo hash has changed, the nickname value will be taken from
 212 the vCard. Just keep these values the same and you'll never have to worry :)
 213 </p>
 214 <p>
 215 The photo tag has to have the 40 byte hex hash of the avatar you have
 216 just set in your vCard. Doing the vCard update is covered in
 217 JEP-0054, (<a href="http://www.jabber.org/jeps/jep-0054.html">vcard-temp</a>).
 218 </p>
 219 <p>
 220 Once again, this works exactly the same in reverse.
 221 PyMSNt will send you presence packets like this for all of your MSN contacts.
 222 If the photo hash changes and you haven't cached that avatar, you should
 223 retrieve retrieve it from the MSN contact's vCard.
 224 If the nickname changes, then update your on-screen display.
 225 </p>
 226 <p>
 227 Status and show fields behave exactly as described above in &quot;Basic Presence&quot;
 228 </p>
 229
 230 <hr/>
 231
 232 <h2>Roster Pushes</h2>
 233 <p>
 234 The reason for this protocol is to allow users to keep their MSN and
 235 Jabber lists synchronised. That is, any users they add in MSN, using
 236 the MSN client should be automatically added and authorised in Jabber.
 237 This is especially important for their first logon, just after registration.
 238 Otherwise they have to reauthorise all of the contacts on their MSN list.
 239 </p>
 240 <p>
 241 The way I've implemented it is this. Treat all subscription packets
 242 just like normal, unless they have a &lt;x&gt; tag qualified by the
 243 http://delx.cjb.net/protocol/roster-subsync namespace.
 244 </p>
 245 <p>
 246 For more details see <a href="http://delx.cjb.net/pymsnt/jep/roster-subsync/JEP-01XX-0.4.html">http://delx.cjb.net/pymsnt/jep/roster-subsync/JEP-01XX-0.4.html</a>
 247 </p>
 248 <p>
 249 If you receive one of these packets, then it will look like this.
 250 </p>
 251 <pre>
 252 &lt;presence from=&quot;contact%hotmail.com@msn.host.com&quot; to=&quot;user@host.com&quot; type=&quot;subscribe&quot;&gt;
 253         &lt;x xmlns=&quot;http://delx.cjb.net/protocol/roster-subsync&quot;&gt;
 254                 &lt;item name=&quot;Some contact&quot; subscription=&quot;both&quot;&gt;
 255                         &lt;group&gt;Friends&lt;/group&gt;
 256                         &lt;group&gt;Colleagues&lt;/group&gt;
 257                 &lt;/item&gt;
 258         &lt;/x&gt;
 259 &lt;/presence&gt;
 260 </pre>
 261 <p>
 262 The most import bit to look it is the subscription attribute of the item tag.
 263 This tells you what the subscription is on the legacy service, so you should
 264 send whatever packets you need to in order to make it this way.
 265 The rest of the information is there if you want to use it.
 266 </p>
 267 <p>
 268 The reason for doing things this way, is that older clients which do not
 269 support roster-subsync will still get the roster push. However he user will
 270 have to follow the right steps in order to get the contact added correctly.
 271 </p>
 272
 273 <h3>Security Concerns</h3>
 274 <p>
 275 Obviously you can't just go accepting these packets without any kind of authorisation
 276 from the user. It would be very easy for a malicious Jabber contact to construct
 277 a packet like this to get themself onto your contact list if that was the case.
 278 </p>
 279 <p>
 280 PyMSNt will not ever send any of these messages until after you have authorised
 281 the gateway itself. The process works like this.
 282 </p>
 283 <ul>
 284 <li>User registers with gateway</li>
 285 <li>Gateway requests authorisation from user</li>
 286 <li>User's client prompts them to authorise the gateway. At this point
 287 you should also check with the user if it's ok to accept any incoming
 288 roster-subsync's from this domain</li>
 289 <li>User's client authorises gateway</li>
 290 <li>Gateway sends flood of roster pushes</li>
 291 <li>User's client automatically synchronises the packets with roster-subsync
 292 tags, only notifying the user about packets that do not have this tag</li>
 293 </ul>
 294
 295 <p>
 296 If you ever receive one or more roster-subsync tag from a domain that the
 297 user has not specifically allowed or disallowed you should display exactly
 298 ONE dialog on the screen for the whole domain, asking the user if they
 299 wish to accept all of these roster pushes.
 300 </p>
 301
 302 <hr/>
 303
 304
 305
 306 <p>Bug reports and comments go to <a href="mailto:james&#64;delx.cjb.net">James Bunton</a></p>
 307 <p>I'll gladly help you with any problems, but please look through this whole page first</p>
 308
 309 <hr/>
 310 <p>Copyright James Bunton &lt;james at delx.cjb.net&gt;. You may freely redistribute this file.</p>
 311
 312
 313 </body>
 314
 315
 316 </html>