hdi::core::InternetPOST Class Reference

Allows for the creation of simple HTTP(S) POST clients to post to, and acquire data from, a given URL. More...

#include <hdicoreInternetPOST.h>

Public Member Functions
	InternetPOST (const std::string &url_, const DictionaryPref &data_)
	Creates a synchronous (blocking) InternetPOST object to perform HTTP(S) POST requests, in a "send and forget" fashion.
	InternetPOST (const std::string &url_, const DictionaryPref &data_, const Callback &success_, const Callback &failure_)
	Creates a synchronous (blocking) InternetPOST object to perform HTTP(S) POST requests.
virtual	~InternetPOST ()
	Destructs an InternetPOST object.
virtual bool	asynchronous () const
	Gets whether the target object is asynchronous (i.e. executes in a background thread)
virtual void	run ()
	Starts the POST request.
virtual bool	running () const
	Gets whether the POST request is currently running.
virtual std::string	content () const
	Gets the content acquired via the POST request.
virtual InternetError	errorCode () const
	Gets a translated platform error code, if possible, that was received by the implementation.
virtual int32_t	platformErrorCode () const
	Gets the raw platform error code that was received by the implementation.
virtual std::string	error () const
	Gets an error description if the POST request failed.

Static Public Member Functions
static InternetPOST *	Async (const std::string &url_, const DictionaryPref &data_)
	Creates an asynchronous (non-blocking) InternetPOST object to perform HTTP(S) POST requests.
static InternetPOST *	Async (const std::string &url_, const DictionaryPref &data_, const Callback &success_, const Callback &failure_)
	Creates an asynchronous (non-blocking) InternetPOST object to perform HTTP(S) POST requests.

Detailed Description

Allows for the creation of simple HTTP(S) POST clients to post to, and acquire data from, a given URL.

Constructor & Destructor Documentation

InternetPOST() [1/2]

hdi::core::InternetPOST::InternetPOST	(	const std::string &	url_,
		const DictionaryPref &	data_
	)

Creates a synchronous (blocking) InternetPOST object to perform HTTP(S) POST requests, in a "send and forget" fashion.

Author

GW

Date

09/2019

Parameters

url_	HTTP(S) URL to read, as UTF-8
data_	Dictionary of data to be JSON-encoded and sent to url_; root-level members of the dictionary will be used as individual POST arguments, and the member values will be individually JSON-encoded as POST argument values

Warning

As this method doesn't take any callback arguments, the request will simply be sent and the caller will never be notified of it finishing/failing.

InternetPOST() [2/2]

hdi::core::InternetPOST::InternetPOST	(	const std::string &	url_,
		const DictionaryPref &	data_,
		const Callback &	success_,
		const Callback &	failure_
	)

Creates a synchronous (blocking) InternetPOST object to perform HTTP(S) POST requests.

Author

GW

Date

08/2014

Parameters

url_	HTTP(S) URL to read, as UTF-8
data_	Dictionary of data to be JSON-encoded and sent to url_; root-level members of the dictionary will be used as individual POST arguments, and the member values will be individually JSON-encoded as POST argument values
success_	Callback to perform when the request completes successfully
failure_	Callback to perform when the request fails

~InternetPOST()

virtual hdi::core::InternetPOST::~InternetPOST ( )

virtual

Destructs an InternetPOST object.

Author

GW

Date

08/2014

Member Function Documentation

Async() [1/2]

static InternetPOST * hdi::core::InternetPOST::Async ( const std::string &  url_, const DictionaryPref &  data_  )

static

Creates an asynchronous (non-blocking) InternetPOST object to perform HTTP(S) POST requests.

Author

GW

Date

09/2019

Parameters

url_	HTTP(S) URL to read, as UTF-8
data_	Dictionary of data to be JSON-encoded and sent to url_; root-level members of the dictionary will be used as individual POST arguments, and the member values will be individually JSON-encoded as POST argument values

Warning

As this method doesn't take any callback arguments, the request will simply be sent and the caller will never be notified of it finishing/failing.

The responsibility for the memory of the returned InternetPOST pointer lies with the caller, and it must not be deleted until after either the success or failure callbacks are called.

Note

Asynchronous InternetPOST objects must be allocated using operator new and have several internal flags set (only synchronous InternetPOST objects can be allocated on the stack), which this function does automatically.

Async() [2/2]

static InternetPOST * hdi::core::InternetPOST::Async ( const std::string &  url_, const DictionaryPref &  data_, const Callback &  success_, const Callback &  failure_  )

static

Creates an asynchronous (non-blocking) InternetPOST object to perform HTTP(S) POST requests.

Author

GW

Date

08/2014

Parameters

url_	HTTP(S) URL to read, as UTF-8
data_	Dictionary of data to be JSON-encoded and sent to url_; root-level members of the dictionary will be used as individual POST arguments, and the member values will be individually JSON-encoded as POST argument values
success_	Callback to perform when the request completes successfully
failure_	Callback to perform when the request fails

Warning

The responsibility for the memory of the returned InternetPOST pointer lies with the caller, and it must not be deleted until after either the success or failure callbacks are called.

Note

Asynchronous InternetPOST objects must be allocated using operator new and have several internal flags set (only synchronous InternetPOST objects can be allocated on the stack), which this function does automatically.

The callbacks will not be called if their scheduling comes during or after plugin pre-shutdown (this would lead to a crash on quit).

asynchronous()

virtual bool hdi::core::InternetPOST::asynchronous ( ) const

virtual

Gets whether the target object is asynchronous (i.e. executes in a background thread)

Author

GW

Date

08/2014

Returns

true for asynchronous, false for synchronous

content()

virtual std::string hdi::core::InternetPOST::content ( ) const

virtual

Gets the content acquired via the POST request.

Author

GW

Date

08/2014

Returns

The resultant content of the network request, encoded in a string of bytes

Note

The std::string return type is slightly misleading; you are not limited to requesting string data. Requesting binary data is perfectly acceptable, as the std::string return type is merely a convenient container.

The results of this method are only valid when it is called from the "success" callback (see the InternetPOST constructor)

error()

virtual std::string hdi::core::InternetPOST::error ( ) const

virtual

Gets an error description if the POST request failed.

Author

GW

Date

08/2014

Returns

The resultant error of the request, as UTF-8

Note

The results of this method are only valid when it is called from the "failure" callback (see the InternetPOST constructor).

errorCode()

virtual InternetError hdi::core::InternetPOST::errorCode ( ) const

virtual

Gets a translated platform error code, if possible, that was received by the implementation.

Author

GW

Date

06/2017

Returns

The translated platform error code

Note

The results of this method are only valid when it is called from the "failure" callback (see the InternetGET constructor).

platformErrorCode()

virtual int32_t hdi::core::InternetPOST::platformErrorCode ( ) const

virtual

Gets the raw platform error code that was received by the implementation.

Author

GW

Date

06/2017

Returns

The translated platform error code

Note

See the file NSURLError.h on Mac, and WinINet.h on Windows, for a list of possible platform error codes.

The results of this method are only valid when it is called from the "failure" callback (see the InternetGET constructor).

run()

virtual void hdi::core::InternetPOST::run ( )

virtual

Starts the POST request.

Author

GW

Date

08/2014

running()

virtual bool hdi::core::InternetPOST::running ( ) const

virtual

Gets whether the POST request is currently running.

Author

GW

Date

08/2014

Returns

true if the request is running, false otherwise