PCL
pcl::NetworkTransfer Class Reference

Synchronous network transfers. More...

#include <NetworkTransfer.h>

+ Inheritance diagram for pcl::NetworkTransfer:

Public Types

typedef bool(Control::* download_event_handler) (NetworkTransfer &sender, const void *buffer, fsize_type size)
 
typedef bool(Control::* progress_event_handler) (NetworkTransfer &sender, fsize_type downloadTotal, fsize_type downloadCurrent, fsize_type uploadTotal, fsize_type uploadCurrent)
 
typedef fsize_type(Control::* upload_event_handler) (NetworkTransfer &sender, void *buffer, fsize_type maxSize)
 

Public Member Functions

 NetworkTransfer ()
 
 NetworkTransfer (const NetworkTransfer &)=delete
 
virtual ~NetworkTransfer ()
 
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
 
NetworkTransferoperator= (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 NetworkTransferNull ()
 
- Static Public Member Functions inherited from pcl::UIObject
static UIObjectNull ()
 

Additional Inherited Members

- Protected Member Functions inherited from pcl::UIObject
 UIObject ()=default
 
 UIObject (const UIObject &x)
 
 UIObject (UIObject &&x)
 
UIObjectoperator= (const UIObject &x)
 
UIObjectoperator= (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()

virtual pcl::NetworkTransfer::~NetworkTransfer ( )
inlinevirtual

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
secondsConnection 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
nlsHeadersA 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:

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
urlA valid URL identifying the proxy server used by this network transfer operation.
userNameThe user name for proxy authentication. The default value is an empty string.
userPasswordThe 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
useSSLEnable 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.
forceSSLIf 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.
verifyPeerVerify 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.
verifyHostVerify 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
urlA valid URL identifying the network resource of this network transfer operation.
userNameThe user name for authentication. The default value is an empty string.
userPasswordThe 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
mailFromThe 'return-to' email address.
mailRecipientsThe 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
uploadSizeThe 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: