Synchronous network transfers. More...

#include <NetworkTransfer.h>

Inheritance diagram for pcl::NetworkTransfer:

Public Types
using	download_event_handler = bool(Control::)(NetworkTransfer &sender, const void buffer, fsize_type size)

using	progress_event_handler = bool(Control::*)(NetworkTransfer &sender, fsize_type downloadTotal, fsize_type downloadCurrent, fsize_type uploadTotal, fsize_type uploadCurrent)

using	upload_event_handler = fsize_type(Control::)(NetworkTransfer &sender, void buffer, fsize_type maxSize)

Public Member Functions
	NetworkTransfer ()

	NetworkTransfer (const NetworkTransfer &)=delete

	~NetworkTransfer () override

fsize_type	BytesTransferred () const

void	CloseConnection ()

String	ContentType () const

String	CustomHTTPHeaders () const

bool	Download ()

void	EnsureUnique () override

String	ErrorInformation () const

void	OnDownloadDataAvailable (download_event_handler handler, Control &receiver)

void	OnTransferProgress (progress_event_handler handler, Control &receiver)

void	OnUploadDataRequested (upload_event_handler handler, Control &receiver)

	operator bool () const

NetworkTransfer &	operator= (const NetworkTransfer &)=delete

bool	PerformedOK () const

bool	POST (const String &fields)

String	ProxyURL () const

int	ResponseCode () const

void	SetConnectionTimeout (int seconds)

void	SetCustomHTTPHeaders (const String &nlsHeaders)

void	SetProxyURL (const String &url, const String &userName=String(), const String &userPassword=String())

void	SetSSL (bool useSSL=true, bool forceSSL=false, bool verifyPeer=true, bool verifyHost=true)

void	SetURL (const String &url, const String &userName=String(), const String &userPassword=String())

bool	SMTP (const String &mailFrom, const StringList &mailRecipients)

double	TotalSpeed () const

double	TotalTime () const

bool	Upload (fsize_type uploadSize=0)

String	URL () const

bool	WasAborted () const

Public Member Functions inherited from pcl::UIObject
virtual	~UIObject () noexcept(false)

bool	IsAlias () const

bool	IsGarbage () const

bool	IsNull () const

bool	IsSameObject (const UIObject &o) const

bool	IsUnique () const

String	ObjectId () const

IsoString	ObjectType () const

bool	operator< (const UIObject &o) const

bool	operator== (const UIObject &o) const

size_type	RefCount () const

void	SetObjectId (const String &id)

Static Public Member Functions
static NetworkTransfer &	Null ()

Static Public Member Functions inherited from pcl::UIObject
static UIObject &	Null ()

Additional Inherited Members
Protected Member Functions inherited from pcl::UIObject
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (UIObject &&x)

Detailed Description

NetworkTransfer is a simple network utility class with the following capabilities:

Synchronous download and upload network data transfers.

HTTP, FTP, SMTP, HTTPS, FTPS and SMTPS protocols supported.

Supports user authentication.

Event-driven operation with separate download, upload and progress event handlers.

Transparent reusable connections for maximum performance.

Thread-safe class.

Definition at line 89 of file NetworkTransfer.h.

Constructor & Destructor Documentation

◆ NetworkTransfer() [1/2]

pcl::NetworkTransfer::NetworkTransfer ( )

Constructs a default NetworkTransfer object.

◆ ~NetworkTransfer()

pcl::NetworkTransfer::~NetworkTransfer ( )

inlineoverride

Destroys this client-side instance and dereferences the server-side object. If the server-side object becomes unreferenced, it will be garbage-collected and eventually destroyed by the core application.

When the server-side object is destroyed, all active network connections are also closed automatically. See the CloseConnection() member function form more information.

Definition at line 107 of file NetworkTransfer.h.

◆ NetworkTransfer() [2/2]

pcl::NetworkTransfer::NetworkTransfer ( const NetworkTransfer & )

delete

Copy constructor. This constructor is disabled because NetworkTransfer represents unique server-side objects.

Member Function Documentation

◆ BytesTransferred()

fsize_type pcl::NetworkTransfer::BytesTransferred ( ) const

Returns the total number of bytes transferred in the last network operation performed with this object (whether successful or not).

◆ CloseConnection()

void pcl::NetworkTransfer::CloseConnection ( )

Closes the internal network connection associated with this object.

Normally, when you call one of the Download(), Upload(), POST() or SMTP() member functions for the first time with a NetworkTransfer object, the PixInsight core application does not close the network connection automatically after completing the operation. The connection remains active for some time, ready to be reused if the same NetworkTransfer object is used again to perform additional (and compatible) data transfers. This greatly improves performance of network transactions.

By calling this function you can force immediate close of the active connection. If there is no active connection associated with this object, this function is simply ignored. Note that the destructor of NetworkTransfer also closes any active connection automatically.

◆ ContentType()

String pcl::NetworkTransfer::ContentType ( ) const

The content type (or MIME type) reported by the remote server after a successful download operation, or an empty string if no valid content type could be retrieved, if the last operation was an upload, or if no transfer operation has been performed with this object.

◆ CustomHTTPHeaders()

String pcl::NetworkTransfer::CustomHTTPHeaders ( ) const

Returns the newline-separated list of custom HTTP headers defined for this object, or an empty string if no custom headers have been defined. Custom HTTP headers are defined by calling SetCustomHTTPHeaders().

◆ Download()

bool pcl::NetworkTransfer::Download ( )

Performs a data download operation.

Returns true upon successful completion of the download operation. Returns false in the event of error, or if the operation was aborted.

Note: Before invoking this function, a download event handler must be set by calling OnDownloadDataAvailable().

◆ EnsureUnique()

void pcl::NetworkTransfer::EnsureUnique ( )

inlineoverridevirtual

Ensures that the server-side object managed by this instance is uniquely referenced.

Since network transfers are unique objects by definition, calling this member function has no effect.

Reimplemented from pcl::UIObject.

Definition at line 130 of file NetworkTransfer.h.

◆ ErrorInformation()

String pcl::NetworkTransfer::ErrorInformation ( ) const

Returns the error information generated in the last network transfer operation. Returns an empty string if no error occurred, or if no transfer operation has been performed with this object.

Note that this function may return some useful diagnostics information, even if the last operation was successful.

◆ Null()

static NetworkTransfer& pcl::NetworkTransfer::Null ( )

static

Returns a reference to a null NetworkTransfer instance. A null NetworkTransfer does not correspond to an existing network transfer in the PixInsight core application.

◆ operator bool()

pcl::NetworkTransfer::operator bool ( ) const

inline

A synonym for PerformedOK()

Definition at line 414 of file NetworkTransfer.h.

◆ operator=()

NetworkTransfer& pcl::NetworkTransfer::operator= ( const NetworkTransfer & )

delete

Copy assignment. This operator is disabled because NetworkTransfer represents unique server-side objects.

◆ PerformedOK()

bool pcl::NetworkTransfer::PerformedOK ( ) const

Returns true if the last network transfer operation was successful; false in the event of error, if no transfer operation has been performed with this object, or if the last operation was aborted.

◆ POST()

bool pcl::NetworkTransfer::POST ( const String & fields )

Performs an HTTP POST operation.

Example:

NetworkTransfer transfer;
transfer.SetURL( "http://example-cars-info-site.com/" );
transfer.OnDownloadDataAvailable( GetCarInfo, receiver );
if ( !transfer.POST( "brand=Toyota&model=RAV4" ) )
   throw Error( "POST operation failed: " + transfer.ErrorInformation() );

Returns true upon successful completion of the POST operation. Returns false in the event of error, or if the operation has been aborted.

This member function performs a download operation. The downloaded data will be the server response to the POSTed fields.

Note: Before invoking this function, a download event handler must be set by calling OnDownloadDataAvailable().

◆ ProxyURL()

String pcl::NetworkTransfer::ProxyURL ( ) const

Returns the URL of the proxy server used in the last network transfer operation performed with this object, or an empty string if no proxy server has been specified.

Note: Proxy user authentication data (user name and password) will never be included in the URL returned by this function.

◆ ResponseCode()

int pcl::NetworkTransfer::ResponseCode ( ) const

Returns the server response code after the last call to Perform(). Returns zero if the response code could not be retrieved, or if no transfer operation has been done.

◆ SetConnectionTimeout()

void pcl::NetworkTransfer::SetConnectionTimeout ( int seconds )

Sets the connection timeout for this NetworkTransfer object.

Parameters

seconds Connection timeout in seconds. Can legally be zero to reset the connection timeout to its default value of 30 seconds.

If the specified timeout is not valid for some reason, or if an internal error occurs, this function throws an Error exception.

◆ SetCustomHTTPHeaders()

void pcl::NetworkTransfer::SetCustomHTTPHeaders ( const String & nlsHeaders )

Define a set of custom HTTP headers.

Parameters

nlsHeaders A newline-separated list of custom HTTP headers. To remove all custom headers and return to the default set of HTTP headers, specify an empty string.

The specified list of custom headers will replace any previously defined list, if one was set by calling this function.

To disable an HTTP header, specify an empty header value (no characters after the ':'). For example:

"User-Agent:"

To define a custom header without a value, include no ':' separator and end the header with a semicolon:

"CustomHeader;"

Example:

NetworkTransfer N;
N.SetURL( "http://foo-bar.com/" );
N.SetCustomHTTPHeaders( "Content-Type: text/plain\nMyCustomHeader: 1" );
N.OnUploadDataRequested( MyUploadDataFunc, receiver );
N.Upload();

◆ SetProxyURL()

void pcl::NetworkTransfer::SetProxyURL	(	const String &	url,
		const String &	userName = `String()`,
		const String &	userPassword = `String()`
	)

Sets the proxy URL of this NetworkTransfer object.

Parameters

url	A valid URL identifying the proxy server used by this network transfer operation.
userName	The user name for proxy authentication. The default value is an empty string.
userPassword	The user password for proxy authentication. The default value is an empty string.

The parameters used by this member function are identical to those of the SetURL() function.

If the specified URL is not syntactically valid, this function throws an Error exception. Existence or responsiveness of the proxy server are not verified.

◆ SetSSL()

void pcl::NetworkTransfer::SetSSL	(	bool	useSSL = `true`,
		bool	forceSSL = `false`,
		bool	verifyPeer = `true`,
		bool	verifyHost = `true`
	)

Set SSL/TLS options.

Parameters

useSSL	Enable SSL/TLS for the FTP, SMTP, POP3 and IMAP protocols. These are protocols that start plain text by default but can be restarted automatically using secure connections. The default value is true.
forceSSL	If true, SSL will be required for communication during the whole transfer operation; in this case, if SSL is not available the connection will fail. If this parameter is false, SSL/TLS will be used if available, but the operation will continue (insecurely) otherwise. The default value is false.
verifyPeer	Verify the authenticity of the peer's certificate, and fail if it is not authentic. The peer's certificate is checked through a chain of certification authority (CA) cerfificates supplied by the calling machine. If this parameter is false, the connection won't fail if the authenticity of the server's certificate cannot be verified. This parameter works for all TLS based protocols: HTTPS, FTPS, SMTPS, etc. The default value is true.
verifyHost	Verify the identity of the host. The connection will fail if the Common Name or Subject Alternate Name fields of the server's certificate don't match the host name in the URL set via the SetURL() member function. If this parameter is false, the connection won't fail if the identity of the server cannot be verified. This parameter works for all TLS based protocols: HTTPS, FTPS, SMTPS, etc. If the verifyPeer parameter is false, this parameter is ignored. The default value is true.

By default, all NetworkTransfer objects are initialized to use SSL/TLS if possible for plain text protocols. Authenticity of peer and host certificates are always verified by default. In other words, the default parameter values of this member function reflect the default state of the object upon construction.

If the specified SSL settings are not valid for some reason, or if an internal error occurs, this function throws an Error exception.

◆ SetURL()

void pcl::NetworkTransfer::SetURL	(	const String &	url,
		const String &	userName = `String()`,
		const String &	userPassword = `String()`
	)

Sets the URL of this NetworkTransfer object.

Parameters

url	A valid URL identifying the network resource of this network transfer operation.
userName	The user name for authentication. The default value is an empty string.
userPassword	The user password for authentication. The default value is an empty string.

URLs must be valid and conform to the URI specification from RFC 3986 (Uniform Resource Identifier: Generic Syntax). The HTTP, FTP, HTTPS, FTPS, SSH and SMTP protocols are supported.

The url may include user authentication data in the 'user:password@' format. It may also include a port specification. For example:

ftp://somebody:secretpwd@ftp.somewhere.com/mydir/myfile.txt:21

However, if explicit user name and password are specified, they will override any user authentication data included in the URL. In all cases, user authentication data will never be shown on the console.

If the specified URL is not syntactically valid, this function throws an Error exception. Existence or responsiveness of the server are not verified.

◆ SMTP()

bool pcl::NetworkTransfer::SMTP	(	const String &	mailFrom,
		const StringList &	mailRecipients
	)

Performs an SMTP operation.

Parameters

mailFrom	The 'return-to' email address.
mailRecipients	The list of recipients for this SMTP operation, usually a list of email addresses that will receive the transferred data as an email message.

Returns true upon successful completion of the SMTP operation. Returns false in the event of error, or if the operation has been aborted.

This member function performs an upload operation. The uploaded data will be the header and body of an email message. See RFC 5322 for detailed information on the data format applicable.

Note: Before invoking this function, an upload event handler must be set by calling OnUploadDataRequested().

◆ TotalSpeed()

double pcl::NetworkTransfer::TotalSpeed ( ) const

Returns the transfer speed in KiB per second, measured for the last network transfer operation performed with this object.

◆ TotalTime()

double pcl::NetworkTransfer::TotalTime ( ) const

Returns the total elapsed time in seconds, measured for the last network transfer operation performed with this object.

◆ Upload()

bool pcl::NetworkTransfer::Upload ( fsize_type uploadSize = 0 )

Performs a data upload operation.

Parameters

uploadSize The total size in bytes of the data that will be transferred. For example, if you are going to upload a disk file, you should specify the file size here. If the size cannot be known in advance, this argument can legally be zero. However, specifying the total upload size can improve uploading performance significantly. The default value is zero.

Returns true upon successful completion of the upload operation. Returns false in the event of error, or if the operation was aborted.

Note: Before invoking this function, an upload event handler must be set by calling OnUploadDataRequested().

◆ URL()

String pcl::NetworkTransfer::URL ( ) const

Returns the URL of the last network transfer operation performed with this object, or an empty string if no transfer operation has been done.

Note: User authentication data (user name and password) will never be included in the URL returned by this function.

◆ WasAborted()

bool pcl::NetworkTransfer::WasAborted ( ) const

Returns true iff the last network transfer operation was aborted by an event handler. Returns false if the operation was not aborted (whether successful or not), or if no transfer operation has been performed with this object.

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

NetworkTransfer.h

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ NetworkTransfer() [1/2]

◆ ~NetworkTransfer()

◆ NetworkTransfer() [2/2]

Member Function Documentation

◆ BytesTransferred()

◆ CloseConnection()

◆ ContentType()

◆ CustomHTTPHeaders()

◆ Download()

◆ EnsureUnique()

◆ ErrorInformation()

◆ Null()

◆ operator bool()

◆ operator=()

◆ PerformedOK()

◆ POST()

◆ ProxyURL()

◆ ResponseCode()

◆ SetConnectionTimeout()

◆ SetCustomHTTPHeaders()

◆ SetProxyURL()

◆ SetSSL()

◆ SetURL()

◆ SMTP()

◆ TotalSpeed()

◆ TotalTime()

◆ Upload()

◆ URL()

◆ WasAborted()