twisted.protocols.msn

Package twisted :: Package protocols :: Module msn |
[frames | no frames]

## Module twisted.protocols.msn

MSNP8 Protocol (client only) - semi-experimental

Stability: unstable.

This module provides support for clients using the MSN Protocol (MSNP8). There are basically 3 servers involved in any MSN session:

Dispatch server

The DispatchClient class handles connections to the dispatch server, which basically delegates users to a suitable notification server.

You will want to subclass this and handle the gotNotificationReferral method appropriately.

Notification Server

The NotificationClient class handles connections to the notification server, which acts as a session server (state updates, message negotiation etc...)

Switcboard Server

The SwitchboardClient handles connections to switchboard servers which are used to conduct conversations with other users.

There are also two classes (FileSend and FileReceive) used for file transfers.

Clients handle events in two ways.

- each client request requiring a response will return a Deferred, the callback for same will be fired when the server sends the required response
- Events which are not in response to any client request have respective methods which should be overridden and handled in an adequate manner

Most client request callbacks require more than one argument, and since Deferreds can only pass the callback one result, most of the time the callback argument will be a tuple of values (documented in the respective request method). To make reading/writing code easier, callbacks can be defined in a number of ways to handle this 'cleanly'. One way would be to define methods like: def callBack(self, (arg1, arg2, arg)): ... another way would be to do something like: d.addCallback(lambda result: myCallback(*result)).

If the server sends an error response to a client request, the errback of the corresponding Deferred will be called, the argument being the corresponding error code.

NOTE: Due to the lack of an official spec for MSNP8, extra checking than may be deemed necessary often takes place considering the server is never 'wrong'. Thus, if gotBadLine (in any of the 3 main clients) is called, or an MSNProtocolError is raised, it's probably a good idea to submit a bug report. ;) Use of this module requires that PyOpenSSL is installed.

# TODO

- check message hooks with invalid x-msgsinvite messages.
- font handling
- switchboard factory

Author: Sam Jordan

Classes
`DispatchClient` | This class provides support for clients connecting to the dispatch server
`FileReceive` | This class provides support for receiving files from contacts.
`FileSend` | This class provides support for sending files to other contacts.
`MSNContact` | This class represents a contact (user).
`MSNContactList` | This class represents a basic MSN contact list.
`MSNEventBase` | This class provides support for handling / dispatching events and is the base class of the three main client protocols (DispatchClient, NotificationClient, SwitchboardClient)
`MSNMessage` | I am the class used to represent an 'instant' message.
`NotificationClient` | This class provides support for clients connecting to the notification server.
`NotificationFactory` | Factory for the NotificationClient protocol.
`PassportLogin` | This class is used internally to obtain a login ticket from a passport HTTPS server -- it should not be used directly.
`PassportNexus` | Used to obtain the URL of a valid passport login HTTPS server.
`SwitchboardClient` | This class provides support for clients connecting to a switchboard server.

Exceptions
`MSNProtocolError` | This Exception is basically used for debugging purposes, as the official MSN server should never send anything _wrong_ and nobody in their right mind would run their own MSN server.

Function Summary
| ``_login`(userHandle, passwd, nexusServer, cached, authData)` This function is used internally and should not ever be called directly.
| ``_parseHeader`(h, v)` Split a certin number of known header values with the format: field1=val,field2=val,field3=val into a dict mapping fields to values.
| `_parsePrimitiveHost(host)`
| `checkParamLen(num, expected, cmd, error)`

Variable Summary
`int` | `ALLOW_LIST` = 2
`int` | `BLOCK_LIST` = 4
`str` | `CR` = `'\r'`
`dict` | `errorCodes` = `{731: 'Not expected', 520: 'Memory allocati...`
`int` | `FORWARD_LIST` = 1
`str` | `HAS_PAGER` = `'MOB'`
`str` | `HOME_PHONE` = `'PHH'`
`str` | `LF` = `'\n'`
`dict` | `listCodeToID` = `{'rl': 8, 'bl': 4, 'fl': 1, 'al': 2}`
`dict` | `listIDToCode` = `{8: 'rl', 1: 'fl', 2: 'al', 4: 'bl'}`
`int` | `LOGIN_FAILURE` = 2
`int` | `LOGIN_REDIRECT` = 3
`int` | `LOGIN_SUCCESS` = 1
`str` | `MOBILE_PHONE` = `'PHM'`
`int` | `REVERSE_LIST` = 8
`str` | `STATUS_AWAY` = `'AWY'`
`str` | `STATUS_BRB` = `'BRB'`
`str` | `STATUS_BUSY` = `'BSY'`
`str` | `STATUS_HIDDEN` = `'HDN'`
`str` | `STATUS_IDLE` = `'IDL'`
`str` | `STATUS_LUNCH` = `'LUN'`
`str` | `STATUS_OFFLINE` = `'FLN'`
`str` | `STATUS_ONLINE` = `'NLN'`
`str` | `STATUS_PHONE` = `'PHN'`
`dict` | `statusCodes` = `{'PHN': 'On the Phone', 'IDL': 'Idle', 'BS...`
`str` | `WORK_PHONE` = `'PHW'`

Function Details

### _login(userHandle, passwd, nexusServer, cached=0, authData='') This function is used internally and should not ever be called directly.

### _parseHeader(h, v) Split a certin number of known header values with the format: field1=val,field2=val,field3=val into a dict mapping fields to values. Parameters: `h` - the header's key `v` - the header's value as a string

Variable Details

    ### ALLOW_LIST Type: `int` Value:
        2

    ### BLOCK_LIST Type: `int` Value:
        4

    ### CR Type: `str` Value:
        '\r'

    ### errorCodes Type: `dict` Value:
        {520: 'Memory allocation failed',
         600: 'Server is busy',
         731: 'Not expected',
         910: 'Server too busy',
         911: 'Authentication failed',
         912: 'Server too busy',
         914: 'Server too busy',
         915: 'Server too busy',
        ...

    ### FORWARD_LIST Type: `int` Value:
        1

    ### HAS_PAGER Type: `str` Value:
        'MOB'

    ### HOME_PHONE Type: `str` Value:
        'PHH'

    ### LF Type: `str` Value:
        '''
        '''

    ### listCodeToID Type: `dict` Value:
        {'rl': 8, 'bl': 4, 'fl': 1, 'al': 2}

    ### listIDToCode Type: `dict` Value:
        {8: 'rl', 1: 'fl', 2: 'al', 4: 'bl'}

    ### LOGIN_FAILURE Type: `int` Value:
        2

    ### LOGIN_REDIRECT Type: `int` Value:
        3

    ### LOGIN_SUCCESS Type: `int` Value:
        1

    ### MOBILE_PHONE Type: `str` Value:
        'PHM'

    ### REVERSE_LIST Type: `int` Value:
        8

    ### STATUS_AWAY Type: `str` Value:
        'AWY'

    ### STATUS_BRB Type: `str` Value:
        'BRB'

    ### STATUS_BUSY Type: `str` Value:
        'BSY'

    ### STATUS_HIDDEN Type: `str` Value:
        'HDN'

    ### STATUS_IDLE Type: `str` Value:
        'IDL'

    ### STATUS_LUNCH Type: `str` Value:
        'LUN'

    ### STATUS_OFFLINE Type: `str` Value:
        'FLN'

    ### STATUS_ONLINE Type: `str` Value:
        'NLN'

    ### STATUS_PHONE Type: `str` Value:
        'PHN'

    ### statusCodes Type: `dict` Value:
        {'AWY': 'Away',
         'BRB': 'Be Right Back',
         'BSY': 'Busy',
         'FLN': 'Offline',
         'HDN': 'Appear Offline',
         'IDL': 'Idle',
         'LUN': 'Out to Lunch',
         'NLN': 'Online',
        ...

    ### WORK_PHONE Type: `str` Value:
        'PHW'

Generated by Epydoc 2.0 on Sat May 15 20:07:44 2004 | http://epydoc.sf.net