Carbons Class Reference

`#include <carbons.h>`

Inheritance diagram for Carbons:
[legend]

## Public Types

enum | Type { Received , Sent , Enable , Disable , Private , Invalid }

## Public Member Functions

| Carbons (Type type)
| Carbons (const Tag *tag=0)
virtual | ~Carbons ()
Type | type () const
virtual Stanza * | embeddedStanza () const
virtual Tag * | embeddedTag () const
virtual const std::string & | filterString () const
virtual StanzaExtension * | newInstance (const Tag *tag) const
virtual Tag * | tag () const
virtual StanzaExtension * | clone () const
Public Member Functions inherited from StanzaExtension
| StanzaExtension (int type)
virtual | ~StanzaExtension ()
int | extensionType () const

## Detailed Description

An implementation of Message Carbons (XEP-0280) as a StanzaExtension.

# Enable Mesage Carbons

Before using Message Carbons you have to check your server for support of the extension. You can do so using Disco::getDiscoInfo(). You can check the result (in DiscoHandler::handleDiscoInfo()) for a feature of `XMLNS_MESSAGE_CARBONS` (use Disco::Info::hasFeature()).

If the feature exists, you can enable Message Carbons with the server.

Client cb( ... );
// ...
// setup
cb.registerStanzaExtension( new Forward() ); // required for Message Carbons support
cb.registerStanzaExtension( new Carbons() );
// ...
// enable Message Carbons
IQ iq( IQ::Set, JID() ); // empty JID
iq.addExtension( new Carbons( Carbons::Enable ) );
cb.send( iq, MyIqHandler, 1 ); // myIqHandler will be notified of the result with the given context ('1' in this case).
gloox::Carbons::Enable
@ Enable
Definition carbons.h:126
gloox::Carbons::Carbons
Carbons(Type type)
Definition carbons.cpp:30
gloox::Client
This class implements a basic Jabber/XMPP Client.
Definition client.h:117
gloox::Forward
This is an implementation of Stanza Forwarding (XEP-0297) as a StanzaExtension.
Definition forward.h:41
gloox::IQ
An abstraction of an IQ stanza.
Definition iq.h:34
gloox::IQ::Set
@ Set
Definition iq.h:46
gloox::JID
An abstraction of a JID.
Definition jid.h:31

Note
  Once enabled, the server will automatically send all received and sent messages of type `Chat` to all other Carbons-enabled resources of the current account. You have to make sure that you actually send messages of type `Chat`. The default is currently `Normal`.

# Disable Message Carbons

Once enabled, you can easily disable Message carbons. The code is almost identical to the code used to enable the feature, except that you use a Carbons::Type of Carbons::Disable when you add the Carbons extension to the IQ:

iq.addExtension( new Carbons( Carbons::Disable ) );
gloox::Carbons::Disable
@ Disable
Definition carbons.h:127

# Prevent carbon copies for a single message

To disable carbon copies for a single message, add a Carbons extension of type Private:

Message msg( Message::Chat, ... );
// ...
msg.addExtension( new Carbons( Carbons::Private ) );
gloox::Carbons::Private
@ Private
Definition carbons.h:128
gloox::Message
An abstraction of a message stanza.
Definition message.h:34
gloox::Message::Chat
@ Chat
Definition message.h:46

The server will not copy this message to your other connected resources.

# Access received carbon copies

When receiving a message (sent by either another connected client of the current user, or by a 3rd party), a carbon copy will have the following characteristics:

- The message's `from` attribute will be the bare JID of the receiving entity.
- The message's `from` attribute will be the full JID of the receiving entity.
- The message contains a Carbons StanzaExtension. This extension contains the original message with the original `from/to` attributes.

Some sample code:

bool Myclass::handleMessage( const Message& msg, MessageSession* )
{
if( msg.hasEmbeddedStanza() ) // optional, saves some processing time when there is no Carbons extension
{
const Carbons* carbon = msg.findExtension<const Carbons>( ExtCarbons );
if( carbon && carbon->embeddedStanza() )
{
Message* embeddedMessage = static_cast<Message *>( carbon->embeddedStanza() );
}
}
}
gloox::Carbons::embeddedStanza
virtual Stanza * embeddedStanza() const
Definition carbons.cpp:70
gloox::MessageSession
An abstraction of a message session between any two entities.
Definition messagesession.h:146
gloox::Stanza::hasEmbeddedStanza
bool hasEmbeddedStanza() const
Definition stanza.h:135
gloox::Stanza::findExtension
const StanzaExtension * findExtension(int type) const
Definition stanza.cpp:57
gloox::ExtCarbons
@ ExtCarbons
Definition stanzaextension.h:91

You can also determine whether a carbon was sent by a 3rd party or a different client of the current user by checking the return value of Carbons::type().

Carbons* c = msg.findExtension<...>( ... );
// check that c is valid
if( c->type() == Carbons::Received )
// Message was sent by a 3rd party
else if( c->type() == Carbons::Sent )
// Message was sent by a different client of the current user
gloox::Carbons::Sent
@ Sent
Definition carbons.h:125
gloox::Carbons::Received
@ Received
Definition carbons.h:124
gloox::Carbons::type
Type type() const
Definition carbons.h:154

XEP Version: 0.8

Author
  Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  1.0.5

Definition at line 116 of file carbons.h.

## Member Enumeration Documentation

## Type

enum Type

The types of Message Carbons stanza extensions.

Enumerator
Received | Indicates that the message received has been sent by a third party.
Sent | Indicates that the message received has been sent by one of the user's own resources.
Enable | Indicates that the sender wishes to enable carbon copies.
Disable | Indicates that the sender wishes to disable carbon copies.
Private | Indicates that the sender does not want carbon copies to be sent for this message.
Invalid | Invalid type.

Definition at line 122 of file carbons.h.

## Constructor & Destructor Documentation

## Carbons() [1/2]

Carbons | ( | Carbons::Type | type | ) |

Constructs a new Carbons instance of the given type. You should only use the `Enable`, `Disable` and `Private` types.

Parameters

  type | The Carbons type to create.

Definition at line 30 of file carbons.cpp.

## Carbons() [2/2]

Carbons | ( | const Tag * | tag = 0 | ) |

Constructs a new Carbons instance from the given tag.

Parameters

  tag | The Tag to create the Carbons instance from.

Definition at line 35 of file carbons.cpp.

## ~Carbons()

~Carbons | ( |  | ) |

virtual

Virtual destructor.

Definition at line 59 of file carbons.cpp.

## Member Function Documentation

## clone()

StanzaExtension * clone | ( |  | ) | const

virtual

Returns an identical copy of the current StanzaExtension.

Returns
  An identical copy of the current StanzaExtension.

Implements StanzaExtension.

Definition at line 98 of file carbons.cpp.

## embeddedStanza()

Stanza * embeddedStanza | ( |  | ) | const

virtual

This function returns the embedded Stanza, if any. You only have to reimplement it if your protocol flow contains embedded Stanzas.

Returns
  The embedded Stanza. May be 0.

Reimplemented from StanzaExtension.

Definition at line 70 of file carbons.cpp.

## embeddedTag()

Tag * embeddedTag | ( |  | ) | const

virtual

This function returns the embedded Tag that the embedded Stanza is based on, if any. You only have to reimplement it if your protocol flow contains embedded Stanzas.

Returns
  The embedded Tag. May be 0.

Reimplemented from StanzaExtension.

Definition at line 78 of file carbons.cpp.

## filterString()

const std::string & filterString | ( |  | ) | const

virtual

Returns an XPath expression that describes a path to child elements of a stanza that an extension handles.

Returns
  The extension's filter string.

Implements StanzaExtension.

Definition at line 64 of file carbons.cpp.

## newInstance()

virtual StanzaExtension * newInstance | ( | const Tag * | tag | ) | const

inline virtual

Returns a new Instance of the derived type. Usually, for a derived class FooExtension, the implementation of this function looks like:

StanzaExtension* FooExtension::newInstance( const Tag* tag ) const
{
return new FooExtension( tag );
}
gloox::Carbons::tag
virtual Tag * tag() const
Definition carbons.cpp:86
gloox::StanzaExtension::StanzaExtension
StanzaExtension(int type)
Definition stanzaextension.h:211
gloox::Tag
This is an abstraction of an XML element.
Definition tag.h:47

Returns
  The derived extension's new instance.

Implements StanzaExtension.

Definition at line 166 of file carbons.h.

## tag()

Tag * tag | ( |  | ) | const

virtual

Returns a Tag representation of the extension.

Returns
  A Tag representation of the extension.

Implements StanzaExtension.

Definition at line 86 of file carbons.cpp.

## type()

Type type | ( |  | ) | const

inline

Returns the current instance's type.

Returns
  The intance's type.

Definition at line 154 of file carbons.h.

The documentation for this class was generated from the following files:

- carbons.h
- carbons.cpp