# `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.