client – XMPP client

Module author: Sylvain Hellegouarch <sh@defuze.org>

Client classes

BaseClient

class headstock.client.BaseClient(jid, password, tls=False, registerclass=None)

Defines a high level API by which your application connects to a XMPP server, creates a XMPP stream and sets the XML parser that will dispatch incoming stanzas to XMP handlers.

You would not create an instance of this directly but use one of its subclass.

jid Jabber identifier of the client account. It must at least be a bare jid.

password Account’s password.

tls False - Flag indicating if the client should use TLS should the server support it.

registerclass None - Class that will handle the registration process. It should be a subclass of headstock.register.Register. The default, None means the registration process is not handled by the client.

cleanup()

Called after the socket was closed.

This goes through registered handlers and calls their cleanup() method if they declare one.

default_handler(e)

log(stanza=None, prefix='', traceback=False)

Logs a stanza into its XML serialized form.

stanza bridge.Element instance to be serialized to a XML string.

prefix A string to prefix the line that will be created by the logger.

traceback False - Flag indicating the current traceback should be logged.

ready()

Called whenever the session is bound.

This goes through registered handlers and calls their ready(client) method if they declare one. The argument is the client’s instance.

register(handler)

Registers recipients for stanzas by going through the members of the provided handler instance. To be taken into account those members must have an attribute called handler set to True as well as a xmpp_local_name indicating which element is expected.

The actual methods will be wrapped into headstock.client.BaseClient.wrap_handler which will call the method and traps some of the headstock.error exceptions and act accordingly.

handler instance of an object that defines at least one method with the expected properties.

register_on_iq(handler, type=None, id=None, once=False)

Registers a callable as a recipient of a Iq stanza with the provided type and/or id attributes.

handler callable that must accept one single argument, a bridge.Element instance.

type None - stanza type to be matched

id None - stanza identifier to be matched

once False - Flag indicating if the handler should be unregistered automatically or not once it has been applied.

send_raw_stanza(stanza)

Sends a stanza already serialized as a XML string.

stanza a stanza serialized as a XML string

send_stanza(stanza)

Sends a stanza onto the wire by serializing it first to XML.

stanza bridge.Element instance to be sent.

send_stream_header()

Sends the initial stream header to the server.

set_log(path=None, stdout=False)

Sets the client’s logger. Note that the logger’s name is suffixed by the jid’s node so that you can create several of them within one single process.

path None - Filesystem path to use a file handler for the logger.

stdout False - Flag indicating if the logger should output to the standard outpout.

socket_error(msg=None)

Called whenever the socket was on error.

start()

Starts the client.

start_tls()

Starts the TLS negociation.

stop()

Stops the client by closing the stream.

stopping()

Called whenever the client stops but before the socket is closed (unless it was on error and already closed).

This goes through registered handlers and calls their stopping() method if they declare one.

swap_handler(new_handler, name, ns, once=False, forget=True)

Swap an existing handler with a new one.

new_handler callable to use from now on. It must accept a bridge.Element instance as its argument.

name stanza name

ns stanza namespace

once False - flag indicating if the handler should be unregistered automatically once it has been called

forget True - flag indicating if the dispatched stanza should be removed from memory once the handler has been called

terminated()

Called right before the client terminates.

This goes through registered handlers and calls their terminated() method if they declare one and then unregister them.

tls_ok()

Called when the TLS negociation is successful.

Reset the XML parser and sends a new stream header.

unregister(handler)

Unregisters recipents for stanzas.

handler instance of an object that defines at least one method with the expected properties.

unregister_all()

Unregisters all previously registered handler.

Note that this is done automatically when terminated is called.

unregister_from_iq(handler, type=None, id=None, once=False)

Unregisters a previously registered callable for a Iq stanza.

handler callable that must accept one single argument, a bridge.Element instance.

type stanza type to be matched

id stanza identifier to be matched

once False - Flag indicating if the handler should be unregistered automatically or not once it has been applied.

wrap_handler(e, handler, fire_once, forget)

Wrapper for any registered XMPP handler.

This traps a few exception:

• headstock.error.HeadstockStartTLS when the TLS has been requested and is

supported by the server. This then calls headstock.client.BaseClient.start_tls to initiate the TLS negociation.

• headstock.error.HeadstockAuthenticationSuccess when the authentication

was successful.

• headstock.error.HeadstockSessionBound when the session is

eventually bound. It automatically sends the initial presence and asks for the account’s roster. It also calls headstock.client.BaseClient.ready so that registered handlers are notified of the bound session.

e bridge.Element instance that has been dispatched by the XML parser.

handler callable applied with the bridge.Element instance. If another bridge.Element instance is returned, it will be sent to the server. You may also return a list of bridge.Element instances.

fire_once flag indicating if the handler should be applied only once or for ever.

forget flags indicating if the dispatched bridge.Element instance should be forgotten to free memory it uses.

AsyncClient

class headstock.client.AsyncClient(jid, password, hostname='localhost', port=5222, tls=False, registercls=None)

Bases: asyncore.dispatcher, headstock.client.BaseClient

run(start_loop=True)

Starts the client.

start_loop True - flag indicating if the asyncore.loop() function should be called too.

KamaeliaClient

class headstock.client.KamaeliaClient(jid, password, hostname='localhost', port=5222, tls=False, registercls=None)

Bases: Axon.Component.component, headstock.client.BaseClient

start()

Starts the client by activating the component.

TornadoClient

class headstock.client.TornadoClient(jid, password, hostname='localhost', port=5222, tls=False, registercls=None)

Bases: headstock.client.BaseClient

run(start_loop=True)

Starts the client.

start_loop True - flag indicating if the ioloop.IOLoop.start() method should be called too.