--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+<link rel="stylesheet" href="style.css" type="text/css"/>
+<title>PyMSNt Client Developer Guide</title>
+</head>
+
+<body>
+
+<h1>PyMSNt Client Developer Guide</h1>
+
+
+<p>Please visit <a href="http://msn-transport.jabberstudio.org">http://msn-transport.jabberstudio.org</a> to download the transport and see news updates</p>
+<p>If you have any insights or comments to add to this page please let me know by email or Jabber: james@delx.cjb.net</p>
+
+<hr/>
+
+
+<h2>Overview</h2>
+<p>
+All of this document applies to PyMSNt 0.11.
+</p>
+<p>
+This page documents the protocols that PyMSNt understands and uses
+to accomplish various tasks, such as registration sending avatars,
+dynamic nicknames and roster pushes.
+</p>
+<p>
+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.
+</p>
+<p>
+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.
+</p>
+
+<hr/>
+
+<h2>Required JEPs</h2>
+<p>
+To register with PyMSNt your client must support JEP-0077,
+(<a href="http://www.jabber.org/jeps/jep-0077.html">In-Band Registration</a>).
+<br/>
+It is also strongly recommended that you support:
+</p>
+<ul>
+<li>JEP-0022, (<a href="http://www.jabber.org/jeps/jep-0022.html">Message Events</a>)</li>
+<li>JEP-0030, (<a href="http://www.jabber.org/jeps/jep-0030.html">Service Discovery</a>)</li>
+<li>JEP-0045, (<a href="http://www.jabber.org/jeps/jep-0045.html">Multi-User Chat)</a>)</li>
+<li>JEP-0050, (<a href="http://www.jabber.org/jeps/jep-0050.html">Ad-Hoc Commands</a>)</li>
+<li>JEP-0054, (<a href="http://www.jabber.org/jeps/jep-0054.html">vcard-temp</a>)</li>
+<li>JEP-0065, (<a href="http://www.jabber.org/jeps/jep-0065.html">Socks5 Bytestreams</a>)</li>
+<li>JEP-0096, (<a href="http://www.jabber.org/jeps/jep-0096.html">File Transfer</a>)</li>
+<li>JEP-0115, (<a href="http://www.jabber.org/jeps/jep-0115.html">Entity Capabilities</a>)</li>
+<li>JEP-0153, (<a href="http://www.jabber.org/jeps/jep-0153.html">vCard-Based Avatars</a>)</li>
+</ul>
+
+<hr/>
+
+<h2>Basic Presence</h2>
+<p>
+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:
+</p>
+<pre>
+<presence>
+ <show>dnd</show>
+ <status>My Status Message</status>
+</presence>
+</pre>
+<p>
+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.
+</p>
+<p>
+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:
+</p>
+<pre>
+<presence from="friend%hotmail.com@msn.host.com">
+ <show>away</show>
+ <status>My Friend's Status Message</status>
+</presence>
+</pre>
+
+<hr/>
+
+<h2>Adding Contacts</h2>
+<p>
+To add a MSN contact you should follow the instructions given in
+section 6.3, (jabber:iq:gateway) of
+JEP-0100 (<a href="http://www.jabber.org/jeps/jep-0100.html#addressing-gateway">Gateway Interaction</a>).
+</p>
+
+<hr/>
+
+<h2>Typing notification</h2>
+<p>
+PyMSNt supports typing notification according to JEP-0022
+(<a href="http://www.jabber.org/jeps/jep-0022.html">Message Events</a>).
+Only the <composing/> tag is supported.
+</p>
+
+<hr/>
+
+<h2>Request no errors</h2>
+<p>
+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.
+</p>
+<p>
+To tell PyMSNt you don't want to hear about any errors do this
+</p>
+<pre>
+<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>
+</pre>
+
+<hr/>
+
+<h2>Groupchat</h2>
+<p>
+PyMSNt only uses a subset of JEP-0045
+(<a href="http://www.jabber.org/jeps/jep-0045.html">Multi-User Chat</a>).
+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.
+</p>
+
+<hr/>
+
+<h2>Avatars</h2>
+<p>
+PyMSNt implements avatars using the vCard. See <a href="http://www.jabber.org/jeps/jep-0054.html">vcard-temp</a>.
+To get the vCard of a MSN contact you should do this:
+</p>
+<pre>
+<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>
+</pre>
+<p>
+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!
+</p>
+<p>
+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.
+</p>
+<p>
+If you want to get avatars or nicknames to dynamically update when changed
+then you need to implement the next section.
+</p>
+
+<hr/>
+
+<h2>Dynamic vCard Updates</h2>
+<p>
+To signal an update of your avatar or nickname send a presence packet
+like below. Do this after you have updated your vCard.
+</p>
+<pre>
+<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>
+</pre>
+<p>
+In the above example the nickname tag SHOULD be identical to the nickname
+you specify in your vCard's nickname field.
+</p>
+<p>
+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 :)
+</p>
+<p>
+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, (<a href="http://www.jabber.org/jeps/jep-0054.html">vcard-temp</a>).
+</p>
+<p>
+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.
+</p>
+<p>
+Status and show fields behave exactly as described above in "Basic Presence"
+</p>
+
+<hr/>
+
+<h2>Roster Pushes</h2>
+<p>
+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.
+</p>
+<p>
+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.
+</p>
+<p>
+For more details see <a href="http://msn-transport.jabberstudio.org/jep/roster-subsync/JEP-01XX-0.4.html">http://msn-transport.jabberstudio.org/jep/roster-subsync/JEP-01XX-0.4.html</a>
+</p>
+<p>
+If you receive one of these packets, then it will look like this.
+</p>
+<pre>
+<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>
+</pre>
+<p>
+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.
+</p>
+<p>
+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.
+</p>
+
+<h3>Security Concerns</h3>
+<p>
+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.
+</p>
+<p>
+PyMSNt will not ever send any of these messages until after you have authorised
+the gateway itself. The process works like this.
+</p>
+<ul>
+<li>User registers with gateway</li>
+<li>Gateway requests authorisation from user</li>
+<li>User's client prompts them to authorise the gateway. At this point
+you should also check with the user if it's ok to accept any incoming
+roster-subsync's from this domain</li>
+<li>User's client authorises gateway</li>
+<li>Gateway sends flood of roster pushes</li>
+<li>User's client automatically synchronises the packets with roster-subsync
+tags, only notifying the user about packets that do not have this tag</li>
+</ul>
+
+<p>
+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.
+</p>
+
+<hr/>
+
+
+
+<p>Bug reports and comments go to <a href="mailto:james@delx.cjb.net">James Bunton</a></p>
+<p>I'll gladly help you with any problems, but please look through this whole page first</p>
+
+
+</body>
+
+
+</html>
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+<link rel="stylesheet" href="style.css" type="text/css"/>
+<title>PyMSNt Server Administrator Guide</title>
+</head>
+
+<body>
+
+<h1>PyMSNt Server Administrator Guide</h1>
+
+
+<p>This documentation is for version 0.11 of the transport.</p>
+<p>Please visit <a href="http://msn-transport.jabberstudio.org">http://msn-transport.jabberstudio.org</a> to download the transport and see news updates.</p>
+<p>Please visit the <a href="http://msn-transport.jabberstudio.org/docs/user.html">MSN Transport User's Guide</a> if you are a Jabber user and want to talk to your MSN friends.</p>
+<p>If you have any insights or comments to add to this page please let me know by email or Jabber: james@delx.cjb.net</p>
+
+<hr/>
+
+
+<h2>Installation Guide</h2>
+
+<p>Instructions/suggestions for other servers and OSs are welcome</p>
+
+<h3>Basic Installation</h3>
+
+<ol>
+
+<li><h4>Python</h4>
+<p>
+Make sure have installed Python 2.3 or newer (I have reports that some older versions work). Most distributions should handle this automatically for you.
+</p>
+<ul>
+<li>Mandrake: <pre>urpmi python</pre></li>
+<li>Debian: <pre>apt-get install python2.3</pre></li>
+<li>Fedora: <pre>yum install python</pre></li>
+<li>Centos 4: <pre>yum install python</pre></li>
+<li>Suse: <pre>yast -i python</pre></li>
+<li>Darwin: You need <a href="http://finkproject.org">fink</a> unstable. <pre>fink install python</pre> (Install Python with fink, because we will use other Python libraries from fink later)</li>
+<li>MS Windows: Download and run the binary installer from <a href="http://www.python.org">http://www.python.org</a>. When complete, add the directory that python.exe is in to your PATH (look in Windows help for details on doing this)</li>
+<li>Others: Use your distribution's installation method, or download and compile the source from <a href="http://www.python.org">http://www.python.org</a></li>
+</ul>
+</li>
+
+<li><h4>Twisted</h4>
+<p>
+Install the Twisted framework (library). Version 1.1 or newer should be fine.
+Please make sure you're using PyMSNt 0.9.3 or newer for Twisted 2.0 support.
+</p>
+<p>
+If you're using Twisted 2.0, either grab the "Sumo" package (easiest),
+or make sure you download at least these modules: core, web, words
+</p>
+<ul>
+<li>Mandrake: You will need to download the pycrypto and python openssl RPMs and install them as well as twisted using urpmi. Unfortunately I cannot provide links. I know you can get them from Mandrake Club though.</li>
+<li>Debian: <pre>apt-get install python2.3-twisted python2.3-crypto \
+ python2.3-pyopenssl</pre></li>
+<li>Fedora: <pre>yum install python-twisted pyOpenSSL pycrypto</pre></li>
+<li>Centos 4: <pre>yum install python-twisted python-crypto pyOpenSSL</pre></li>
+<li>Suse: <pre>yast -i python-twisted python-openssl python-pycrypto</pre></li>
+<li>Darwin: <pre>fink install twisted-py23 pycrypto-py23 pyopenssl-py23</pre></li>
+<li>MS Windows: Download and run the binary installers for Twisted, PyCrypto and PyOpenSSL from <a href="http://www.twistedmatrix.com">http://www.twistedmatrix.com</a></li>
+<li>Others: Use your distribution's installation method, or download (and compile when necessary) from <a href="http://www.twistedmatrix.com">Twisted</a>, <a href="http://pyopenssl.sourceforge.net/">PyOpenSSL</a> and <a href="http://www.amk.ca/python/code/crypto.html">PyCrypto</a></li>
+</ul>
+</li>
+
+<li><h4>PyMSNt</h4>
+<p>
+Download PyMSNt from <a href="http://msn-transport.jabberstudio.org">msn-transport.jabberstudio.org</a> and decompress it to a suitable location.
+</p>
+</li>
+
+<li><h4>Configure</h4>
+<p>
+Copy the file config-example.xml to config.xml and edit it to suit your environment.<br/>
+Note, with older versions of PyMSNt you were supposed to edit config.py. This is NOT recommended in this version.
+</p>
+<ul>
+<li>The 'jid' setting should be the ID you want PyMSNt to take on the network.
+Example: 'msn.host.com'.</li>
+<li>The 'host' setting should be a public DNS or IP address of the server the transport is running on. This is needed for file transfer!</li>
+<li>The 'mainServer' setting should be the IP address or DNS of the main Jabber server.
+Default: '127.0.0.1'.</li>
+<li>The 'port' setting is the port that PyMSNt and the Jabber server agree to use to connect between them (more details on this below). Default: '5347'.</li>
+<li>The 'secret' setting should match the secret specified for component connections in your main Jabber server. It's a password that only the Jabber server and the transport must know.</li>
+<li>The 'website' setting should be a website to refer users to.</li>
+<li>There are other options in this file that are documented by comments. It is safe to leave them at the default values.</li>
+<li>Ensure that the transport can make outgoing connections on port 443 (HTTPS), 1863, as well as incoming connections on 8010 (for Jabber file transfers).</li>
+</ul>
+</li>
+
+<li><h4>Spool directory</h4>
+<p>
+PyMSNt stores login information (MS Passport account, password and nick) in the spool directory.
+This directory should meet this conditions:
+</p>
+<ul>
+<li>be located in the same place as the README and TODO files</li>
+<li>be writeable by whatever system user will be running PyMSNt</li>
+<li>have the same name as the 'jid' value you specified above in config.xml. (for example: 'msn.host.com')</li>
+</ul>
+<p>
+This directory will be automatically created for you if this is a fresh installation. If you are migrating from an older version of the transport (including the C version), you can copy your existing spool directory into the new location.<br/>
+Don't forget to rename it to the 'jid' value you specified on config.xml
+</p>
+</li>
+
+<li><h4>Configure Jabber server</h4>
+<p>
+Now you have to configure your Jabber server.
+The following section covers this in detail.
+</p>
+</li>
+
+<li><h4>Start PyMSNt</h4>
+<p>
+Now you're ready to start PyMSNt for the first time:
+</p>
+<pre>
+./PyMSNt.py
+</pre>
+<p>
+It will connect to the Jabber server and serve the Discovery JID you specified.
+Note: PyMSNt does not implement the old and deprecated 'Browse' capacity,
+only the newer 'Discovery'.
+</p>
+<p>
+On MS Windows you can run it by opening a DOS console in the PyMSNt directory and running "python PyMSNt.py"
+</p>
+<p>
+You may wish to find a rc.d script to automatically start the transport on Linux, or to make the transport into a service on Windows.
+</p>
+</li>
+
+</ol>
+
+<hr/>
+
+
+<h3>Jabber Server Configuration</h3>
+
+<p>The instructions below assume you are running PyMSNt on the same machine as your main Jabber server</p>
+
+<ul>
+<li><h4>Jabberd1.4.x</h4>
+<p>If you are using Jabberd1.4.x then you need to add this to your jabber.xml file</p>
+<pre>
+ <service id="msn.host.com">
+ <host>msn.host.com</host>
+ <accept>
+ <ip>127.0.0.1</ip>
+ <port>5347</port>
+ <secret>secret</secret>
+ </accept>
+ </service>
+</pre>
+<p>
+Check that msn.host.com is the same as the 'jid' setting from config.xml and
+that 5347 is the same as the 'port' setting. Also 'secret' must correspond, and the 'mainServer' setting should be pointing to the same interface as the <ip/> tag is (in this example the loopback interface is used. So 'mainServer' would be '127.0.0.1').
+</p>
+<p>You must also add this to the browse section of your jabber.xml file</p>
+<pre>
+ <service type="msn" jid="msn.host.com" name="MSN Transport">
+ <ns>jabber:iq:register</ns>
+ <ns>jabber:iq:gateway</ns>
+ </service>
+</pre>
+<p>Once again, msn.host.com must correspond to the 'jid' setting in config.xml</p>
+<p>Once you have made all these changes, restart your Jabberd1.4.x server, then start PyMSNt and it should all work.</p>
+</li>
+
+<li><h4>Jabberd2</h4>
+<p>If you are using Jabberd2 then you shouldn't have to do much configuration. Make sure the 'mainServer' setting is the IP or DNS of your Jabber server, and leave the 'port' setting alone. Double-check that the secret for legacy components in router.xml (for Jabberd2) is the same as the secret setting in config.xml. That should be all. You don't even need to restart Jabberd2.</p>
+<p>You may need to add the following to your Jabberd2 router-users.xml</p>
+<pre>
+<user>
+ <name>msn.host.com</name>
+ <secret>secret</secret>
+</user>
+</pre>
+<p>
+If you are upgrading from the old C version of MSN-t then you need to remove the alias info in your router.xml and the item discovery
+info in your sm.xml for the old msn transport. These were needed for the old MSN-t, but Jabberd2 can automatically add the new PyMSNt to the browse lists.
+</p>
+</li>
+
+<li><h4>ejabberd</h4>
+<p>
+To configure ejabberd for PyMSNt, as explained in <a
+href="http://ejabberd.jabberstudio.org/guide.html#htoc17">ejabberd Guide</a>:
+</p>
+<ol>
+<li>Edit <i>ejabberd.cfg</i>.</li>
+<li>In the section that says: '<i>{listen,</i>' add those two lines:
+<pre>
+ {5347, ejabberd_service, [{host, "msn.host.com",
+ [{password, "secret"}]}]},
+
+</pre>
+</li>
+<li>Restart ejabberd and you're done.</li>
+</ol>
+</li>
+</ul>
+
+<hr/>
+
+
+<h2>Clustering</h2>
+
+<p>More to be written... For now, have a look at the compjid option.</p>
+
+<hr/>
+
+<h2>Tips</h2>
+<ul>
+<li>You can send 'end' to the transport's bare JID at any time to completely destroy your session.</li>
+<li>You can specify the transport should use a different config file by passing the name of the file as an argument, eg
+<pre>
+./PyMSNt -c /etc/jabber/pymsnt.xml &
+</pre>
+If you are using multiple configurations it is recommended that you specify using absolute paths to the PID and spool settings in each of the configurations.
+</li>
+<li>There are many settings in the config.xml file, have a look and see if any of them would be useful to you</li>
+<li>The transport will try to talk to the user in their own language, provided their client sends a xml:lang attribute. You can read about this in the <a href="http://xmpp.org">XMPP RFCs</a>. If you want your language to be included, please have a look at lang.py, make a translation and send it to me.</li>
+<li>On Unix platforms sending a SIGHUP will cause the transport to reload the config file and close & open the debug.log file, eg
+<pre>
+kill -1 `cat PyMSNt.pid`
+</pre>
+Run in the directory that PyMSNt.pid is in. This will send a SIGHUP signal to the transport.
+</li>
+<li>If you want your transport to be accessible to other Jabber servers then make sure the JID is resolvable by DNS. Note that not having a resolvable DNS doesn't prevent a determined server admin from using your gateway.</li>
+<li>To disable file transfer, simply comment out the ftJabberPort and ftOOBPort options. This will disable file transfer in both directions.</li>
+</ul>
+<hr/>
+
+<h2>Possible problems:</h2>
+
+<ul>
+<li>On MS Windows, if you can't run PyMSNt, make sure you have Python installed correctly (as well as all of Twisted and PyCrypto/PyOpenSSL), and that python.exe is in your PATH (see above).</li>
+<li>See the <a href="http://msn-transport.jabberstudio.org/docs/user.html">User's Guide to PyMSNt</a> for more details on using the transport</li>
+<li>If you are upgrading from the CMSN-t and your Jabber server has been running
+prior to about November 2003 then some of your users' contact lists may have
+msn.host.com/registered in them. These users should delete the transport from their list, and reregister it. There is no need to delete the transport users (so they will not have to reauthorise any contacts).</li>
+<li>Under some circumstances CMSNt will split your spool directory into many subdirectories. To use this spool directory with PyMSNt, you can first run this command in your current spool directory:
+<pre>find -name '*.xml' -exec cp -v {} fixed_msn.host.com \;</pre>
+</li>
+</ul>
+
+<hr/>
+
+
+
+<p>Bug reports and comments go to <a href="mailto:james@delx.cjb.net">James Bunton</a></p>
+<p>I'll gladly help you with any problems, but please look through this whole page, the README & config.xml files first.</p>
+
+
+</body>
+
+
+</html>
--- /dev/null
+<style type="text/css">
+h2 { text-align:center; margin-top: 2em }
+h3,h4,h5,h6 { margin-left: 4%; margin-right: 4% }
+p { margin-left: 4%; margin-right: 4% }
+pre, ol, ul, dl { margin-left: 6%; margin-right: 6% }
+li { margin-bottom: 1em }
+hr { width: 92% }
+</style>
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+<link rel="stylesheet" href="style.css" type="text/css"/>
+<title>Jabber MSN Gateway User Guide</title>
+</head>
+
+<body>
+
+<h1>Jabber MSN Gateway User Guide</h1>
+
+
+<p>Please visit the <a href="http://msn-transport.jabberstudio.org/docs/server.html">Server Administrator Guide</a> if you are a server administrator looking for information on how to configure/install the transport.</p>
+<p>If you have any insights or comments to add to this page please contact me by Jabber or email: james@delx.cjb.net</p>
+
+<hr/>
+
+
+<h2>Usage Guide</h2>
+
+<p>You must already have a Jabber client (a program to connect to a Jabber server) set up with your Jabber account to follow these instructions</p>
+
+<p>These are generic instructions, intended to be useful no matter which Jabber client or what operating system you are using. Please read through them in their entirety before beginning.</p>
+
+<hr/>
+
+<h3>Getting started - Registration</h3>
+<p>
+It is recommended that you register using the <a href="http://msn-transport.jabberstudio.org/webreg">Jabber Transport Registration Form</a>.
+Your Jabber server may have this form available on their website. So have a look there too.
+</p>
+<p>
+To register with your Jabber client, follow these steps.
+</p>
+<ul>
+<li>First, you must check that your Jabber server has the MSN gateway installed. To do this, look for a menu item or button labelled something like "Browse Services", "Service Discovery" or "Transports/Gateways".</li>
+<li>If you see "MSN Transport" in the list you can continue, otherwise you can either ask the person who runs your Jabber server to install the MSN gateway, or you can try using the transports from another server. If there is an option to browse to a different server you may want to use that to use the MSN Gateway on another server.</li>
+<li>To proceed you must be able to choose to register with the MSN Transport from the browse list. You can usually do this by double-clicking it's icon, or clicking it and choosing register.</li>
+<li>Type your MSN passport into the username field (eg, fred@hotmail.com) and fill in your password.</li>
+<li>When you click the register button you will receive a Jabber authorisation message (to do with allowing users to view your online status) for each user on your MSN list. This can be a lot of messages. This step can only be avoided by using the <a href="http://msn-transport.jabberstudio.org/webreg">Transport Registration Form</a> mentioned above. Some clients (notably <a href="http://psi.affinix.com">Psi</a>) provide an option in the advanced section to auto-accept authorisation requests. You may wish to turn this on before continuing, and then turn it off afterwards. Please note that this flood will only occur once, upon registration of the transport.</li>
+<li>Click the register button, and accept any subscription messages you see.</li>
+<li>You should now be registered with the MSN transport. You should see the users from your MSN contact list appear. These steps will not need to be repeated.</li>
+</ul>
+
+<hr/>
+
+<h3>Adding a friend to your list</h3>
+<p>
+To add a person who only uses MSN to your contact list you must translate their MSN passport (eg, bob@hotmail.com) into a Jabber ID. This is very simple to do.<br/>
+Many clients will do this for you automatically if you tell them to:
+</p>
+<ul>
+<li>In Psi, choose "Add Contact" from the menu.</li>
+<li>Select MSN from the list</li>
+<li>Type your friend's MSN ID in the box</li>
+<li>Click the "Get Jabber ID" button, then click "Add", and you're done.</li>
+</ul>
+<p>For clients that do not support this, you must manually translate their MSN passport. Here are some examples:</p>
+<ul>
+<li>If the MSN passport is bob@hotmail.com, and your Jabber server's MSN Transport address is msn.host.com, then the Jabber ID of that MSN user is bob%hotmail.com@msn.host.com</li>
+<li>If the MSN passport of the user is fred@yahoo.com, and your Jabber server is tipic.com, then the Jabber ID of that user is fred%yahoo.com@msn.tipic.com</li>
+<li>All that happens is the @ symbol is exchanged for a % sign, and you add @msn.host.com to the end.</li>
+</ul>
+
+
+<hr/>
+
+<h3>Chatting with friends</h3>
+<ul>
+<li>To chat with a MSN user you perform the same process you would for a Jabber user, simply double-click their name in your contact list, and chat type a message.</li>
+<li>To start a groupchat (more than one person in a "room") with MSN users you must do the following.
+ <ul>
+ <li>Join a room on the msn.host.com server (where host.com is your Jabber server). The room name is not important, just make sure it does not have a % sign in it.</li>
+ <li>Invite your MSN contacts to this room to chat with them</li>
+ <li>Note that you cannot invite other Jabber users to this room. Attempts to do so will fail. This will not be possible in the future either</li>
+ </ul>
+</li>
+</ul>
+
+<hr/>
+
+<h3>Setting personal details</h3>
+<ul>
+<li>Out of all the data in your Jabber vCard, only the photo and your nickname can be sent to MSN users.</li>
+<li>You can set a nickname in Psi by going to Account Setup->Modify->Details->Edit Personal Details. In recent versions this will allow you to set your avatar as well.</li>
+<li>Your Jabber status message appears to MSN users as the "Personal Message"</li>
+</ul>
+
+<hr/>
+
+<h3>Multiple Resources</h3>
+<p>Jabber allows you to log into your account multiple times. For example, you could be logged in at home, at work, and on your laptop simultaneously.</p>
+<p>Because MSN Messenger does not have any concept of this, messages will always go to your <i>highest priority</i> resource by default. It is important to set the client you're using to a higher priority that the ones that you're not.</p>
+<p>If you do happen to send a message to somebody from a lower priority resource, then messages from that person will be sent to that resource until:</p>
+<ul>
+ <li>You log out from that resource.</li>
+ <li>You send a message to that person from another resource.</li>
+ <li>That user closes the chat window on their machine.</li>
+</ul>
+
+<hr/>
+
+<h3>Things that don't work yet</h3>
+<ul>
+<li>Avatars and file transfer are supported, but only in the latest release. So you may need to ask your server administrator to update. Also, you need to make sure your Jabber client supports avatars and file transfer.</li>
+<li>Please do not add yourself to your contact list.</li>
+</ul>
+
+<hr/>
+
+<h3>Misc Notes</h3>
+
+<ul>
+<li>If you wish to remove the MSN transport and all of your MSN contacts from your Jabber contact list you must be sure to remove the MSN transport <em>first</em>, followed by the contacts. If you do it the other way around then your MSN contacts will be removed from the MSN server's contact list too (so the next time you sign in with MSN Messenger you will have no contacts)</li>
+<li>If your MSN transport session seems frozen, and logging in & out doesn't fix it. Try double-clicking the MSN Transport icon in your list, and sending a "end" as a message. That should log you out of MSN and you can try using the transport again.</li>
+</ul>
+
+</body>
+
+</html>