SIProfileFT Class Reference

`#include <siprofileft.h>`

Inheritance diagram for SIProfileFT:
[legend]

## Public Types

enum | StreamType { FTTypeS5B = 1 , FTTypeIBB = 2 , FTTypeOOB = 4 , FTTypeAll = 0xFF }

## Public Member Functions

| SIProfileFT (ClientBase *parent, SIProfileFTHandler *sipfth, SIManager *manager=0, SOCKS5BytestreamManager *s5Manager=0)
virtual | ~SIProfileFT ()
const std::string | requestFT (const JID &to, const std::string &name, long size, const std::string &hash=EmptyString, const std::string &desc=EmptyString, const std::string &date=EmptyString, const std::string &mimetype=EmptyString, int streamTypes=FTTypeAll, const JID &from=JID(), const std::string &sid=EmptyString)
void | acceptFT (const JID &to, const std::string &sid, StreamType type=FTTypeS5B, const JID &from=JID())
void | declineFT (const JID &to, const std::string &sid, SIManager::SIError reason, const std::string &text=EmptyString)
void | cancel (Bytestream *bs)
void | dispose (Bytestream *bs)
void | registerSIProfileFTHandler (SIProfileFTHandler *sipfth)
void | removeSIProfileFTHandler ()
void | setStreamHosts (StreamHostList hosts)
void | addStreamHost (const JID &jid, const std::string &host, int port)
void | registerSOCKS5BytestreamServer (SOCKS5BytestreamServer *server)
void | removeSOCKS5BytestreamServer ()
virtual void | handleSIRequest (const JID &from, const JID &to, const std::string &id, const SIManager::SI &si)
virtual void | handleSIRequestResult (const JID &from, const JID &to, const std::string &sid, const SIManager::SI &si)
virtual void | handleSIRequestError (const IQ &iq, const std::string &sid)
virtual void | handleIncomingBytestreamRequest (const std::string &sid, const JID &from)
virtual void | handleIncomingBytestream (Bytestream *bs)
virtual void | handleOutgoingBytestream (Bytestream *bs)
virtual void | handleBytestreamError (const IQ &iq, const std::string &sid)
virtual bool | handleIq (const IQ &iq)
virtual void | handleIqID (const IQ &iq, int context)
Public Member Functions inherited from SIProfileHandler
virtual | ~SIProfileHandler ()
Public Member Functions inherited from SIHandler
virtual | ~SIHandler ()
Public Member Functions inherited from BytestreamHandler
virtual | ~BytestreamHandler ()
Public Member Functions inherited from IqHandler
virtual | ~IqHandler ()

## Detailed Description

An implementation of the file transfer SI profile (XEP-0096).

An SIProfileFT object acts as a 'plugin' to the SIManager. SIProfileFT manages most of the file transfer functionality. The naming comes from the fact that File Transfer (FT) is a profile of Stream Initiation (SI).

Usage:

Create a new SIProfileFT object. It needs a ClientBase -derived object (e.g. Client) as well as a SIProfileFTHandler -derived object that will receive file transfer-related events. If you already use SI and the SIManager somewhere else, you should pass a pointer to that SIManager object as third parameter to SIProfileFT's constructor.

class MyFileTransferHandler : public SIProfileFTHandler
{
// ...
};
Client* client = new Client( ... );
// ...
MyFileTransferHandler* mh = new MyFileTransferHandler( ... );
SIProfileFT* ft = new SIProfileFT( client, mh );
gloox::Client
This class implements a basic Jabber/XMPP Client.
Definition client.h:117
gloox::SIProfileFTHandler
An abstract base class to handle file transfer (FT) requests.
Definition siprofilefthandler.h:37
gloox::SIProfileFT
An implementation of the file transfer SI profile (XEP-0096).
Definition siprofileft.h:152
gloox::SIProfileFT::SIProfileFT
SIProfileFT(ClientBase *parent, SIProfileFTHandler *sipfth, SIManager *manager=0, SOCKS5BytestreamManager *s5Manager=0)
Definition siprofileft.cpp:31

You are now, basically, ready to send and receive files.

A couple of notes:

- There are two (actually two and a half) possible "techniques" to transfer files using SI. The first is using a peer-to-peer SOCKS5 bytestream, optionally via a (special) SOCKS5 proxy. The second techniques is using an in-band bytestream, i.e. the data is encapsulated in XMPP stanzas and sent through the server.

- To be able to send files using the former method (SOCKS5 bytestreams), you may need access to a SOCKS5 bytestream proxy (called StreamHost). This is especially true if either or both of sender and receiver are behind NATs or are otherwise blocked from establishing direct TCP connections. You should use Disco to query a potential SOCKS5 proxy for its host and port parameters and feed that information into SIProfileFT:
  ft->addStreamHost( JID( "proxy.server.dom" ), "101.102.103.104", 6677 );
  gloox::JID
  An abstraction of a JID.
  Definition jid.h:31
  gloox::SIProfileFT::addStreamHost
  void addStreamHost(const JID &jid, const std::string &host, int port)
  Definition siprofileft.cpp:176
  You should not hard-code this information (esp. host/IP and port) into your app since the proxy may go down occasionally or vanish completely.

- In addition to (or even instead of) using external SOCKS5 proxies, you can use a SOCKS5BytestreamServer object that gloox provides:
  SOCKS5BytestreamServer* server = new SOCKS5BytestreamServer( client->logInstance(), 1234 );
  if( server->listen() != ConnNoError )
  printf( "port in use\n" );
  ft->addStreamHost( client->jid(), my_ip, 1234 );
  ft->registerSOCKS5BytestreamServer( server );
  gloox::ClientBase::logInstance
  LogSink & logInstance()
  Definition clientbase.h:599
  gloox::ClientBase::jid
  const JID & jid()
  Definition clientbase.h:147
  gloox::SIProfileFT::registerSOCKS5BytestreamServer
  void registerSOCKS5BytestreamServer(SOCKS5BytestreamServer *server)
  Definition siprofileft.h:283
  gloox::SOCKS5BytestreamServer
  A server listening for SOCKS5 bytestreams.
  Definition socks5bytestreamserver.h:37
  gloox::SOCKS5BytestreamServer::listen
  ConnectionError listen()
  Definition socks5bytestreamserver.cpp:43
  gloox::ConnNoError
  @ ConnNoError
  Definition gloox.h:685
  This listening server should then be integrated into your mainloop to have its recv() method called from time to time. It is safe to put the server into its own thread.

- When you finally receive a Bytestream via the SIProfileFTHandler, you will need to integrate this bytestream with your mainloop, or put it into a separate thread (if occasional blocking is not acceptable). You will need to call connect() on that Bytestream. For SOCKS5 bytestreams, this function will try to connect to each of the given StreamHosts and block until it has established a connection with one of them (or until all attempts failed). Further, if you want to receive a file via the bytestream, you will have to call recv() on the object from time to time. For in-band bytestreams, connect() will send an "open the bytestream" request to the contact.

- For both stream types, BytestreamDataHandler::handleBytestreamOpen() will announce the established bytestream. The stream then is ready to send and receive data.

- In general, both types of streams can be handled equally, i.e. there's no need to know whether the underlying stream really is a SOCKS5Bytestream or an InBandBytestream. Bytestream::type() tells anyway. Note, however, that sending large amounts of data using in-band bytestreams may trigger rate limiting in some servers.

- If you e.g. told Client to connect through a HTTP proxy or a SOCKS5 proxy , or any other ConnectionBase -derived method, or even chains thereof, SIProfileFT will use the same connection types with the same configuration to connect to the Stream Host/SOCKS5 proxy. If this is inappropriate because you have e.g. a local SOCKS5 proxy inside your local network, use SOCKS5Bytestream::setConnectionImpl() to override the above default connection(s).

- Do not delete Bytestream objects manually. Use dispose() instead.

- When using the Client's JID as the first argument to addStreamHost() as in the code snippet above, make sure the JID is actually a full JID. If you let the server pick a resource, the call to Client::jid() needs to be made after the connection has been established and authenticated, because only then Client knows its full JID. This is generally a good idea, since the server may choose to change the resource, even if you provided one at login.

- The interal SOCKS5BytestreamServer will obviously not work across NATs.

- Using addStreamHost(), you can add as many potential StreamHosts as you like. However, you should add the best options (e.g. the local SOCKS5BytestreamServer) first.

When cleaning up, delete the objectes you created above in the opposite order of creation:

delete server
delete ft;
delete client;

For usage examples see src/examples/ft_send.cpp and src/examples/ft_recv.cpp.

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

Since
  0.9

Definition at line 150 of file siprofileft.h.

## Member Enumeration Documentation

## StreamType

enum StreamType

Supported stream types.

Enumerator
FTTypeS5B | SOCKS5 Bytestreams.
FTTypeIBB | In-Band Bytestreams.
FTTypeOOB | Out-of-Band Data.
FTTypeAll | All types.

Definition at line 157 of file siprofileft.h.

## Constructor & Destructor Documentation

## SIProfileFT()

SIProfileFT | ( | ClientBase * | parent,
|  | SIProfileFTHandler * | sipfth,
|  | SIManager * | manager = 0,
|  | SOCKS5BytestreamManager * | s5Manager = 0 )

Constructor.

Parameters

  parent | The ClientBase to use for signaling.
  sipfth | The SIProfileFTHandler to receive events.
  manager | An optional SIManager to register with. If this is zero, SIProfileFT will create its own SIManager. You should pass a valid SIManager here if you are already using one with the `parent` ClientBase above.
  s5Manager | An optional SOCKS5BytestreamManager to use. If this is zero, SIProfileFT will create its own SOCKS5BytestreamManager. You should pass a valid SOCKS5BytestreamManager here if you are already using one with the `parent` ClientBase above.

Note
  If you passed a SIManager and/or SOCKS5BytestreamManager and/or InBandBytestreamManager to SIProfileFT's constructor, these objects will not be deleted on desctruction of SIProfileFT.

Definition at line 31 of file siprofileft.cpp.

## ~SIProfileFT()

~SIProfileFT | ( |  | ) |

virtual

Virtual destructor.

Definition at line 52 of file siprofileft.cpp.

## Member Function Documentation

## acceptFT()

void acceptFT | ( | const JID & | to,
|  | const std::string & | sid,
|  | StreamType | type = FTTypeS5B,
|  | const JID & | from = JID() )

Call this function to accept a file transfer request previously announced by means of SIProfileFTHandler::handleFTRequest() .

Parameters

  to | The requestor.
  sid | The request's sid, as passed to SIProfileHandler::handleFTRequest().
  type | The desired stream type to use for this file transfer. Defaults to SOCKS5 Bytestream. You should not use `FTTypeAll` here.
  from | An optional 'from' address to stamp outgoing stanzas with. Used in component scenario only. Defaults to empty JID.

Definition at line 98 of file siprofileft.cpp.

## addStreamHost()

void addStreamHost | ( | const JID & | jid,
|  | const std::string & | host,
|  | int | port )

Adds one StreamHost to the list of SOCKS5 StreamHosts.

Parameters

  jid | The StreamHost's JID.
  host | The StreamHost's hostname.
  port | The StreamHost's port.

Definition at line 176 of file siprofileft.cpp.

## cancel()

void cancel | ( | Bytestream * | bs | ) |

Cancels the given bytestream. Most useful for SOCKS5 bytestreams where no proxies could be found. The given Bytestream will be deleted.

Parameters

  bs | The Bytestream to cancel.

Note
  Can also be used with IBB.

Definition at line 156 of file siprofileft.cpp.

## declineFT()

void declineFT | ( | const JID & | to,
|  | const std::string & | sid,
|  | SIManager::SIError | reason,
|  | const std::string & | text = EmptyString )

Call this function to decline a FT request previously announced by means of SIProfileFTHandler::handleFTRequest() .

Parameters

  to | The requestor.
  sid | The request's sid, as passed to SIProfileFTHandler::handleFTRequest().
  reason | The reason for the reject.
  text | An optional human-readable text explaining the decline.

Definition at line 136 of file siprofileft.cpp.

## dispose()

void dispose | ( | Bytestream * | bs | ) |

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

Parameters

  bs | The bytestream to dispose. It will be deleted here.

Definition at line 145 of file siprofileft.cpp.

## handleBytestreamError()

void handleBytestreamError | ( | const IQ & | iq,
|  | const std::string & | sid )

virtual

Notifies the handler of errors occuring when a bytestream was requested. For example, if the remote entity does not implement SOCKS5 bytestreams.

Parameters

  iq | The error stanza.
  sid | The request's SID.

Implements BytestreamHandler.

Definition at line 306 of file siprofileft.cpp.

## handleIncomingBytestream()

void handleIncomingBytestream | ( | Bytestream * | bs | ) |

virtual

Notifies the implementor of a new incoming bytestream. The bytestream is not yet ready to send data. To initialize the bytestream and to prepare it for data transfer, register a BytestreamDataHandler with it and call its connect() method. To not block your application while the data transfer lasts, you most likely want to put the bytestream into its own thread or process (before calling connect() on it). It is safe to do so without additional synchronization. When you are finished using the bytestream, use SIProfileFT::dispose() to get rid of it.

Parameters

  bs | The bytestream.

Implements BytestreamHandler.

Definition at line 294 of file siprofileft.cpp.

## handleIncomingBytestreamRequest()

void handleIncomingBytestreamRequest | ( | const std::string & | sid,
|  | const JID & | from )

virtual

Notifies the implementor of a new incoming bytestream request. You have to call either BytestreamManager::acceptBytestream() or BytestreamManager::rejectBytestream(), to accept or reject the bytestream request, respectively.

Parameters

  sid | The bytestream's id, to be passed to BytestreamManager::acceptBytestream() and BytestreamManager::rejectBytestream(), respectively.
  from | The remote initiator of the bytestream request.

Implements BytestreamHandler.

Definition at line 288 of file siprofileft.cpp.

## handleIq()

virtual bool handleIq | ( | const IQ & | iq | ) |

inline virtual

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

Parameters

  iq | The complete IQ stanza.

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

Since
  1.0

Implements IqHandler.

Definition at line 316 of file siprofileft.h.

## handleIqID()

void handleIqID | ( | const IQ & | iq,
|  | 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 empty positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.

Parameters

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

Note
  Only IQ stanzas of type 'result' or 'error' can arrive here.

Since
  1.0

Implements IqHandler.

Definition at line 271 of file siprofileft.cpp.

## handleOutgoingBytestream()

void handleOutgoingBytestream | ( | Bytestream * | bs | ) |

virtual

Notifies the implementor of successful establishing of an outgoing bytestream request. The stream has been accepted by the remote entity and is ready to send data. The BytestreamHandler does not become the owner of the Bytestream object. Use SIProfileFT::dispose() to get rid of the bytestream object after it has been closed.

Parameters

  bs | The new bytestream.

Implements BytestreamHandler.

Definition at line 300 of file siprofileft.cpp.

## handleSIRequest()

void handleSIRequest | ( | const JID & | from,
|  | const JID & | to,
|  | const std::string & | id,
|  | const SIManager::SI & | si )

virtual

This function is called to handle incoming SI requests, i.e. a remote entity requested a stream to send a file to you. You should use either SIManager::acceptSI() or SIManager::declineSI() to accept or reject the request, respectively.

Parameters

  from | The SI requestor.
  to | The SI recipient, usually oneself. Used in component scenario.
  id | The request's id (not the stream's id). This id MUST be supplied to either SIManager::acceptSI() or SIManager::declineSI().
  si | The request's complete SI.

Implements SIProfileHandler.

Definition at line 182 of file siprofileft.cpp.

## handleSIRequestError()

void handleSIRequestError | ( | const IQ & | iq,
|  | const std::string & | sid )

virtual

This function is called to handle a request error or decline.

Parameters

  iq | The complete error stanza.
  sid | The request's SID.

Implements SIHandler.

Definition at line 282 of file siprofileft.cpp.

## handleSIRequestResult()

void handleSIRequestResult | ( | const JID & | from,
|  | const JID & | to,
|  | const std::string & | sid,
|  | const SIManager::SI & | si )

virtual

This function is called to handle results of outgoing SI requests, i.e. you requested a stream (using SIManager::requestSI()) to send a file to a remote entity.

Parameters

  from | The remote SI receiver.
  to | The SI requestor. Usually oneself. Used in component scenario.
  sid | The stream ID.
  si | The request's complete SI.

Implements SIHandler.

Definition at line 228 of file siprofileft.cpp.

## registerSIProfileFTHandler()

void registerSIProfileFTHandler | ( | SIProfileFTHandler * | sipfth | ) |

inline

Registers a handler that will be informed about incoming file transfer requests, i.e. when a remote entity wishes to send a file.

Parameters

  sipfth | A SIProfileFTHandler to register. Only one handler can be registered at any one time.

Definition at line 256 of file siprofileft.h.

## registerSOCKS5BytestreamServer()

void registerSOCKS5BytestreamServer | ( | SOCKS5BytestreamServer * | server | ) |

inline

Tells the interal SOCKS5BytestreamManager which SOCKS5BytestreamServer handles peer-2-peer SOCKS5 bytestreams.

Parameters

  server | The SOCKS5BytestreamServer to use.

Definition at line 283 of file siprofileft.h.

## removeSIProfileFTHandler()

void removeSIProfileFTHandler | ( |  | ) |

inline

Removes the previously registered file transfer request handler.

Definition at line 261 of file siprofileft.h.

## removeSOCKS5BytestreamServer()

void removeSOCKS5BytestreamServer | ( |  | ) |

inline

Un-registers any local SOCKS5BytestreamServer.

Definition at line 289 of file siprofileft.h.

## requestFT()

const std::string requestFT | ( | const JID & | to,
|  | const std::string & | name,
|  | long | size,
|  | const std::string & | hash = EmptyString,
|  | const std::string & | desc = EmptyString,
|  | const std::string & | date = EmptyString,
|  | const std::string & | mimetype = EmptyString,
|  | int | streamTypes = FTTypeAll,
|  | const JID & | from = JID(),
|  | const std::string & | sid = EmptyString )

Starts negotiating a file transfer with a remote entity.

Parameters

  to | The entity to send the file to. Must be a full JID.
  name | The file's name. Mandatory and must not be empty.
  size | The file's size. Mandatory and must be > 0.
  hash | The file content's MD5 hash.
  desc | A description.
  date | The file's last modification date/time. See XEP-0082 for details.
  mimetype | The file's mime-type. Defaults to 'binary/octet-stream' if empty.
  streamTypes | ORed StreamType that can be used for this transfer.
  from | An optional 'from' address to stamp outgoing requests with. Used in component scenario only. Defaults to empty JID.
  sid | Optionally specify a stream ID (SID). If empty, one will be generated.

Returns
  The requested stream's ID (SID). Empty if conditions above (file name, size) are not met.

Definition at line 63 of file siprofileft.cpp.

## setStreamHosts()

void setStreamHosts | ( | StreamHostList | hosts | ) |

Sets a list of StreamHosts that will be used for subsequent SOCKS5 bytestream requests.

Note
  At least one StreamHost is required.

Parameters

  hosts | A list of StreamHosts.

Definition at line 170 of file siprofileft.cpp.

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

- siprofileft.h
- siprofileft.cpp