Please visit http://msn-transport.jabberstudio.org to download the transport and see news updates
+If you have any insights or comments to add to this page please let me know by email or Jabber: james@delx.cjb.net
+ ++All of this document applies to PyMSNt 0.11. +
++This page documents the protocols that PyMSNt understands and uses +to accomplish various tasks, such as registration sending avatars, +dynamic nicknames and roster pushes. +
++I don't have the time or inclination to submit all of these as JEPs. +Anybody is welcome to write them up if they wish, and if a JEP comes +along with equivalent functionality then I'll most likely depreciate +these and implement the official standard. +
++Note that with the exception of roster pushes, these protocols are not +specific to gateway interaction, and SHOULD NOT be applied specially +to MSN contacts. +
+ +
+To register with PyMSNt your client must support JEP-0077,
+(In-Band Registration).
+
+It is also strongly recommended that you support:
+
+You don't need to do anything special to support this section. It's just +informational for those who want to know how it works. +To log in, or set your status all you need to do is send a presence +packet like the following: +
++<presence> + <show>dnd</show> + <status>My Status Message</status> +</presence> ++
+The Jabber status message and show get mapped to the MSN7 personal message +and status, respectively. The show tag is mapped to the most appropriate status +code that MSN has available. +
++This operates exactly in reverse. PyMSNt will send you presence packets +with the same field mappings whenever MSN contacts change their status. +So you'll get packets like: +
++<presence from="friend%hotmail.com@msn.host.com"> + <show>away</show> + <status>My Friend's Status Message</status> +</presence> ++ +
+To add a MSN contact you should follow the instructions given in +section 6.3, (jabber:iq:gateway) of +JEP-0100 (Gateway Interaction). +
+ ++PyMSNt supports typing notification according to JEP-0022 +(Message Events). +Only the <composing/> tag is supported. +
+ ++You can ask PyMSNt to not send you errors in response to a <message> +packet that you send. This should only ever be used by drone programs, clients +that interact with users should always give users the error message. +
++To tell PyMSNt you don't want to hear about any errors do this +
++<message to="user%hotmail.com"> + <body> + Hi friend! If you don't get this message then I won't be + told by my transport. It will be silently dropped. + </body> + <noerror xmlns="sapo:noerror"/> +</message> ++ +
+PyMSNt only uses a subset of JEP-0045 +(Multi-User Chat). +This subset was originally known as "Groupchat 1.0". +If you follow the instructions given in JEP-0045 to join a room with +any name not containing a % (percent) character, you will be able to +invite multiple MSN users to the room and chat with them. +
+ ++PyMSNt implements avatars using the vCard. See vcard-temp. +To get the vCard of a MSN contact you should do this: +
++<iq type="get" to="friend%hotmail.com@msn.host.com" id="randomvalue" > + <vCard xmlns="vcard-temp"/> +</iq> + +<iq from="friend%hotmail.com@msn.host.com" type="result" id="randomvalue"> + <vCard xmlns="vcard-temp"> + <NICKNAME>Friend's nickname</NICKNAME> + <PHOTO> + <TYPE>image/png</TYPE> + <BINVAL> + BASE64 PNG DATA GOES HERE + </BINVAL> + </PHOTO> + </vCard> +</iq> ++
+Note the NICKNAME tag has the MSN contact's nickname in it. +The BINVAL field contains the base64 image, the type is given in +the TYPE field. For MSN users this type will always be "image/png", +but you MUST NOT assume this! +
++Once again this protocol works in reverse. PyMSNt fetches your vCard once +whenever a session is started. If it finds a NICKNAME tag it will set +your MSN nickname to this value. If it finds a vCard then it will +make that available to other MSN users. +
++If you want to get avatars or nicknames to dynamically update when changed +then you need to implement the next section. +
+ ++To signal an update of your avatar or nickname send a presence packet +like below. Do this after you have updated your vCard. +
++<presence> + <show>dnd</show> + <status>My Status Message</status> + <x xmlns="vcard-temp:x:update"> + <photo>hex SHA1 hash of avatar</photo> + <nickname>My Nickname Goes Here</nickname> + </x> +</presence> ++
+In the above example the nickname tag SHOULD be identical to the nickname +you specify in your vCard's nickname field. +
++This is because if the photo hash hasn't changed, but the nickname tag has, then PyMSNt +will not fetch the vCard, it will use the value from that tag. However +if the photo hash has changed, the nickname value will be taken from +the vCard. Just keep these values the same and you'll never have to worry :) +
++The photo tag has to have the 40 byte hex hash of the avatar you have +just set in your vCard. Doing the vCard update is covered in +JEP-0054, (vcard-temp). +
++Once again, this works exactly the same in reverse. +PyMSNt will send you presence packets like this for all of your MSN contacts. +If the photo hash changes and you haven't cached that avatar, you should +retrieve retrieve it from the MSN contact's vCard. +If the nickname changes, then update your on-screen display. +
++Status and show fields behave exactly as described above in "Basic Presence" +
+ ++The reason for this protocol is to allow users to keep their MSN and +Jabber lists synchronised. That is, any users they add in MSN, using +the MSN client should be automatically added and authorised in Jabber. +This is especially important for their first logon, just after registration. +Otherwise they have to reauthorise all of the contacts on their MSN list. +
++The way I've implemented it is this. Treat all subscription packets +just like normal, unless they have a <x> tag qualified by the +http://delx.cjb.net/protocol/roster-subsync namespace. +
++For more details see http://msn-transport.jabberstudio.org/jep/roster-subsync/JEP-01XX-0.4.html +
++If you receive one of these packets, then it will look like this. +
++<presence from="contact%hotmail.com@msn.host.com" to="user@host.com" type="subscribe"> + <x xmlns="http://delx.cjb.net/protocol/roster-subsync"> + <item name="Some contact" subscription="both"> + <group>Friends</group> + <group>Colleagues</group> + </item> + </x> +</presence> ++
+The most import bit to look it is the subscription attribute of the item tag. +This tells you what the subscription is on the legacy service, so you should +send whatever packets you need to in order to make it this way. +The rest of the information is there if you want to use it. +
++The reason for doing things this way, is that older clients which do not +support roster-subsync will still get the roster push. However he user will +have to follow the right steps in order to get the contact added correctly. +
+ ++Obviously you can't just go accepting these packets without any kind of authorisation +from the user. It would be very easy for a malicious Jabber contact to construct +a packet like this to get themself onto your contact list if that was the case. +
++PyMSNt will not ever send any of these messages until after you have authorised +the gateway itself. The process works like this. +
++If you ever receive one or more roster-subsync tag from a domain that the +user has not specifically allowed or disallowed you should display exactly +ONE dialog on the screen for the whole domain, asking the user if they +wish to accept all of these roster pushes. +
+ +Bug reports and comments go to James Bunton
+I'll gladly help you with any problems, but please look through this whole page first
+ + + + + +