carbons – Message Carbons (XEP-0280)

Message Carbons is an XMPP extension which allows an entity to receive copies of inbound and outbound messages received and sent by other resources of the same account. It is specified in XEP-0280. The goal of this feature is to allow users to have multiple devices which all have a consistent view on the messages sent and received.

This subpackage provides basic support for Message Carbons. It allows enabling and disabling the feature at the server side.

Service

class aioxmpp.CarbonsClient(client, *, logger_base=None, dependencies={}, service_order_index=0)

Provide an interface to enable and disable Message Carbons on the server side.

Note

This service deliberately does not provide a way to actually obtain sent or received carbonated messages.

The common way for a service to do this would be a stanza filter (see aioxmpp.stream.StanzaStream); however, in general the use and further distribution of carbonated messages highly depends on the application: it does, for example, not make sense to simply unwrap carbonated messages.

async enable()

Enable message carbons.

Raises

• RuntimeError – if the server does not support message carbons.

• aioxmpp.XMPPError – if the server responded with an error to the request.

Raises

as specified in aioxmpp.Client.send()

async disable()

Disable message carbons.

Raises

• RuntimeError – if the server does not support message carbons.

• aioxmpp.XMPPError – if the server responded with an error to the request.

Raises

as specified in aioxmpp.Client.send()

XSOs

aioxmpp.Message.xep0280_sent

On a Carbon message, this holds the Sent XSO which in turn holds the carbonated stanza.

aioxmpp.Message.xep0280_received

On a Carbon message, this holds the Received XSO which in turn holds the carbonated stanza.

class aioxmpp.carbons.xso.Received(*args, **kwargs)

Wrap a stanza which was received by another entity of the same account.

Received XSOs are available in Carbon messages at aioxmpp.Message.xep0280_received.

stanza

The wrapped stanza, usually a aioxmpp.Message.

Internally, this accesses the stanza attribute of forwarded. If forwarded is None, reading this attribute returns None. Writing to this attribute creates a new Forwarded object if necessary, but re-uses an existing object if available.

forwarded

The full Forwarded object which holds the received stanza.

class aioxmpp.carbons.xso.Sent(*args, **kwargs)

Wrap a stanza which was sent by another entity of the same account.

Sent XSOs are available in Carbon messages at aioxmpp.Message.xep0280_sent.

stanza

The wrapped stanza, usually a aioxmpp.Message.

Internally, this accesses the stanza attribute of forwarded. If forwarded is None, reading this attribute returns None. Writing to this attribute creates a new Forwarded object if necessary, but re-uses an existing object if available.

forwarded

The full Forwarded object which holds the sent stanza.