gloox  1.1-svn
Public Types | Public Member Functions | List of all members
SIProfileFT Class Reference

#include <siprofileft.h>

Inheritance diagram for SIProfileFT:
Inheritance graph
[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 );

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

A couple of notes:

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 Schroeter js@ca.nosp@m.maya.nosp@m..net
Since
0.9

Definition at line 150 of file siprofileft.h.

Member Enumeration Documentation

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 ( ClientBase parent,
SIProfileFTHandler sipfth,
SIManager manager = 0,
SOCKS5BytestreamManager s5Manager = 0 
)

Constructor.

Parameters
parentThe ClientBase to use for signaling.
sipfthThe SIProfileFTHandler to receive events.
managerAn 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.
s5ManagerAn 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 ( )
virtual

Virtual destructor.

Definition at line 52 of file siprofileft.cpp.

Member Function Documentation

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
toThe requestor.
sidThe request's sid, as passed to SIProfileHandler::handleFTRequest().
typeThe desired stream type to use for this file transfer. Defaults to SOCKS5 Bytestream. You should not use FTTypeAll here.
fromAn 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.

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

Adds one StreamHost to the list of SOCKS5 StreamHosts.

Parameters
jidThe StreamHost's JID.
hostThe StreamHost's hostname.
portThe StreamHost's port.

Definition at line 176 of file siprofileft.cpp.

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
bsThe Bytestream to cancel.
Note
Can also be used with IBB.

Definition at line 156 of file siprofileft.cpp.

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
toThe requestor.
sidThe request's sid, as passed to SIProfileFTHandler::handleFTRequest().
reasonThe reason for the reject.
textAn optional human-readable text explaining the decline.

Definition at line 136 of file siprofileft.cpp.

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
bsThe bytestream to dispose. It will be deleted here.

Definition at line 145 of file siprofileft.cpp.

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
iqThe error stanza.
sidThe request's SID.

Implements BytestreamHandler.

Definition at line 306 of file siprofileft.cpp.

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
bsThe bytestream.

Implements BytestreamHandler.

Definition at line 294 of file siprofileft.cpp.

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
sidThe bytestream's id, to be passed to BytestreamManager::acceptBytestream() and BytestreamManager::rejectBytestream(), respectively.
fromThe remote initiator of the bytestream request.

Implements BytestreamHandler.

Definition at line 288 of file siprofileft.cpp.

virtual bool handleIq ( const IQ iq)
inlinevirtual

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

Parameters
iqThe 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, a 'error' will be sent.
Since
1.0

Implements IqHandler.

Definition at line 316 of file siprofileft.h.

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

Parameters
iqThe complete IQ stanza.
contextA 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.

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
bsThe new bytestream.

Implements BytestreamHandler.

Definition at line 300 of file siprofileft.cpp.

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
fromThe SI requestor.
toThe SI recipient, usually oneself. Used in component scenario.
idThe request's id (not the stream's id). This id MUST be supplied to either SIManager::acceptSI() or SIManager::declineSI().
siThe request's complete SI.

Implements SIProfileHandler.

Definition at line 182 of file siprofileft.cpp.

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

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

Parameters
iqThe complete error stanza.
sidThe request's SID.

Implements SIHandler.

Definition at line 282 of file siprofileft.cpp.

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
fromThe remote SI receiver.
toThe SI requestor. Usually oneself. Used in component scenario.
sidThe stream ID.
siThe request's complete SI.

Implements SIHandler.

Definition at line 228 of file siprofileft.cpp.

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
sipfthA SIProfileFTHandler to register. Only one handler can be registered at any one time.

Definition at line 256 of file siprofileft.h.

void registerSOCKS5BytestreamServer ( SOCKS5BytestreamServer server)
inline

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

Parameters
serverThe SOCKS5BytestreamServer to use.

Definition at line 283 of file siprofileft.h.

void removeSIProfileFTHandler ( )
inline

Removes the previously registered file transfer request handler.

Definition at line 261 of file siprofileft.h.

void removeSOCKS5BytestreamServer ( )
inline

Un-registers any local SOCKS5BytestreamServer.

Definition at line 289 of file siprofileft.h.

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
toThe entity to send the file to. Must be a full JID.
nameThe file's name. Mandatory and must not be empty.
sizeThe file's size. Mandatory and must be > 0.
hashThe file content's MD5 hash.
descA description.
dateThe file's last modification date/time. See XEP-0082 for details.
mimetypeThe file's mime-type. Defaults to 'binary/octet-stream' if empty.
streamTypesORed StreamType that can be used for this transfer.
fromAn optional 'from' address to stamp outgoing requests with. Used in component scenario only. Defaults to empty JID.
sidOptionally 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.

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
hostsA list of StreamHosts.

Definition at line 170 of file siprofileft.cpp.


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