The XML Stream

Events

feed	the XMLStream has just been fed with xml
open	the XMLStream is open
closed	the XMLStream has been closed
error	received a <stream:error></stream:error> from the server
unhandled_xml	the XMLStream failed to feed the incremental XML parser with the given value
node	a new xmpp.Node was just parsed by the stream and is available to use
iq	a new xmpp.IQ was node was received
message	a new xmpp.Message node was received
presence	a new xmpp.Presence node was received
start_stream	a new stream is being negotiated
start_tls	server sent <starttls />
tls_proceed	the peer allowed the TCP connection to upgrade to TLS
sasl_challenge	the peer sent a SASL challenge
sasl_success	the peer sent a SASL success
sasl_failure	the peer sent a SASL failure
sasl_response	the peer sent a SASL response
sasl_support	the peer says it supports SASL
bind_support	the peer says it supports binding resource
iq_result	the peer returned a <iq type-“result”></iq>
iq_set	the peer returned a <iq type-“set”></iq>
iq_get	the peer returned a <iq type-“get”></iq>
iq_error	the peer returned a <iq type-“error”></iq>
user_registration	the peer supports user registration
bound_jid	the peer returned a <jid>username@domain/resource</jid> that should be used in the from- of stanzas

API

class xmpp.stream.XMLStream(connection, debug=False)

XML Stream behavior class.

Parameters:

• connection – a XMPPConnection instance
• debug – whether to print errors to the stderr

add_contact(contact_jid, from_jid=None, groups=None)

adds a contact to the roster of the bound_jid or the provided from_jid parameter.

Automatically sends a <presence type="subscribe"> with a subsequent <iq type="set">.

Parameters:

• contact_jid – the jid to add in the roster
• from_jid – custom from= field to designate the owner of the roster
• groups – a list of strings with group names to categorize this contact in the roster

bind_to_resource(name)

sends an <iq type="set"><resource>name</resource></iq> in order to bind the resource

Parameters:name – the name of the resource

bound_jid

a JID or None

Automatically captured from the XML traffic.

close(disconnect=True)

sends a final </stream:stream> to the server then immediately closes the bound TCP connection,disposes it and resets the minimum state kept by the stream, so it can be reutilized right away.

feed(data, attempt=1)

feeds the stream with incoming data from the XMPP server. This is the basic entrypoint for usage with the XML received from the XMPPConnection

Parameters:data – the XML string

id

returns the stream id provided by the server. <stream:stream id="SOMETHING">

Mainly used by the authenticate() when crafting the secret.

load_extensions()

reloads all the available extensions bound to this stream

open_client(domain)

Sends a <stream:stream xmlns=”jabber:client”> to the given domain

Parameters:domain – the FQDN of the XMPP server

parse()

attempts to parse whatever is in the buffer of the incremental XML parser and creates a new parser.

ready_to_read(_, connection)

event handler for the on.ready_to_read event of a XMPP Connection.

You should probably never have to call this by hand, use bind() instead

ready_to_write(_, connection)

even handler for the on.ready_to_write event of a XMPP Connection.

You should probably never have to call this by hand, use bind() instead

reset()

resets the minimal state of the XML Stream, that is: * attributes of the <stream> sent by the server during negotiation, used by id() * a bound JID sent by the server * a successful sasl result node to leverage has_gone_through_sasl()

send(node)

sends a XML serialized Node through the bound XMPP connection

Parameters:node – the Node

send_message(message, to, **params)

Parameters:

• message – the string with the message
• to – the jid to send the message to
• **params –

  keyword args for designating attributes of the message

send_presence(to=None, delay=None, priority=10, **params)

sends presence

Parameters:

• to – jid to receive presence.
• delay – if set, it must be a ISO compatible date string
• priority – the priority of this resource

send_sasl_auth(mechanism, message)

sends a SASL response to the server in order to proceed with authentication handshakes

Parameters:mechanism – the name of SASL mechanism (i.e. SCRAM-SHA-1, PLAIN, EXTERNAL)

send_sasl_response(mechanism, message)

sends a SASL response to the server in order to proceed with authentication handshakes

Parameters:mechanism – the name of SASL mechanism (i.e. SCRAM-SHA-1, PLAIN, EXTERNAL)