#include <inbandbytestreammanager.h>

Inheritance diagram for InBandBytestreamManager:

Collaboration diagram for InBandBytestreamManager:

Public Member Functions
GLOOX_DEPRECATED_CTOR	InBandBytestreamManager (ClientBase *parent)
virtual	~InBandBytestreamManager ()
bool	requestInBandBytestream (const JID &to, InBandBytestreamHandler *ibbh, const std::string &sid="")
void	setBlockSize (int blockSize)
int	blockSize () const
bool	dispose (InBandBytestream *ibb)
void	acceptInBandBytestream (InBandBytestream *ibb)
void	rejectInBandBytestream (InBandBytestream *ibb)
void	registerInBandBytestreamHandler (InBandBytestreamHandler *ibbh, bool sync=true)
void	removeInBandBytestreamHandler ()
virtual bool	handleIq (Stanza *stanza)
virtual bool	handleIqID (Stanza *stanza, int context)
Public Member Functions inherited from IqHandler
virtual	~IqHandler ()

Detailed Description

An InBandBytestreamManager dispatches In-Band Bytestreams.

Initiating a bytestream

To initiate a new bytestream, you need an InBandBytestreamManager object. You will also need an InBandBytestreamHandler-derived object which will receive incoming and outgoing bytestreams (not the data but the InBandBytestream objects).

class MyClass : public InBandBytestreamHandler
{
  ...
  private:
    InBandBytestreamManager *m_ibbManager;
  ...
};

Create a new InBandBytestreamManager and request a new bytestream:

MyClass::MyClass()
{
  m_ibbManager = new InBandBytestreamManager( m_client );
}
void MyClass::myFunc()
{
  JID jid( "entity@server/resource" );
  m_ibbManager->requestInBandBytestream( jid, this );
}

After the bytestream has been negotiated with the peer, InBandBytestreamHandler::handleOutgoingInBandBytestream() is called. Here you should attach the bytestream to a MessageSession associated with the remote entity. This is necessary since message stanzas are used for the actual data exchange and the MessageSession class offers a convenient interface to filter these out. In this example, there is a map of JID/MessageSession pairs and a map of JID/InBandBytestreams.

void MyClass::handleOutgoingInBandBytestream( const JID& to, InBandBytestream *ibb )
{
  MessageSessionList::iterator it = m_messageSessions.find( to.full() );
  if( it != m_messageSessions.end() )
  {
    ibb->attachTo( (*it).second );
  }
  else
  {
    MessageSession *session = new MessageSession( m_client, to );
    ibb->attachTo( session );
    m_messageSessions[to.full()] = session;
  }
  m_ibbs[to.full()] = ibb;
}

If you want to receive data from the bytestream (In-Band Bytestreams can be bi-directional), you have to register a InBandBytestreamDataHandler here, similar to the folowing example.

When sending data you should make sure you never try to send a block larger than the negotiated blocksize (which defaults to 4096 bytes). If a block is larger than this it will not be sent.

Receiving a bytestream

To receive a bytestream you need a InBandBytestreamManager, too, and you have to register an InBandBytestreamHandler which will receive the incoming bytestreams.

m_ibbManager->registerInBandBytestreamHandler( this );

Upon an incoming request the InBandBytestreamManager notifies the registered InBandBytestreamHandler by calling handleIncomingInBandBytestream() . The return value of the handler determines whether the stream shall be accepted or not.

bool MyClass::handleIncomingInBandBytestream( const JID& from, InBandBytestream *ibb )
{
  // Check whether you want to accept the bytestream
  // add an InBandBytestreamDataHandler
  ibb->registerInBandBytestreamDataHandler( this );
  // The rest of this function probaly looks similar to the implementation of
  // handleOutgoingInBandBytestream() above.
  // You should *not* start to send blocks of data from within this
  // function, though.
  // return true to accept the bytestream, false to reject it
  return true;
}

Sending data

To actually send data, you should utilise some kind of mainloop integration that allows to call a function periodically. It is important to remember the following:

chunks of data passed to InBandBytestream::sendBlock() may not exceed the negotiated block-size
neither InBandBytestreamManager nor InBandBytestream will ask for data to send.

The following is an example of a primitive mainloop integration:

void MyClass::mainloop()
{
  if( m_client->connect(false) )
  {
    ConnectionError ce = ConnNoError;
    while( ce == ConnNoError )
    {
      ce = m_client->recv();
      sendIBBData();
    }
    printf( "disconnected. reason: %d\n", ce );
  }
}

In sendIBBData() you would then iterate over your bytestreams and send a block of data where appropriate.

void MyClass::sendIBBData()
{
  IBBList::iterator it = m_ibbs.begin();
  for( ; it != m_ibbs.end(); ++it )
  {
    (*it).second->sendBlock( "some data" );
  }
}

Getting rid of bytestreams

When you're done with a bytestream you can get rid of it by calling the dispose() function. The bytestream will be recycled and you should no longer use it.

m_ibbManager->dispose( ibb );

ibb = 0;

Note: You should have only one InBandBytestreamManager per Client/ClientBase lying around. One is enough for receiving and initiating bytestreams.; In the excerpts above, only one bytestream per remote entity is possible (without leaking). However, gloox in general does not impose such a limitation, nor does the In-Band Bytestreams specification.

Author: Jakob Schroeter js@ca.nosp@m.maya.nosp@m..net

Since: 0.8

Deprecated:: Functionality will be merged with SI-based file transfer (SIProfileFT). InBandBytestreamManager will go away in 1.0.

Definition at line 179 of file inbandbytestreammanager.h.

Constructor & Destructor Documentation

InBandBytestreamManager ( ClientBase * parent )

Constructs a new InBandBytestreamManager.

Parameters

parent The ClientBase to use for sending data.

Deprecated:: Functionality will be merged with SI-based file transfer (SIProfileFT). InBandBytestreamManager will go away in 1.0.

Definition at line 23 of file inbandbytestreammanager.cpp.

~InBandBytestreamManager ( )

virtual

Virtual destructor.

Definition at line 34 of file inbandbytestreammanager.cpp.

Member Function Documentation

void acceptInBandBytestream ( InBandBytestream * ibb )

When using asynchronous InBandBytestream notifications (if you used registerInBandBytestreamHandler() with a second argument of true) you have to call either this function or rejectInBandBytestream() after receiving an InBandBytestream from the InBandBytestreamHandler. Else the initiator will never know whether the request was actually received.

Parameters

ibb	The InBandBytestream (as received from InBandBytestreamHandler) to accept.

Since: 0.8.1

Definition at line 134 of file inbandbytestreammanager.cpp.

int blockSize ( ) const

inline

Returns the currently set block-size.

Returns: The currently set block-size.

Definition at line 221 of file inbandbytestreammanager.h.

bool dispose ( InBandBytestream * ibb )

To get rid of a bytestream (i.e., close and delete it), call this function. You should not use the bytestream any more. The remote entity will be notified about the closing of the stream.

Parameters

ibb	The bytestream to dispose. It will be deleted here.

Definition at line 225 of file inbandbytestreammanager.cpp.

bool handleIq ( Stanza * stanza )

virtual

Reimplement this function if you want to be notified about incoming IQs.

Parameters

stanza The complete Stanza.

Returns: Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, a 'error' will be sent.

Implements IqHandler.

Definition at line 77 of file inbandbytestreammanager.cpp.

bool handleIqID	(	Stanza *	stanza,
		int	context
	)

virtual

Reimplement this function if you want to be notified about incoming IQs with a specific value of the id attribute. You have to enable tracking of those IDs using Client::trackID(). This is usually useful for IDs that generate a positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.

Parameters

stanza	The complete Stanza.
context	A value to restore context, stored with ClientBase::trackID().

Returns: Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, a 'error' will be sent.

Implements IqHandler.

Definition at line 187 of file inbandbytestreammanager.cpp.

void registerInBandBytestreamHandler	(	InBandBytestreamHandler *	ibbh,
		bool	sync = `true`
	)

Use this function to register an object that will receive new incoming bytestream requests from the InBandBytestreamManager. Only one InBandBytestreamHandler can be registered at any one time.

Parameters

ibbh	The InBandBytestreamHandler derived object to receive notifications.
sync	Whether incoming bytestrams shall be announced syncronously. Default: true (syncronous)

Definition at line 238 of file inbandbytestreammanager.cpp.

void rejectInBandBytestream ( InBandBytestream * ibb )

When using asynchronous InBandBytestream notifications (if you used registerInBandBytestreamHandler() with a second argument of true) you have to call either this function or acceptInBandBytestream() after receiving an InBandBytestream from the InBandBytestreamHandler. Else the initiator will never know whether the request was actually received.

Parameters

ibb	The InBandBytestream (as received from InBandBytestreamHandler) to reject.

Since: 0.8.1

Definition at line 147 of file inbandbytestreammanager.cpp.

void removeInBandBytestreamHandler ( )

Removes the registered InBandBytestreamHandler.

Definition at line 245 of file inbandbytestreammanager.cpp.

bool requestInBandBytestream	(	const JID &	to,
		InBandBytestreamHandler *	ibbh,
		const std::string &	sid = `""`
	)

This function initiates opening of a bytestream with the MessageSession's remote entity. Data can only be sent over an open stream. Use isOpen() to find out what the stream's current state is. However, successful opening/initiation will be announced by means of the InBandBytestreamHandler interface. Multiple bytestreams (even per JID) can be initiated without waiting for success.

Parameters

to	The recipient of the requested bytestream.
ibbh	The InBandBytestreamHandler to send the new bytestream to.
sid	The bytestream's stream ID, if previously negotiated e.g. using SI (XEP-0095).

Returns: False in case of an error, true otherwise. A return value of true does not indicate that the bytestream has been opened. This is announced by means of the InBandBytestreamHandler.

Definition at line 50 of file inbandbytestreammanager.cpp.

void setBlockSize ( int blockSize )

inline

Sets the default block-size. Default: 4096

Parameters

blockSize The default block-size in byte.

Definition at line 215 of file inbandbytestreammanager.h.

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

Public Member Functions

Detailed Description

Initiating a bytestream

Receiving a bytestream

Sending data

Getting rid of bytestreams

Constructor & Destructor Documentation

Member Function Documentation