Package twisted :: Package protocols :: Module msn :: Class MSNSwitchboardClient

[show private | hide private]
[frames | no frames]

## Class MSNSwitchboardClient

    BaseProtocol --+
                   |
            Protocol --+
                       |
            LineReceiver --+
                           |
                MSNEventBase --+
                               |
                              MSNSwitchboardClient

this class provides support for clients connecting to a switchboard server.

Switchboard servers are used for conversations with other people on the MSN network. This means that the number of conversations at any given time will be directly proportional to the number of connections to varioius switchboard servers. MSN makes no distinction between single and group conversations, so any number of users may be invited to join a specific conversation taking place on a switchboard server.

Method Summary
| `__init__(self)`
| ``checkMessage`(self, message)` hook for detecting any notification type messages (e.g.
| ``connectionFailed`(self)` (Deprecated) (inherited from `Protocol`)
| ``connectionLost`(self, reason)` Called when the connection is shut down.
| ``connectionMade`(self)` Called when a connection is made.
| ``dataReceived`(self, data)` Protocol.dataReceived. (inherited from `LineReceiver`)
| ``fileInvitationReply`(self, iCookie, accept)` used to reply to a file transfer invitation.
| ``gotBadLine`(self, line, why)` called when a handler notifies me that this line is broken (inherited from `MSNEventBase`)
| ``gotChattingUsers`(self, users)` called after connecting to an existing chat session.
| ``gotError`(self, errorCode)` called when the server sends an error which is not in response to a sent command (ie. (inherited from `MSNEventBase`)
| ``gotMessage`(self, message)` called when we receive a message.
| ``gotSendRequest`(self, fileName, fileSize, iCookie, message)` called when a contact is trying to send us a file.
| `handle_ACK(self, params)`
| `handle_ANS(self, params)`
| `handle_BYE(self, params)`
| `handle_CAL(self, params)`
| `handle_IRO(self, params)`
| `handle_JOI(self, params)`
| `handle_MSG(self, params)` (inherited from `MSNEventBase`)
| `handle_NAK(self, params)`
| ``handle_UNKNOWN`(self, cmd, params)` implement me in subclasses if you want to handle unknown events (inherited from `MSNEventBase`)
| `handle_USR(self, params)`
| ``inviteUser`(self, userHandle)` used to invite a user to the current switchboard server.
| ``lineLengthExceeded`(self, line)` Called when the maximum line length has been reached. (inherited from `LineReceiver`)
| ``lineReceived`(self, line)` Override this for when each line is received. (inherited from `MSNEventBase`)
| ``loggedIn`(self)` called when all login details have been negotiated.
| ``makeConnection`(self, transport)` Make a connection to a transport and a server. (inherited from `BaseProtocol`)
| ``rawDataReceived`(self, data)` Override this for when raw data is received. (inherited from `MSNEventBase`)
| ``sendFileInvitation`(self, fileName, fileSize)` send an notification that we want to send a file.
| ``sendLine`(self, line)` Sends a line to the other end of the connection. (inherited from `LineReceiver`)
| ``sendMessage`(self, message)` used to send a message.
| ``sendTransferInfo`(self, accept, iCookie, authCookie, ip, port)` send information relating to a file transfer session.
| ``sendTypingNotification`(self)` used to send a typing notification.
| ``setLineMode`(self, extra)` Sets the line-mode of this receiver. (inherited from `LineReceiver`)
| ``setRawMode`(self)` Sets the raw mode of this receiver. (inherited from `LineReceiver`)
| ``userJoined`(self, userHandle, screenName)` called when a user has joined the conversation.
| ``userLeft`(self, userHandle)` called when a user has left the conversation.
| ``userTyping`(self, message)` called when we receive the special type of message notifying us that a user is typing a message.
| ``_checkFileInfo`(self, message, info)` helper method for checkMessage
| ``_checkFileInvitation`(self, message, info)` helper method for checkMessage
| ``_checkFileResponse`(self, message, info)` helper method for checkMessage
| ``_checkTyping`(self, message, cTypes)` helper method for checkMessage
| ``_createIDMapping`(self, data)` return a unique transaction ID that is mapped internally to a deferred .. (inherited from `MSNEventBase`)
| ``_fireCallback`(self, id, *args)` Fire the callback for the given id if one exists and return 1, else return false (inherited from `MSNEventBase`)
| `_newInvitationCookie(self)`
| ``_nextTransactionID`(self)` return a usable transaction ID (inherited from `MSNEventBase`)
| ``_sendInit`(self)` send initial data based on whether we are replying to an invitation or starting one.

Instance Variable Summary
| `key` - authorization key, obtained when receiving invitation / requesting switchboard server.
| `reply` - set this to 1 in connectionMade or before to signifiy that you are replying to a switchboard invitation.
| `sessionID` - unique session ID, used if you are replying to a switchboard invitation
| `userHandle` - your user handle (passport)

Class Variable Summary
`int` | `key`
`int` | `reply`
`str` | `sessionID`
`str` | `userHandle`
`int` | `_iCookie`

Method Details

### checkMessage(self, message)

hook for detecting any notification type messages (e.g. file transfer)

### connectionLost(self, reason)

Called when the connection is shut down.

Clear any circular references here, and any external references to this Protocol. The connection has been closed.

  Parameters:
    `reason`
    (type=`twisted.python.failure.Failure`)
  Overrides:
    `twisted.protocols.msn.MSNEventBase.connectionLost` (inherited documentation)

### connectionMade(self)

Called when a connection is made.

This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.

  Overrides:
    `twisted.protocols.msn.MSNEventBase.connectionMade` (inherited documentation)

### fileInvitationReply(self, iCookie, accept=1)

used to reply to a file transfer invitation.

  Parameters:
    `iCookie` - the invitation cookie of the initial invitation
    `accept` - whether or not you accept this transfer, 1 = yes, 0 = no, default = 1.
  Returns:
    A Deferred, the callback for which will be fired when the user responds with the transfer information. The callback argument will be a tuple with 5 elements, whether or not they wish to proceed with the transfer (1=yes, 0=no), their ip, the port, the authentication cookie (see MSNFileReceive/MSNFileSend) and the message info (dict) (in case they send extra header-like info like Internal-IP, this doesn't necessarily need to be used). If you wish to proceed with the transfer see MSNFileReceive.

### gotChattingUsers(self, users)

called after connecting to an existing chat session.

  Parameters:
    `users` - A dict mapping usre handles to screen names (current users taking part in the conversation)

### gotMessage(self, message)

called when we receive a message.

  Parameters:
    `message` - the associated MSNMessage object

### gotSendRequest(self, fileName, fileSize, iCookie, message)

called when a contact is trying to send us a file. To accept or reject this transfer see the fileInvitationReply method.

  Parameters:
    `fileName` - the name of the file
    `fileSize` - the size of the file
    `iCookie` - the invitation cookie, used so the client can match up your reply with this request.
    `message` - the MSNMessage object which brought about this invitation (it may contain more information)

### inviteUser(self, userHandle)

used to invite a user to the current switchboard server.

  Parameters:
    `userHandle` - the user handle (passport) of the desired user.
  Returns:
    A Deferred, the callback for which will be called when the server notifies us that the user has indeed been invited. The callback argument will be a tuple with 1 element, the sessionID given to the invited user. I'm not sure if this is useful or not.

### loggedIn(self)

called when all login details have been negotiated. Messages can now be sent, or new users invited.

### sendFileInvitation(self, fileName, fileSize)

send an notification that we want to send a file.

  Parameters:
    `fileName` - the file name
    `fileSize` - the file size
  Returns:
    A Deferred, the callback of which will be fired when the user responds to this invitation with an appropriate message. The callback argument will be a tuple with 3 elements, the first being 1 or 0 depending on whether they accepted the transfer (1=yes, 0=no), the second being an invitation cookie to identify your follow-up responses and the third being the message 'info' which is a dict of information they sent in their reply (this doesn't really need to be used). If you wish to proceed with the transfer see the sendTransferInfo method.

### sendMessage(self, message)

used to send a message.

  Parameters:
    `message` - the corresponding MSNMessage object.
  Returns:
    Depending on the value of message.ack. If set to MSNMessage.MESSAGE_ACK or MSNMessage.MESSAGE_NACK a Deferred will be returned, the callback for which will be fired when an ACK or NCK is received - the callback argument will be (None,). If set to MSNMessage.MESSAGE_ACK_NONE then the return value is None.

### sendTransferInfo(self, accept, iCookie, authCookie, ip, port)

send information relating to a file transfer session.

  Parameters:
    `accept` - whether or not to go ahead with the transfer (1=yes, 0=no)
    `iCookie` - the invitation cookie of previous replies relating to this transfer
    `authCookie` - the authentication cookie obtained from an MSNFileSend instance
    `ip` - your ip
    `port` - the port on which an MSNFileSend protocol is listening.

### sendTypingNotification(self)

used to send a typing notification. Upon receiving this message the official client will display a 'user is typing' message to all other users in the chat session for 10 seconds. The official client sends one of these every 5 seconds (I think) as long as you continue to type.

### userJoined(self, userHandle, screenName)

called when a user has joined the conversation.

  Parameters:
    `userHandle` - the user handle (passport) of the user
    `screenName` - the screen name of the user

### userLeft(self, userHandle)

called when a user has left the conversation.

  Parameters:
    `userHandle` - the user handle (passport) of the user.

### userTyping(self, message)

called when we receive the special type of message notifying us that a user is typing a message.

  Parameters:
    `message` - the associated MSNMessage object

### _checkFileInfo(self, message, info)

helper method for checkMessage

### _checkFileInvitation(self, message, info)

helper method for checkMessage

### _checkFileResponse(self, message, info)

helper method for checkMessage

### _checkTyping(self, message, cTypes)

helper method for checkMessage

### _sendInit(self)

send initial data based on whether we are replying to an invitation or starting one.

Instance Variable Details

### key

authorization key, obtained when receiving invitation / requesting switchboard server.

### reply

set this to 1 in connectionMade or before to signifiy that you are replying to a switchboard invitation.

### sessionID

unique session ID, used if you are replying to a switchboard invitation

### userHandle

your user handle (passport)

Class Variable Details

### key

  Type:
    `int`
  Value:

        0

### reply

  Type:
    `int`
  Value:

        0

### sessionID

  Type:
    `str`
  Value:

        ''

### userHandle

  Type:
    `str`
  Value:

        ''

### _iCookie

  Type:
    `int`
  Value:

        0

Generated by Epydoc 1.1 on Thu May 8 13:18:52 2003 | http://epydoc.sf.net