#include <siprofileft.h>

Inheritance diagram for SIProfileFT:

Collaboration diagram for SIProfileFT:

Public Types
enum	StreamType { FTTypeS5B = 1 }

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="", const std::string &desc="", const std::string &date="", const std::string &mimetype="")
void	acceptFT (const JID &to, const std::string &id, StreamType type=FTTypeS5B)
void	declineFT (const JID &to, const std::string &id, SIManager::SIError reason, const std::string &text="")
void	setRangedTransfers (bool ranged)
void	dispose (SOCKS5Bytestream *s5b)
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 std::string &id, const std::string &profile, Tag si, Tag ptag, Tag *fneg)
virtual void	handleSIRequestResult (const JID &from, const std::string &sid, Tag si, Tag ptag, Tag *fneg)
virtual void	handleSIRequestError (Stanza *stanza, const std::string &sid)
virtual void	handleIncomingSOCKS5BytestreamRequest (const std::string &sid, const JID &from)
virtual void	handleIncomingSOCKS5Bytestream (SOCKS5Bytestream *s5b)
virtual void	handleOutgoingSOCKS5Bytestream (SOCKS5Bytestream *s5b)
virtual void	handleSOCKS5BytestreamError (Stanza *stanza, const std::string &sid)
Public Member Functions inherited from SIProfileHandler
virtual	~SIProfileHandler ()
Public Member Functions inherited from SIHandler
virtual	~SIHandler ()
Public Member Functions inherited from SOCKS5BytestreamHandler
virtual	~SOCKS5BytestreamHandler ()

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.

Usage:

Create a new SIProfileFT object. It needs a ClientBase -derived object as well as a SIProfileFTHandler -derived object that will receive file transfer-related events. The naming comes from the fact that File Transfer (FT) is a profile of Stream Initiation (SI). 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:

To be able to send files, you will need access to a SOCKS5 bytestream proxy (called StreamHost)(not an ordinary SOCKS5 proxy). You should use Disco to query it for its host and port and feed that information into SIProfileFT:
ft->addStreamHost( JID( "proxy.server.dom" ), "101.102.103.104", 6677 );

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.

When you finally receive a SOCKS5Bytestream 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 SOCKS5Bytestream::connect() . connect() will try to connect to each of the given StreamHosts and block until it has established a connection with one of the 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.

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 a SOCKS5Bytestream manually. Use dispose() instead.

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

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

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

Since: 0.9

Definition at line 125 of file siprofileft.h.

Member Enumeration Documentation

enum StreamType

Supported stream types.

Enumerator:

FTTypeS5B

SOCKS5 Bytestreams.

Definition at line 131 of file siprofileft.h.

Constructor & Destructor Documentation

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 to SIProfileFT's constructor, these objects will not be deleted on desctruction of SIProfileFT.

Definition at line 27 of file siprofileft.cpp.

~SIProfileFT ( )

virtual

Virtual destructor.

Definition at line 47 of file siprofileft.cpp.

Member Function Documentation

void acceptFT	(	const JID &	to,
		const std::string &	id,
		StreamType	type = `FTTypeS5B`
	)

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

Parameters

to	The requestor.
id	The request's id, as passed to SIProfileHandler::handleFTRequest().
type	The desired stream type to use for this file transfer. Defaults to SOCKS5 Bytestream.

Definition at line 91 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

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

Definition at line 138 of file siprofileft.cpp.

void declineFT	(	const JID &	to,
		const std::string &	id,
		SIManager::SIError	reason,
		const std::string &	text = `""`
	)

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

Parameters

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

Definition at line 117 of file siprofileft.cpp.

void dispose ( SOCKS5Bytestream * s5b )

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

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

Definition at line 126 of file siprofileft.cpp.

void handleIncomingSOCKS5Bytestream ( SOCKS5Bytestream * s5b )

virtual

Notifies the implementor of a new incoming SOCKS5 bytestream. The bytestream is not yet ready to send data. To initialize the bytestream and to prepare it for data transfer, register a SOCKS5BytestreamDataHandler 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() (or SOCKS5BytestreamManager::dispose() if you use SOCKS5BytestreamManager directly) to get rid of it.

Parameters

s5b	The bytestream.

Implements SOCKS5BytestreamHandler.

Definition at line 204 of file siprofileft.cpp.

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

virtual

Notifies the implementor of a new incoming SOCKS5 request. You have to call either SOCKS5BytestreamManager::acceptSOCKS5Bytestream() or SOCKS5BytestreamManager::rejectSOCKS5Bytestream(), to accept or reject the bytestream request, respectively.

Parameters

sid	The bytestream's id, to be passed to SOCKS5BytestreamManager::acceptSOCKS5Bytestream() and SOCKS5BytestreamManager::rejectSOCKS5Bytestream(), respectively.
from	The remote initiator of the bytestream request.

Implements SOCKS5BytestreamHandler.

Definition at line 198 of file siprofileft.cpp.

void handleOutgoingSOCKS5Bytestream ( SOCKS5Bytestream * s5b )

virtual

Notifies the implementor of successful establishing of an outgoing SOCKS5 bytestream request. The stream has been accepted by the remote entity and is ready to send data. The SOCKS5BytestreamHandler does not become the owner of the SOCKS5Bytestream object. Use SIProfileFT::dispose() (or SOCKS5BytestreamManager::dispose() if you use SOCKS5BytestreamManager directly) to get rid of the bytestream object after it has been closed.

Parameters

s5b	The new bytestream.

Implements SOCKS5BytestreamHandler.

Definition at line 210 of file siprofileft.cpp.

void handleSIRequest	(	const JID &	from,
		const std::string &	id,
		const std::string &	profile,
		Tag *	si,
		Tag *	ptag,
		Tag *	fneg
	)

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.
id	The request's id (not the stream's id). This id MUST be supplied to either SIManager::acceptSI() or SIManager::declineSI().
profile	The requested stream profile.
si	The request's complete <si/> Tag.
ptag	The profile-specific child of the SI request. May be 0, but should not be.
fneg	The <feature/> child of the SI request. May be 0.

Implements SIProfileHandler.

Definition at line 144 of file siprofileft.cpp.

void handleSIRequestError	(	Stanza *	stanza,
		const std::string &	sid
	)

virtual

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

Parameters

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

Implements SIHandler.

Definition at line 192 of file siprofileft.cpp.

void handleSIRequestResult	(	const JID &	from,
		const std::string &	sid,
		Tag *	si,
		Tag *	ptag,
		Tag *	fneg
	)

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 SI receiver.
sid	The stream ID.
si	The request's complete <si/> Tag.
ptag	The profile-specific child of the SI request. May be 0.
fneg	The <feature/> child of the SI request. May be 0 (but should not be).

Implements SIHandler.

Definition at line 173 of file siprofileft.cpp.

void handleSOCKS5BytestreamError	(	Stanza *	stanza,
		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

stanza The error stanza.

Implements SOCKS5BytestreamHandler.

Definition at line 216 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

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

Definition at line 217 of file siprofileft.h.

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 244 of file siprofileft.h.

void removeSIProfileFTHandler ( )

inline

Removes the previously registered file transfer request handler.

Definition at line 222 of file siprofileft.h.

void removeSOCKS5BytestreamServer ( )

inline

Un-registers any local SOCKS5BytestreamServer.

Definition at line 250 of file siprofileft.h.

const std::string requestFT	(	const JID &	to,
		const std::string &	name,
		long	size,
		const std::string &	hash = `""`,
		const std::string &	desc = `""`,
		const std::string &	date = `""`,
		const std::string &	mimetype = `""`
	)

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.

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

Definition at line 58 of file siprofileft.cpp.

void setRangedTransfers ( bool ranged )

inline

Enables or disables offering of ranged file transfers. This is off by default.

Parameters

ranged True if you want to support ranged transfers, false otherwise.

Definition at line 201 of file siprofileft.h.

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 132 of file siprofileft.cpp.

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

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation