Perform a simple Web request (HTTP, HTTPS, FTP). More...

#include <tsWebRequest.h>

Inheritance diagram for ts::WebRequest:

[legend]

Collaboration diagram for ts::WebRequest:

[legend]

Public Member Functions
	WebRequest (Report *report, bool non_blocking=false)
	Constructor.

	WebRequest (ReporterBase *delegate, bool non_blocking=false)
	Constructor.

virtual	~WebRequest () override
	Destructor.

void	abort ()
	Abort a transfer in progress.

size_t	announcedContentSize () const
	Get the announced content size in bytes.

void	clearPostData ()
	Clear previous POST data.

void	clearRequestHeaders ()
	Clear all headers which will be sent with the request.

bool	close ()
	Close the transfer.

size_t	contentSize () const
	Get the size in bytes of the downloaded content.

bool	deleteCookiesFile () const
	Delete the cookies file, if one was defined.

void	deleteRequestHeader (const UString &name)
	Delete all headers with a given name.

void	disableCookies ()
	Disable the use of cookies for all requests.

bool	downloadBinaryContent (const UString &url, ByteBlock &data, size_t chunk_size=DEFAULT_CHUNK_SIZE)
	Download the content of the URL as binary data in one operation.

bool	downloadFile (const UString &url, const fs::path &file_name, size_t chunk_size=DEFAULT_CHUNK_SIZE)
	Download the content of the URL in a file in one operation.

bool	downloadTextContent (const UString &url, UString &text, size_t chunk_size=DEFAULT_CHUNK_SIZE)
	Download the content of the URL as text in one operation.

void	enableCompression (bool on=true)
	Enable compression.

void	enableCookies (const fs::path &file_name=fs::path())
	Enable the use of cookies for all requests using this instance.

UString	finalURL () const
	Get the final URL of the actual download operation.

fs::path	getCookiesFileName () const
	Get the file name to use for cookies for all requests using this instance.

SysHandleType	getHandle () const
	Get the underlying file descriptor or device handle.

virtual SysHandleType	getReadHandle () const
	Get the underlying file descriptor or device handle for read operations.

SysSocketType	getReadSocket () const
	Get the underlying file descriptor or device handle as a system socket handle for read operations.

void	getResponseHeaders (UStringToUStringMultiMap &headers) const
	Get all response headers.

SysSocketType	getSocket () const
	Get the underlying file descriptor or device handle as a system socket handle.

virtual SysHandleType	getWriteHandle () const
	Get the underlying file descriptor or device handle for write operations.

SysSocketType	getWriteSocket () const
	Get the underlying file descriptor or device handle as a system socket handle for write operations.

bool	httpClientError () const
	Check if the HTTP status code indicates a client error.

bool	httpServerError () const
	Check if the HTTP status code indicates a server error.

int	httpStatus () const
	Get the HTTP status code (200, 404, etc).

bool	httpSuccess () const
	Check if the HTTP status code indicates success.

bool	isNonBlocking () const
	Check if the device is in non-blocking mode.

bool	isOpen () const
	Check if a transfer is open.

bool	isSupportedByReactor (bool recheck=false)
	Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

UString	mimeType (bool simple=true, bool lowercase=true) const
	Get the MIME type in the response headers.

bool	muteReport (bool mute)
	Temporarily mute the associated report.

bool	open (const UString &url, IOSB *iosb=nullptr)
	Open an URL and start the transfer.

UString	originalURL () const
	Get the original URL, as set by setURL().

const UString &	proxyHost () const
	Get the current actual proxy host.

const UString &	proxyPassword () const
	Get the current actual proxy user password.

uint16_t	proxyPort () const
	Get the current actual proxy port number.

const UString &	proxyUser () const
	Get the current actual proxy user name.

bool	receive (void buffer, size_t max_size, size_t &ret_size, IOSB iosb=nullptr)
	Receive data.

UString	reponseHeader (const UString &name) const
	Get the value of one header.

virtual Report &	report () const override
	Access the Report which is associated with this object.

const UStringToUStringMultiMap &	responseHeaders () const
	Get all response headers.

void	setArgs (const WebRequestArgs &args)
	Set various arguments from command line.

void	setAutoRedirect (bool on)
	Enable or disable the automatic redirection of HTTP requests.

void	setConnectionTimeout (cn::milliseconds timeout)
	Set the connection timeout for this request.

void	setInsecure (bool on=true)
	Enable or disable HTTPS security (certificate validation).

bool	setNonBlocking (bool non_blocking)
	Set the device in non-blocking mode.

void	setPostData (const ByteBlock &data)
	Set data to POST.

void	setPostData (const UString &data, const UString content_type=u"text/plain; charset=utf-8")
	Set data to POST.

void	setProxyHost (const UString &host, uint16_t port)
	Set the optional proxy host and port for this request.

void	setProxyUser (const UString &user, const UString &password)
	Set the optional proxy authentication for this request.

void	setReceiveTimeout (cn::milliseconds timeout)
	Set the timeout for each receive operation.

Report *	setReport (Report *report)
	Associate this object with another Report to log errors.

ReporterBase *	setReport (ReporterBase *delegate)
	Associate this object with another ReporterBase to log errors.

void	setRequestHeader (const UString &name, const UString &value)
	Set a header which will be sent with the request.

void	setUserAgent (const UString &name=UString())
	Set the user agent name to use in HTTP headers.

const UString &	userAgent () const
	Get the current user agent name to use in HTTP headers.

Static Public Member Functions
static UString	GetLibraryVersion ()
	Get the version of the underlying HTTP library.

static bool	IsPendingStatus (int error_code)
	This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

static void	SetDefaultProxyHost (const UString &host, uint16_t port)
	Set the default proxy host and port for all subsequent requests.

static void	SetDefaultProxyUser (const UString &user, const UString &password)
	Set the default proxy authentication for all subsequent requests.

static int	SilentLevel (bool silent, int default_severity=Severity::Error)
	Compute a log severity level from a "silent" parameter.

Static Public Attributes
static constexpr size_t	DEFAULT_CHUNK_SIZE = 64 * 1024
	Default download chunk size for bulk transfers.

static constexpr uint16_t	DEFAULT_HTTP_PORT = 80
	Default TCP port for HTTP.

static constexpr uint16_t	DEFAULT_HTTPS_PORT = 443
	Default TCP port for HTTPS.

static constexpr const UChar *	DEFAULT_USER_AGENT = u"tsduck"
	Default user agent string ("tsduck").

Protected Member Functions
virtual bool	allowSetNonBlocking () const
	Check that the non-blocking mode can be set.

bool	checkNonBlocking (bool non_blocking, const UChar *opname)
	Check the blocking mode of a device.

bool	checkNonBlocking (IOSB iosb, const UChar opname)
	Check the blocking mode of a device.

int	genericSystemRead (void addr, size_t max_size, size_t &ret_size, const AbortInterface abort, Device::IOSB *iosb, uint64_t position)
	Generic system read operation.

int	genericSystemWrite (const void addr, size_t size, size_t &written_size, Device::IOSB iosb, uint64_t position)
	Generic system write operation.

bool	setSystemNonBlocking (bool non_blocking)
	Low-level method to set the system file or socket descriptor in non-blocking mode.

Detailed Description

Perform a simple Web request (HTTP, HTTPS, FTP).

On UNIX systems, the implementation uses libcurl. On Windows systems, the implementation uses Microsoft Wininet. We could have used libcurl on Windows but building it was a pain...

The proxy and transfer settings must be set before starting any download operation. The HTTP status and the response headers are available after a successful download start.

By default, no proxy is used. If no proxy is set, the default proxy is used (system configuration on Windows, http_proxy environment on Unix systems).

Constructor & Destructor Documentation

◆ WebRequest() [1/2]

ts::WebRequest::WebRequest	(	Report *	report,
		bool	non_blocking = `false`
	)

explicit

Constructor.

Parameters

[in]	report	Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.
[in]	non_blocking	It true, the Web request is initially set in non-blocking mode.

◆ WebRequest() [2/2]

ts::WebRequest::WebRequest	(	ReporterBase *	delegate,
		bool	non_blocking = `false`
	)

explicit

Constructor.

Parameters

[in]	delegate	Use the report of another ReporterBase. If delegate is null, log messages are discarded.
[in]	non_blocking	It true, the Web request is initially set in non-blocking mode.

Member Function Documentation

◆ setConnectionTimeout()

void ts::WebRequest::setConnectionTimeout ( cn::milliseconds timeout )

inline

Set the connection timeout for this request.

Parameters

[in] timeout Connection timeout in milliseconds.

◆ setReceiveTimeout()

void ts::WebRequest::setReceiveTimeout ( cn::milliseconds timeout )

inline

Set the timeout for each receive operation.

Parameters

[in] timeout Reception timeout in milliseconds.

◆ setProxyHost()

void ts::WebRequest::setProxyHost	(	const UString &	host,
		uint16_t	port
	)

Set the optional proxy host and port for this request.

Parameters

[in]	host	Proxy host name or address.
[in]	port	Proxy port number.

◆ setProxyUser()

void ts::WebRequest::setProxyUser	(	const UString &	user,
		const UString &	password
	)

Set the optional proxy authentication for this request.

Parameters

[in]	user	Proxy user name.
[in]	password	Proxy user's password.

◆ SetDefaultProxyHost()

static void ts::WebRequest::SetDefaultProxyHost	(	const UString &	host,
		uint16_t	port
	)

static

Set the default proxy host and port for all subsequent requests.

Parameters

[in]	host	Proxy host name or address.
[in]	port	Proxy port number.

◆ SetDefaultProxyUser()

static void ts::WebRequest::SetDefaultProxyUser	(	const UString &	user,
		const UString &	password
	)

static

Set the default proxy authentication for all subsequent requests.

Parameters

[in]	user	Proxy user name.
[in]	password	Proxy user's password.

◆ proxyHost()

const UString & ts::WebRequest::proxyHost ( ) const

Get the current actual proxy host.

Returns: A constant reference to the proxy host name.

◆ proxyPort()

uint16_t ts::WebRequest::proxyPort ( ) const

Get the current actual proxy port number.

Returns: The proxy port number.

◆ proxyUser()

const UString & ts::WebRequest::proxyUser ( ) const

Get the current actual proxy user name.

Returns: A constant reference to the proxy user name.

◆ proxyPassword()

const UString & ts::WebRequest::proxyPassword ( ) const

Get the current actual proxy user password.

Returns: A constant reference to the proxy user password.

◆ enableCookies()

void ts::WebRequest::enableCookies ( const fs::path & file_name = fs::path() )

Enable the use of cookies for all requests using this instance.

Parameters

[in] file_name The name of the file to use to load and store cookies. On Windows, there is an implicit per-user cookie repository and fileName is ignored. On Unix systems, this file is used to store and retrieve cookies in the libcurl format. When fileName is empty, use a temporary file name.

◆ disableCookies()

void ts::WebRequest::disableCookies ( )

Disable the use of cookies for all requests.

Cookies are initially disabled by default.

◆ getCookiesFileName()

fs::path ts::WebRequest::getCookiesFileName ( ) const

Get the file name to use for cookies for all requests using this instance.

On Linux, return the current cookie file name, possibly the name of a temporary file if EnableCookies() was called with an empty string.
On Windows, the cookie repository is defined per user. There is no specific per-application file and this method always report an empty string.
Returns
The cookie file name.

◆ deleteCookiesFile()

bool ts::WebRequest::deleteCookiesFile ( ) const

Delete the cookies file, if one was defined.

Returns: True on success, false on error.

◆ setUserAgent()

void ts::WebRequest::setUserAgent ( const UString & name = UString() )

inline

Set the user agent name to use in HTTP headers.

Parameters

[in] name The user agent name. If empty, DEFAULT_USER_AGENT is used.

◆ userAgent()

const UString & ts::WebRequest::userAgent ( ) const

inline

Get the current user agent name to use in HTTP headers.

Returns: A constant reference to the user agent name to use in HTTP headers.

◆ enableCompression()

void ts::WebRequest::enableCompression ( bool on = true )

inline

Enable compression.

Compression is disabled by default.

Parameters

[in] on Boolean setting compression on or off.

◆ setInsecure()

void ts::WebRequest::setInsecure ( bool on = true )

inline

Enable or disable HTTPS security (certificate validation).

Certificate validation is enabled by default.

Parameters

[in] on If true, disable certificate validation.

◆ setAutoRedirect()

void ts::WebRequest::setAutoRedirect ( bool on )

inline

Enable or disable the automatic redirection of HTTP requests.

This option is active by default.

Parameters

[in] on If true, allow automatic redirection of HTTP requests.

◆ setArgs()

void ts::WebRequest::setArgs ( const WebRequestArgs & args )

Set various arguments from command line.

Parameters

[in] args Command line arguments.

◆ setRequestHeader()

void ts::WebRequest::setRequestHeader	(	const UString &	name,
		const UString &	value
	)

Set a header which will be sent with the request.

If the same header already exists with another value, a new header is added.

Parameters

[in]	name	The header name.
[in]	value	The header value.

◆ deleteRequestHeader()

void ts::WebRequest::deleteRequestHeader ( const UString & name )

Delete all headers with a given name.

Parameters

[in] name The header name.

◆ setPostData() [1/2]

void ts::WebRequest::setPostData	(	const UString &	data,
		const UString	content_type = `u"text/plain; charset=utf-8"`
	)

Set data to POST.

The request will be a POST one.

Parameters

[in]	data	Text POST data. The text will be sent in UTF-8 format.
[in]	content_type	The content type to set in the request headers. The default "Content-Type" header is "text/plain; charset=utf-8", which is usually appropriate. When set to the empty string, no header is set.

◆ setPostData() [2/2]

void ts::WebRequest::setPostData ( const ByteBlock & data )

Set data to POST.

The request will be a POST one.

Parameters

[in] data Binary POST data.

◆ clearPostData()

void ts::WebRequest::clearPostData ( )

Clear previous POST data.

The request will be a GET one.

◆ open()

bool ts::WebRequest::open	(	const UString &	url,
		IOSB *	iosb = `nullptr`
	)

Open an URL and start the transfer.

For HTTP request, perform all redirections and get response headers.

Parameters

[in]	url	The complete URL to fetch.
[in,out]	iosb	Address of an IOSB structure. If non-null, the request must be in non-blocking mode. When null, the request must be in blocking mode (the default). See the description of IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error.

◆ isOpen()

bool ts::WebRequest::isOpen ( ) const

inline

Check if a transfer is open.

Returns: True if a transfer is open, false otherwise.

◆ httpStatus()

int ts::WebRequest::httpStatus ( ) const

inline

Get the HTTP status code (200, 404, etc).

Returns: The HTTP status code.

◆ httpSuccess()

bool ts::WebRequest::httpSuccess ( ) const

inline

Check if the HTTP status code indicates success.

The HTTP status codes are classified as follow (Wikipedia):

1xx informational response – the request was received, continuing process
2xx successful – the request was successfully received, understood, and accepted
3xx redirection – further action needs to be taken in order to complete the request
4xx client error – the request contains bad syntax or cannot be fulfilled
5xx server error – the server failed to fulfil an apparently valid request
Returns
True if the HTTP status code indicates success.

◆ httpClientError()

bool ts::WebRequest::httpClientError ( ) const

inline

Check if the HTTP status code indicates a client error.

Returns: True if the HTTP status code indicates a client error.

◆ httpServerError()

bool ts::WebRequest::httpServerError ( ) const

inline

Check if the HTTP status code indicates a server error.

Returns: True if the HTTP status code indicates a server error.

◆ announcedContentSize()

size_t ts::WebRequest::announcedContentSize ( ) const

inline

Get the announced content size in bytes.

This is the value which was sent in the content headers. This may be zero, this may not be the actual size of the content to download.

Returns: Announced content size in bytes.

◆ getResponseHeaders()

void ts::WebRequest::getResponseHeaders ( UStringToUStringMultiMap & headers ) const

inline

Get all response headers.

Parameters

[out] headers A multimap of all response headers.

◆ responseHeaders()

const UStringToUStringMultiMap & ts::WebRequest::responseHeaders ( ) const

inline

Get all response headers.

Returns: A constant reference to a map of response headers.

◆ reponseHeader()

UString ts::WebRequest::reponseHeader ( const UString & name ) const

Get the value of one header.

Parameters

[in] name Header name, case sensitive.

Returns: Header value or an empty string when the header is not found. If the header is present more than once, the first value is returned.

◆ mimeType()

UString ts::WebRequest::mimeType	(	bool	simple = `true`,
		bool	lowercase = `true`
	)		const

Get the MIME type in the response headers.

Parameters

[in]	simple	If true, simple type name. If false, return the full specification with options.
[in]	lowercase	Force lowercase in the result.

Returns: The MIME type.

◆ originalURL()

UString ts::WebRequest::originalURL ( ) const

inline

Get the original URL, as set by setURL().

Returns: The original URL.

◆ finalURL()

UString ts::WebRequest::finalURL ( ) const

inline

Get the final URL of the actual download operation.

It can be different from originalURL() if some HTTP redirections were performed. When called before a download operation, return originalURL().

If redirections are disabled using setAutoRedirect() and the site returned a redirection, finalURL() returns the redirected URL.

Returns: The final / redirected URL.

◆ receive()

bool ts::WebRequest::receive	(	void *	buffer,
		size_t	max_size,
		size_t &	ret_size,
		IOSB *	iosb = `nullptr`
	)

Receive data.

Parameters

[out]	buffer	Address of the buffer for the received data.
[in]	max_size	Size in bytes of the reception buffer.
[out]	ret_size	Size in bytes of the received data. Will never be larger than max_size. When ret_size is zero, this is the end of the transfer.
[in,out]	iosb	Address of an IOSB structure. If non-null, the request must be in non-blocking mode. When null, the request must be in blocking mode (the default). See the description of IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error. A successful end of transfer is reported when ret_size is zero and the returned value is true.

◆ close()

bool ts::WebRequest::close ( )

Close the transfer.

Returns: True on success, false on error.

◆ abort()

void ts::WebRequest::abort ( )

Abort a transfer in progress.

Can be called from another thread.

◆ contentSize()

size_t ts::WebRequest::contentSize ( ) const

inline

Get the size in bytes of the downloaded content.

Returns: Size in bytes of the downloaded content.

◆ downloadBinaryContent()

bool ts::WebRequest::downloadBinaryContent	(	const UString &	url,
		ByteBlock &	data,
		size_t	chunk_size = `DEFAULT_CHUNK_SIZE`
	)

Download the content of the URL as binary data in one operation.

The open/read/close session is embedded in this method. The request must be in blocking mode (the default).

Parameters

[in]	url	The complete URL to fetch.
[out]	data	The content of the URL.
[in]	chunk_size	Individual download chunk size.

Returns: True on success, false on error.

◆ downloadTextContent()

bool ts::WebRequest::downloadTextContent	(	const UString &	url,
		UString &	text,
		size_t	chunk_size = `DEFAULT_CHUNK_SIZE`
	)

Download the content of the URL as text in one operation.

The open/read/close session is embedded in this method.. The downloaded text is converted from UTF-8. End of lines are normalized as LF. The request must be in blocking mode (the default).

Parameters

[in]	url	The complete URL to fetch.
[out]	text	The content of the URL.
[in]	chunk_size	Individual download chunk size.

Returns: True on success, false on error.

◆ downloadFile()

bool ts::WebRequest::downloadFile	(	const UString &	url,
		const fs::path &	file_name,
		size_t	chunk_size = `DEFAULT_CHUNK_SIZE`
	)

Download the content of the URL in a file in one operation.

The open/read/close session is embedded in this method.. No transformation is applied to the data. The request must be in blocking mode (the default).

Parameters

[in]	url	The complete URL to fetch.
[in]	file_name	Name of the file to create.
[in]	chunk_size	Individual download chunk size.

Returns: True on success, false on error.

◆ GetLibraryVersion()

static UString ts::WebRequest::GetLibraryVersion ( )

static

Get the version of the underlying HTTP library.

Returns: The library version.

◆ setNonBlocking()

bool ts::Device::setNonBlocking ( bool non_blocking )

inherited

Set the device in non-blocking mode.

Important: Usually, this method must be called before opening the device, whatever it means. Otherwise it is ignored and the device blocking mode is unchanged.

Parameters

[in] non_blocking It true, the device is set in non-blocking mode.

Returns: True on success, false if the device is already open and the non-blocking mode is unchanged.

◆ isNonBlocking()

bool ts::Device::isNonBlocking ( ) const

inlineinherited

Check if the device is in non-blocking mode.

Returns: True if the device is in non-blocking mode, false otherwise.

See also: setNonBlocking()

◆ isSupportedByReactor()

bool ts::Device::isSupportedByReactor ( bool recheck = false )

inherited

Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

Parameters

[in] recheck If true, force a recheck. If false and the device was previously checked, return the previous cached value.

Returns: True if the device is supported by a reactor for non-blocking or asynchronous I/O, false otherwise.

◆ IsPendingStatus()

static bool ts::Device::IsPendingStatus ( int error_code )

inlinestaticinherited

This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

Parameters

[in] error_code System error code.

Returns: True if error_code is an in-progress/would-block one.

◆ getHandle()

SysHandleType ts::Device::getHandle ( ) const

inherited

Get the underlying file descriptor or device handle.

This method is reserved for low-level operations and should not be used by normal applications.

On UNIX systems, sockets are standard file descriptors. On Windows systems, sockets and devices handles are two distinct types (SOCKET, an integer type, and HANDLE, a pointer type). However, SOCKET and HANDLE have the same size and can be converted between each other. In practice, all Windows device handles are pointers. When Microsoft decided to implement the BSD socket API, they needed to represent sockets as integers. The integer is simply a cast of the HANDLE pointer.

In practice, the methods getHandle() and getSocket() return the same value, represented as two different portable types, SysHandleType and SysSocketType. Note that this types are defined as their real representation. On UNIX systems, both are defined as int and are compatible. However, on Windows systems, they are defined as HANDLE and SOCKET and are not compatible. So, accidentally mixing the two compiles on UNIX but not on Windows. Be careful to use the right type for the right usage.

There is one important difference between getHandle() and getSocket(): the error values, SYS_HANDLE_INVALID and SYS_SOCKET_INVALID. Be careful, these constants have distinct binary values on Windows. This is the only case were it is not possible to cast between a SysHandleType value and a SysSocketType value. This is why it is recommended to always use getHandle() when a SysHandleType is required and getSocket() when a SysSocketType is required.

A subclass which uses file descriptors or device handles for read, write, or both, must override the methods getReadHandle(), getWriteHandle(), or both. If the two types of operations use the same file descriptor, the two methods must return the same value.

An application should call getReadHandle() for read operations and getWriteHandle() for write operations. The method getHandle() returns getReadHandle() if its returns a valid value, and getWriteHandle() otherwise.

Returns: The underlying file descriptor or device handler. Return SYS_HANDLE_INVALID if the socket is not open.

◆ getReadHandle()

virtual SysHandleType ts::Device::getReadHandle ( ) const

virtualinherited

Get the underlying file descriptor or device handle for read operations.

Subclasses should override this method.

Returns: The underlying file descriptor for read operations or SYS_HANDLE_INVALID if the device is not open for read.

See also: getHandle()

Reimplemented in ts::Socket, ts::BinaryFile, and ts::ForkPipe.

◆ getWriteHandle()

virtual SysHandleType ts::Device::getWriteHandle ( ) const

virtualinherited

Get the underlying file descriptor or device handle for write operations.

Subclasses should override this method.

Returns: The underlying file descriptor for write operations or SYS_HANDLE_INVALID if the device is not open for write.

See also: getHandle()

Reimplemented in ts::Socket, ts::BinaryFile, and ts::ForkPipe.

◆ getSocket()

SysSocketType ts::Device::getSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle.

Returns: The underlying socket descriptor. Return SYS_SOCKET_INVALID if the socket is not open.

See also: getHandle()

◆ getReadSocket()

SysSocketType ts::Device::getReadSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle for read operations.

Returns: The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for read.

See also: getHandle()

◆ getWriteSocket()

SysSocketType ts::Device::getWriteSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle for write operations.

Returns: The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for write.

See also: getHandle()

◆ checkNonBlocking() [1/2]

bool ts::Device::checkNonBlocking	(	bool	non_blocking,
		const UChar *	opname
	)

protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters

[in]	non_blocking	The required non-blocking mode.
[in]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ checkNonBlocking() [2/2]

bool ts::Device::checkNonBlocking	(	IOSB *	iosb,
		const UChar *	opname
	)

protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters

[in,out]	iosb	Address of an IOSB structure. If non-null, we are in non-blocking mode. When null, we are in blocking mode. When non-null, pending is reset to false and overlap is zeroed.
[in]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ allowSetNonBlocking()

virtual bool ts::Device::allowSetNonBlocking ( ) const

protectedvirtualinherited

Check that the non-blocking mode can be set.

Must be implemented by subclasses which do not support setting the non-blocking in certain states, such as after being opened. The default implementation always allows setting the non-blocking mode.

Returns: True if setting the non-blocking mode is allowed, false otherwise.

Reimplemented in ts::Socket, ts::BinaryFile, and ts::ForkPipe.

◆ setSystemNonBlocking()

bool ts::Device::setSystemNonBlocking ( bool non_blocking )

protectedinherited

Low-level method to set the system file or socket descriptor in non-blocking mode.

Parameters

[in] non_blocking It true, the device is set in non-blocking mode.

Returns: True on success, false on error.

Summary: Do not use this method unless you exactly know what you are doing.

UNIX: Depending on the way a file descriptor is created, it may be possible to specify the non-blocking mode from the beginning. Or it can be somehow inherited. However, this is not portable.

Examples:

On Linux and FreeBSD, a socket can be directly created in non-blocking mode using the flag SOCK_NONBLOCK in the 'type' parameter of the socket() system call. However, it does not work on macOS.
On macOS (and maybe FreeBSD), when a server socket is in non-blocking mode, all client session sockets which are created by accept() are also in non-blocking mode. However, on Linux, they are in blocking mode.

In all cases, it is possible to set a file descriptor in non-blocking mode at any time using the method setSystemNonBlocking(). This method uses fcntl(F_SETFL) to alter the file descriptor's flags.

Windows: The natural way of not being blocked on I/O on Windows is asynchronous I/O. To increase the general confusion, there is some form of non-blocking mode on Windows sockets, and only sockets, not other forms of file handles. This mode is activated using "ioctlsocket(fd, FIONBIO, &mode)". When this mode is active, socket I/O become similar to UNIX: they immediately either succeed or fail, but never block. However, there is no way to get notified when the I/O becomes possible. There is no equivalent to epoll (Linux) or kqueue (macOS and BSD). The Windows I/O Completion Ports can only work on asynchronous I/O, using OVERLAPPED structures. Because this form of non-blocking mode is mostly useless in practice, we do not use it and the method setSystemNonBlocking() does nothing on Windows.

See also: https://learn.microsoft.com/en-us/archive/blogs/csliu/io-concept-blockingnon-blocking-vs-syncasync

◆ genericSystemWrite()

int ts::Device::genericSystemWrite	(	const void *	addr,
		size_t	size,
		size_t &	written_size,
		Device::IOSB *	iosb,
		uint64_t	position
	)

protectedinherited

Generic system write operation.

This is a convenience method which can be used (or not) by subclasses when the system calls write() (UNIX) or WriteFile() (Windows) are appropriate.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[out]	written_size	Actually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::Device::IOSB.
[in]	position	This value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.

Returns: Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to write (e.g. broken pipe).

◆ genericSystemRead()

int ts::Device::genericSystemRead	(	void *	addr,
		size_t	max_size,
		size_t &	ret_size,
		const AbortInterface *	abort,
		Device::IOSB *	iosb,
		uint64_t	position
	)

protectedinherited

Generic system read operation.

This is a convenience method which can be used (or not) by subclasses when the system calls read() (UNIX) or ReadFile() (Windows) are appropriate.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	max_size	Maximum size in bytes of the buffer.
[out]	ret_size	Returned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::Device::IOSB.
[in]	position	This value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.

Returns: Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to read.

◆ report()

virtual Report & ts::ReporterBase::report ( ) const

overridevirtualinherited

Access the Report which is associated with this object.

Can be called from another thread only if the Report object is thread-safe.

Returns: A reference to the associated report.

Implements ts::ReporterInterface.

◆ setReport() [1/2]

Report * ts::ReporterBase::setReport ( Report * report )

inherited

Associate this object with another Report to log errors.

Parameters

[in] report Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.

Returns: The address of the previous Report object or a null pointer if there was none.

◆ setReport() [2/2]

ReporterBase * ts::ReporterBase::setReport ( ReporterBase * delegate )

inherited

Associate this object with another ReporterBase to log errors.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, the previous explicit Report is used..

Returns: The address of the previous ReporterBase object or a null pointer if there was none.

◆ muteReport()

bool ts::ReporterBase::muteReport ( bool mute )

inherited

Temporarily mute the associated report.

Parameters

[in] mute It true, report() will return a null report (log messages are discarded), until muteReport() is invoked again with mute set to false.

Returns: Previous state of the mute field.

◆ SilentLevel()

static int ts::ReporterBase::SilentLevel	(	bool	silent,
		int	default_severity = `Severity::Error`
	)

inlinestaticinherited

Compute a log severity level from a "silent" parameter.

Some subclass methods have a "silent" parameter to avoid reporting errors which may be insignificant, typically when closing a device after an error, in which case the close operation may produce other errors if the previous error left the device in an inconsistent state. While those errors should not be displayed as errors, we still display them at debug level.

Parameters

[in]	silent	If true, do not report errors, report debug messages instead.
[in]	default_severity	Default severity, in non-silent mode (error by default).

Returns: Error when silent is false, Debug otherwise.

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

tsWebRequest.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ WebRequest() [1/2]

◆ WebRequest() [2/2]

Member Function Documentation

◆ setConnectionTimeout()

◆ setReceiveTimeout()

◆ setProxyHost()

◆ setProxyUser()

◆ SetDefaultProxyHost()

◆ SetDefaultProxyUser()

◆ proxyHost()

◆ proxyPort()

◆ proxyUser()

◆ proxyPassword()

◆ enableCookies()

◆ disableCookies()

◆ getCookiesFileName()

◆ deleteCookiesFile()

◆ setUserAgent()

◆ userAgent()

◆ enableCompression()

◆ setInsecure()

◆ setAutoRedirect()

◆ setArgs()

◆ setRequestHeader()

◆ deleteRequestHeader()

◆ setPostData() [1/2]

◆ setPostData() [2/2]

◆ clearPostData()

◆ open()

◆ isOpen()

◆ httpStatus()

◆ httpSuccess()

◆ httpClientError()

◆ httpServerError()

◆ announcedContentSize()

◆ getResponseHeaders()

◆ responseHeaders()

◆ reponseHeader()

◆ mimeType()

◆ originalURL()

◆ finalURL()

◆ receive()

◆ close()

◆ abort()

◆ contentSize()

◆ downloadBinaryContent()

◆ downloadTextContent()

◆ downloadFile()

◆ GetLibraryVersion()

◆ setNonBlocking()

◆ isNonBlocking()

◆ isSupportedByReactor()

◆ IsPendingStatus()

◆ getHandle()

◆ getReadHandle()

◆ getWriteHandle()

◆ getSocket()

◆ getReadSocket()

◆ getWriteSocket()

◆ checkNonBlocking() [1/2]

◆ checkNonBlocking() [2/2]

◆ allowSetNonBlocking()

◆ setSystemNonBlocking()

◆ genericSystemWrite()

◆ genericSystemRead()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()