#include <carbons.h>

Inheritance diagram for Carbons:

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).

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 ) );

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() );
    }
  }
}

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

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

inlinevirtual

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 );
}

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:

Public Types

Public Member Functions

Detailed Description

Enable Mesage Carbons

Disable Message Carbons

Prevent carbon copies for a single message

Access received carbon copies

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ Carbons() [1/2]

◆ Carbons() [2/2]

◆ ~Carbons()

Member Function Documentation

◆ clone()

◆ embeddedStanza()

◆ embeddedTag()

◆ filterString()

◆ newInstance()

◆ tag()

◆ type()