Encapsulate the SChannel context of TLS connection (Windows-specific). More...

#include <tsSChannelContext.h>

Inheritance diagram for ts::SChannelContext:

[legend]

Collaboration diagram for ts::SChannelContext:

[legend]

Public Member Functions
	SChannelContext (ReporterBase delegate, const TLSConnectionBase &params, Object owner=nullptr)
	Constructor.

virtual	~SChannelContext ()
	Destructor.

bool	eof () const
	Check if the input TLS stream is terminated (peer shutdown).

bool	initClient ()
	Initialize the client side of a connection.

bool	initServer (::PCCERT_CONTEXT cert)
	Initialize the server side of a connection.

bool	initShutdown ()
	Generate a shutdown message to send to the peer.

bool	isOwned ()
	Check if the object is owned.

template<class OBJECT > requires std::derived_from<OBJECT, ts::Object>
bool	isOwned ()
	Check if the object is owned by an object of a given type.

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

bool	needReceive () const
	Check if more TLS protocol data must be received in order to continue.

bool	needSend () const
	Check if some TLS protocol data must be sent.

Object *	owner ()
	Get the address of the optional "owner" object which was specified in the constructor.

template<class OBJECT > requires std::derived_from<OBJECT, ts::Object>
OBJECT *	owner ()
	Get the address of the "owner" object which was specified in the constructor.

void *	receiveAddress ()
	Get the address of the input buffer for the TLS protocol data to receive.

bool	receiveCompleted (size_t received_size, ByteBlock &user_data)
	Acknowledge the reception of data in the input buffer.

size_t	receiveSize () const
	Get the size in bytes of the input buffer for the TLS protocol data to receive.

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

void	reset ()
	Clear the context, free all resources.

const void *	sendAddress () const
	Get the address of the TLS protocol data to send.

bool	sendCompleted ()
	Acknowledge that the data to send are fully sent.

size_t	sendSize () const
	Get the size in bytes of the TLS protocol data to send.

bool	sendUserData (const void *&data, size_t &size)
	Send clear user data over the TLS connection.

bool	serverSide () const
	Check if this is the server-side of the TLS connection.

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.

bool	shutdowning () const
	Check if a TLS shutdown was generated.

Static Public Member Functions
static int	SilentLevel (bool silent)
	Compute a log severity level from a "silent" parameter.

Detailed Description

Encapsulate the SChannel context of TLS connection (Windows-specific).

No I/O is done in this class. Thus, it can be used in blocking and asynchronous implementation of TLS on Windows.

Constructor & Destructor Documentation

◆ SChannelContext()

ts::SChannelContext::SChannelContext	(	ReporterBase *	delegate,
		const TLSConnectionBase &	params,
		Object *	owner = `nullptr`
	)

Constructor.

Parameters

[in]	delegate	Use the report of another ReporterBase. If delegate is null, log messages are discarded.
[in]	params	TLS connection parameters.
[in]	owner	Optional address of an "owner" object, typically an instance of class containing this object.

Member Function Documentation

◆ initClient()

bool ts::SChannelContext::initClient ( )

Initialize the client side of a connection.

Returns: True on success, false on error.

◆ initServer()

bool ts::SChannelContext::initServer ( ::PCCERT_CONTEXT cert )

Initialize the server side of a connection.

Parameters

[in] cert Pointer to server certificate.

Returns: True on success, false on error.

◆ serverSide()

bool ts::SChannelContext::serverSide ( ) const

inline

Check if this is the server-side of the TLS connection.

Returns: True if this is the server-side of the TLS connection.

◆ sendUserData()

bool ts::SChannelContext::sendUserData	(	const void *&	data,
		size_t &	size
	)

Send clear user data over the TLS connection.

Most of the time, this results in a TLS protocol packet to be sent. If the user data are too long, only some of them can be sent in the next TLS protocol packet.

Parameters

[in,out]	data	Address of the clear user message to sent. On output, it is updated with the length of the actual part of the message which is ready to send.
[in,out]	size	Siz in bytes of the clear user message to sent. On output, it is updated with the length of the actual part of the message which is ready to send.

Returns: True on success, false on error.

See also: needSend()

◆ needSend()

bool ts::SChannelContext::needSend ( ) const

inline

Check if some TLS protocol data must be sent.

The application must send the corresponding data and then call sendCompleted().

Returns: True if there are some TLS protocol data to send.

See also: sendAddress(); sendSize(); sendCompleted()

◆ sendAddress()

const void * ts::SChannelContext::sendAddress ( ) const

inline

Get the address of the TLS protocol data to send.

Returns: The address of the TLS protocol data to send or a null pointer if there is none.

See also: needSend(); sendSize(); sendCompleted()

◆ sendSize()

size_t ts::SChannelContext::sendSize ( ) const

inline

Get the size in bytes of the TLS protocol data to send.

Returns: The size in bytes of the TLS protocol data to send.

See also: needSend(); sendAddress(); sendCompleted()

◆ sendCompleted()

bool ts::SChannelContext::sendCompleted ( )

Acknowledge that the data to send are fully sent.

Returns: True on success, false on error.

◆ needReceive()

bool ts::SChannelContext::needReceive ( ) const

inline

Check if more TLS protocol data must be received in order to continue.

Returns: True if more TLS protocol data must be received in order to continue.

◆ receiveAddress()

void * ts::SChannelContext::receiveAddress ( )

inline

Get the address of the input buffer for the TLS protocol data to receive.

Returns: The address of the input buffer.

See also: needReceive(); receiveSize(); receiveCompleted()

◆ receiveSize()

size_t ts::SChannelContext::receiveSize ( ) const

inline

Get the size in bytes of the input buffer for the TLS protocol data to receive.

Returns: The size in bytes of the input buffer.

See also: needReceive(); receiveAddress(); receiveCompleted()

◆ receiveCompleted()

bool ts::SChannelContext::receiveCompleted	(	size_t	received_size,
		ByteBlock &	user_data
	)

Acknowledge the reception of data in the input buffer.

Parameters

[in]	received_size	Received size in bytes.
[in,out]	user_data	If any clear user data were extracted from the TLS protocol data, they are appended into user_data.

Returns: True on success, false on error.

◆ eof()

bool ts::SChannelContext::eof ( ) const

inline

Check if the input TLS stream is terminated (peer shutdown).

Returns: True if the input TLS stream is terminated.

◆ initShutdown()

bool ts::SChannelContext::initShutdown ( )

Generate a shutdown message to send to the peer.

Returns: True on success, false on error.

◆ shutdowning()

bool ts::SChannelContext::shutdowning ( ) const

inline

Check if a TLS shutdown was generated.

Returns: True if a TLS shutdown was generated.

◆ report()

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

inherited

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.

◆ 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 )

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.

Returns: Error when silent is false, Debug otherwise.

◆ owner() [1/2]

Object * ts::OwnedObject::owner ( )

inlineinherited

Get the address of the optional "owner" object which was specified in the constructor.

Returns: Address of the "owner" object or a null pointer if there was none.

◆ owner() [2/2]

template<class OBJECT >
requires std::derived_from<OBJECT, ts::Object>

OBJECT * ts::OwnedObject::owner ( )

inherited

Get the address of the "owner" object which was specified in the constructor.

This template version requires that the owner objet is set and of type OBJECT, or some subclass of it. If there is no owner object or if it is not compatible with the template class OBJECT, this is a fatal error and the application is terminated.

Template Parameters

OBJECT A subclass of Object

Returns: Address of the "owner" object or a null pointer if there was none.

◆ isOwned() [1/2]

bool ts::OwnedObject::isOwned ( )

inlineinherited

Check if the object is owned.

Returns: True if this object has an owner, false otherwise.

◆ isOwned() [2/2]

template<class OBJECT >
requires std::derived_from<OBJECT, ts::Object>

bool ts::OwnedObject::isOwned ( )

inlineinherited

Check if the object is owned by an object of a given type.

Template Parameters

OBJECT A subclass of Object

Returns: True if this object has an owner by an object of type OBJECT, false otherwise.

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

tsSChannelContext.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SChannelContext()

Member Function Documentation

◆ initClient()

◆ initServer()

◆ serverSide()

◆ sendUserData()

◆ needSend()

◆ sendAddress()

◆ sendSize()

◆ sendCompleted()

◆ needReceive()

◆ receiveAddress()

◆ receiveSize()

◆ receiveCompleted()

◆ eof()

◆ initShutdown()

◆ shutdowning()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()

◆ owner() [1/2]

◆ owner() [2/2]

◆ isOwned() [1/2]

◆ isOwned() [2/2]