gloox  1.0.27
Public Types | Public Member Functions | List of all members
Carbons Class Reference

#include <carbons.h>

Inheritance diagram for Carbons:
Inheritance graph
[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 StanzaembeddedStanza () const
 
virtual TagembeddedTag () const
 
virtual const std::string & filterString () const
 
virtual StanzaExtensionnewInstance (const Tag *tag) const
 
virtual Tagtag () const
 
virtual StanzaExtensionclone () 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).
Carbons(Type type)
Definition: carbons.cpp:30
@ Set
Definition: iq.h:46
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 ) );

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:

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]

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

Parameters
typeThe 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
tagThe 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 );
}
virtual Tag * tag() const
Definition: carbons.cpp:86
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: