pyxmpp.client.Client

Package pyxmpp :: Module client :: Class Client |
[show private | hide private]
[frames | no frames]

## Class Client

Known Subclasses:
  `JabberClient`

Base class for an XMPP-IM client.

This class does not provide any JSF extensions to the XMPP protocol, including legacy authentication methods.

Method Summary
| ``__init__`(self, jid, password, server, port, auth_methods, tls_settings, keepalive)` Initialize a Client object.
| ``authenticated`(self)` Handle "authenticated" event.
| ``authorized`(self)` Handle "authorized" event.
| ``connect`(self, register)` Connect to the server and set up the stream.
| ``connected`(self)` Handle "connected" event.
| ``disconnect`(self)` Disconnect from the server.
| ``disconnected`(self)` Handle "disconnected" event.
`socket.socket` | ``get_socket`(self)` Get the socket object of the active connection.
`pyxmpp.ClientStream` | ``get_stream`(self)` Get the connected stream object.
| ``idle`(self)` Do some "housekeeping" work like cache expiration or timeout handling.
| ``loop`(self, timeout)` Simple "main loop" for the client.
| ``request_roster`(self)` Request the user's roster.
| ``request_session`(self)` Request an IM session.
| ``roster_updated`(self, item)` Handle roster update event.
| ``session_started`(self)` Handle session started event.
| ``stream_closed`(self, stream)` Handle stream closure event.
| ``stream_created`(self, stream)` Handle stream creation event.
| ``stream_error`(self, err)` Handle stream error received.
| ``stream_state_changed`(self, state, arg)` Handle any stream state change.

Instance Variable Summary
`list` of `str` | `auth_methods`: methods allowed for stream authentication.
`pyxmpp.JID` | `jid`: configured JID of the client (current actual JID is avialable as `self.stream.jid`).
`int` | `keepalive`: keepalive interval for the stream or 0 when keepalive is disabled.
`threading.RLock` | `lock`: lock for synchronizing `Client` attributes access.
`unicode` | `password`: authentication password.
`int` | `port`: port number on the server to use if non-standard and not discoverable by SRV lookups.
`pyxmpp.Roster` | `roster`: user's roster or `None` if the roster is not yet retrieved.
`unicode` | `server`: server to use if non-standard and not discoverable by SRV lookups.
`bool` | `session_established`: `True` when an IM session is established.
`threading.Condition` | `state_changed`: condition notified the the object state changes (stream becomes connected, session established etc.).
`pyxmpp.ClientStream` | `stream`: current stream when the client is connected, `None` otherwise.

Method Details

### __init__(self, jid=None, password=None, server=None, port=5222, auth_methods=('sasl:DIGEST-MD5',), tls_settings=None, keepalive=0) (Constructor) Initialize a Client object. Parameters: `jid` - user full JID for the connection. (type=`pyxmpp.JID`) `password` - user password. (type=`unicode`) `server` - server to use. If not given then address will be derived form the JID. (type=`unicode`) `port` - port number to use. If not given then address will be derived form the JID. (type=`int`) `auth_methods` - sallowed authentication methods. SASL authentication mechanisms in the list should be prefixed with "sasl:" string. (type=sequence of `str`) `tls_settings` - settings for StartTLS -- `TLSSettings` instance. (type=`pyxmpp.TLSSettings`) `keepalive` - keepalive output interval. 0 to disable. (type=`int`)

### authenticated(self) Handle "authenticated" event. May be overriden in derived classes. This one does nothing.

### authorized(self) Handle "authorized" event. May be overriden in derived classes. This one requests an IM session.

### connect(self, register=False) Connect to the server and set up the stream. Set `self.stream` and notify `self.state_changed` when connection succeeds.

### connected(self) Handle "connected" event. May be overriden in derived classes. This one does nothing.

### disconnect(self) Disconnect from the server.

### disconnected(self) Handle "disconnected" event. May be overriden in derived classes. This one does nothing.

### get_socket(self) Get the socket object of the active connection. Returns: socket used by the stream. (type=`socket.socket`)

### get_stream(self) Get the connected stream object. Returns: stream object or `None` if the client is not connected. (type=`pyxmpp.ClientStream`)

### idle(self) Do some "housekeeping" work like cache expiration or timeout handling. Should be called periodically from the application main loop. May be overriden in derived classes.

### loop(self, timeout=1) Simple "main loop" for the client. By default just call the `pyxmpp.Stream.loop_iter` method of `self.stream`, which handles stream input and `self.idle` for some "housekeeping" work until the stream is closed. This usually will be replaced by something more sophisticated. E.g. handling of other input sources.

### request_roster(self) Request the user's roster.

### request_session(self) Request an IM session.

### roster_updated(self, item=None) Handle roster update event. May be overriden in derived classes. This one does nothing. Parameters: `item` - the roster item changed or `None` if whole roster was received. (type=`pyxmpp.RosterItem`)

### session_started(self) Handle session started event. May be overriden in derived classes. This one sends the initial presence and requests the user's roster.

### stream_closed(self, stream) Handle stream closure event. May be overriden in derived classes. This one does nothing. Parameters: `stream` - the new stream. (type=`pyxmpp.ClientStream`)

### stream_created(self, stream) Handle stream creation event. May be overriden in derived classes. This one does nothing. Parameters: `stream` - the new stream. (type=`pyxmpp.ClientStream`)

### stream_error(self, err) Handle stream error received. May be overriden in derived classes. This one passes an error messages to logging facilities. Parameters: `err` - the error element received. (type=`pyxmpp.error.StreamErrorNode`)

### stream_state_changed(self, state, arg) Handle any stream state change. May be overriden in derived classes. This one does nothing. Parameters: `state` - the new state. (type=`str`) `arg` - state change argument.

Instance Variable Details

### auth_methods methods allowed for stream authentication. SASL mechanism names should be preceded with "sasl:" prefix. Type: `list` of `str`

### jid configured JID of the client (current actual JID is avialable as `self.stream.jid`). Type: `pyxmpp.JID`

### keepalive keepalive interval for the stream or 0 when keepalive is disabled. Type: `int`

### lock lock for synchronizing `Client` attributes access. Type: `threading.RLock`

### password authentication password. Type: `unicode`

### port port number on the server to use if non-standard and not discoverable by SRV lookups. Type: `int`

### roster user's roster or `None` if the roster is not yet retrieved. Type: `pyxmpp.Roster`

### server server to use if non-standard and not discoverable by SRV lookups. Type: `unicode`

### session_established `True` when an IM session is established. Type: `bool`

### state_changed condition notified the the object state changes (stream becomes connected, session established etc.). Type: `threading.Condition`

### stream current stream when the client is connected, `None` otherwise. Type: `pyxmpp.ClientStream`