From: jamesbunton Date: Sat, 18 Mar 2006 12:30:17 +0000 (+0000) Subject: Added docs to version control. X-Git-Url: https://code.delx.au/pymsnt/commitdiff_plain/dacce305fcfe3594ea6336e12bd7f7330501e870?hp=c4a69377f28b46025f8ee9d4500c44e598df644a Added docs to version control. git-svn-id: http://delx.cjb.net/svn/pymsnt/trunk@126 55fbd22a-6204-0410-b2f0-b6c764c7e90a committer: jamesbunton --- diff --git a/docs/developer.html b/docs/developer.html new file mode 100644 index 0000000..8ccd360 --- /dev/null +++ b/docs/developer.html @@ -0,0 +1,313 @@ + + + + + +PyMSNt Client Developer Guide + + + + +

PyMSNt Client Developer Guide

+ + +

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

+ +
+ + +

Overview

+

+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. +

+ +
+ +

Required JEPs

+

+To register with PyMSNt your client must support JEP-0077, +(In-Band Registration). +
+It is also strongly recommended that you support: +

+ + +
+ +

Basic Presence

+

+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>
+
+ +
+ +

Adding Contacts

+

+To add a MSN contact you should follow the instructions given in +section 6.3, (jabber:iq:gateway) of +JEP-0100 (Gateway Interaction). +

+ +
+ +

Typing notification

+

+PyMSNt supports typing notification according to JEP-0022 +(Message Events). +Only the <composing/> tag is supported. +

+ +
+ +

Request no errors

+

+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>
+
+ +
+ +

Groupchat

+

+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. +

+ +
+ +

Avatars

+

+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. +

+ +
+ +

Dynamic vCard Updates

+

+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" +

+ +
+ +

Roster Pushes

+

+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. +

+ +

Security Concerns

+

+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

+ + + + + + diff --git a/docs/server.html b/docs/server.html new file mode 100644 index 0000000..9c2228e --- /dev/null +++ b/docs/server.html @@ -0,0 +1,263 @@ + + + + + +PyMSNt Server Administrator Guide + + + + +

PyMSNt Server Administrator Guide

+ + +

This documentation is for version 0.11 of the transport.

+

Please visit http://msn-transport.jabberstudio.org to download the transport and see news updates.

+

Please visit the MSN Transport User's Guide if you are a Jabber user and want to talk to your MSN friends.

+

If you have any insights or comments to add to this page please let me know by email or Jabber: james@delx.cjb.net

+ +
+ + +

Installation Guide

+ +

Instructions/suggestions for other servers and OSs are welcome

+ +

Basic Installation

+ +
    + +

  1. Python

    +

    +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. +

    +
      +
    • Mandrake: 
      urpmi python
      • +
    • Debian: 
      apt-get install python2.3
      • +
    • Fedora: 
      yum install python
      • +
    • Centos 4: 
      yum install python
      • +
    • Suse: 
      yast -i python
      • +
    • Darwin: You need fink unstable. 
      fink install python
      (Install Python with fink, because we will use other Python libraries from fink later)
      • +
    • MS Windows: Download and run the binary installer from http://www.python.org. When complete, add the directory that python.exe is in to your PATH (look in Windows help for details on doing this)
      • +
    • Others: Use your distribution's installation method, or download and compile the source from http://www.python.org
      • +
    +
    2. + +

  2. Twisted

    +

    +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. +

    +

    +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 +

    +
      +
    • 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.
      • +
    • Debian: 
      apt-get install python2.3-twisted python2.3-crypto \
+                python2.3-pyopenssl
      • +
    • Fedora: 
      yum install python-twisted pyOpenSSL pycrypto
      • +
    • Centos 4: 
      yum install python-twisted python-crypto pyOpenSSL
      • +
    • Suse: 
      yast -i python-twisted python-openssl python-pycrypto
      • +
    • Darwin: 
      fink install twisted-py23 pycrypto-py23 pyopenssl-py23
      • +
    • MS Windows: Download and run the binary installers for Twisted, PyCrypto and PyOpenSSL from http://www.twistedmatrix.com
      • +
    • Others: Use your distribution's installation method, or download (and compile when necessary) from Twisted, PyOpenSSL and PyCrypto
      • +
    +
    3. + +

  3. PyMSNt

    +

    +Download PyMSNt from msn-transport.jabberstudio.org and decompress it to a suitable location. +

    +
    4. + +

  4. Configure

    +

    +Copy the file config-example.xml to config.xml and edit it to suit your environment.
    +Note, with older versions of PyMSNt you were supposed to edit config.py. This is NOT recommended in this version. +

    +
      +
    • The 'jid' setting should be the ID you want PyMSNt to take on the network. +Example: 'msn.host.com'.
      • +
    • 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!
      • +
    • The 'mainServer' setting should be the IP address or DNS of the main Jabber server. +Default: '127.0.0.1'.
      • +
    • 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'.
      • +
    • 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.
      • +
    • The 'website' setting should be a website to refer users to.
      • +
    • There are other options in this file that are documented by comments. It is safe to leave them at the default values.
      • +
    • Ensure that the transport can make outgoing connections on port 443 (HTTPS), 1863, as well as incoming connections on 8010 (for Jabber file transfers).
      • +
    +
    5. + +

  5. Spool directory

    +

    +PyMSNt stores login information (MS Passport account, password and nick) in the spool directory. +This directory should meet this conditions: +

    +
      +
    • be located in the same place as the README and TODO files
      • +
    • be writeable by whatever system user will be running PyMSNt
      • +
    • have the same name as the 'jid' value you specified above in config.xml. (for example: 'msn.host.com')
      • +
    +

    +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.
    +Don't forget to rename it to the 'jid' value you specified on config.xml +

    +
    6. + +

  6. Configure Jabber server

    +

    +Now you have to configure your Jabber server. +The following section covers this in detail. +

    +
    7. + +

  7. Start PyMSNt

    +

    +Now you're ready to start PyMSNt for the first time: +

    +
    +./PyMSNt.py
+
    +

    +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'. +

    +

    +On MS Windows you can run it by opening a DOS console in the PyMSNt directory and running "python PyMSNt.py" +

    +

    +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. +

    +
    8. + +
+ +
+ + +

Jabber Server Configuration

+ +

The instructions below assume you are running PyMSNt on the same machine as your main Jabber server

+ + + +
+ + +

Clustering

+ +

More to be written... For now, have a look at the compjid option.

+ +
+ +

Tips

+ +
+ +

Possible problems:

+ + + +
+ + + +

Bug reports and comments go to James Bunton

+

I'll gladly help you with any problems, but please look through this whole page, the README & config.xml files first.

+ + + + + + diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..aa7d995 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,8 @@ + diff --git a/docs/user.html b/docs/user.html new file mode 100644 index 0000000..0bc0f53 --- /dev/null +++ b/docs/user.html @@ -0,0 +1,122 @@ + + + + + +Jabber MSN Gateway User Guide + + + + +

Jabber MSN Gateway User Guide

+ + +

Please visit the Server Administrator Guide if you are a server administrator looking for information on how to configure/install the transport.

+

If you have any insights or comments to add to this page please contact me by Jabber or email: james@delx.cjb.net

+ +
+ + +

Usage Guide

+ +

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

+ +

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.

+ +
+ +

Getting started - Registration

+

+It is recommended that you register using the Jabber Transport Registration Form. +Your Jabber server may have this form available on their website. So have a look there too. +

+

+To register with your Jabber client, follow these steps. +

+ + +
+ +

Adding a friend to your list

+

+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.
+Many clients will do this for you automatically if you tell them to: +

+ +

For clients that do not support this, you must manually translate their MSN passport. Here are some examples:

+ + + +
+ +

Chatting with friends

+ + +
+ +

Setting personal details

+ + +
+ +

Multiple Resources

+

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.

+

Because MSN Messenger does not have any concept of this, messages will always go to your highest priority resource by default. It is important to set the client you're using to a higher priority that the ones that you're not.

+

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:

+ + +
+ +

Things that don't work yet

+ + +
+ +

Misc Notes

+ + + + + +