The rsocket_alpn class provides a specialized interface for easily managing a collection of ALPN protocol names, and maintaining the underlying structure that's always immediately ready for use with OpenSSL's ALPN callback function and any other uses that need this. More...

#include <randolf/rsocket_alpn>

Collaboration diagram for randolf::rsocket_alpn:

Public Member Functions
	rsocket_alpn () noexcept
	Instantiate a new rsocket_alpn object.
	rsocket_alpn (const rsocket_alpn &original) noexcept
	Instantiate a new rsocket_alpn object that is an independent copy of an existing rsocket_alpn object.
	~rsocket_alpn () noexcept
	Destructor for rsocket_alpn object, which releases all interally-allocated resources.
rsocket_alpn &	add (const char *alpn_protocol, int len=-1)
	Add one protocol name to the internal ALPN protocol-list structure. If the protocol name provided is already in the list, or it's an empty string (or `nullptr` was provided), it will simply be ignored.
rsocket_alpn &	add (const std::string &alpn_protocol)
	Add one protocol name to the internal ALPN protocol-list structure. If the protocol name provided is already in the list, or it's an empty string, it will simply be ignored.
template<class... Ps>
rsocket_alpn &	add (const std::string &alpn_protocol, Ps... alpn_protocols)
	Add one or more new protocol names, which will be added to the internal ALPN protocol-list structure.
const unsigned char *	data () noexcept
	Return pointer to entire ALPN protocol-list structure.
rsocket_alpn &	del (const char *alpn_protocol, int len=-1)
	Delete one protocol name from the internal ALPN protocol-list structure. If the protocol name provided is not already in the list, or it's an empty string (or `nullptr` was provided), nothing will be deleted.
rsocket_alpn &	del (const std::string &alpn_protocol)
	Delete one protocol name from the internal ALPN protocol-list structure.
template<class... Ps>
rsocket_alpn &	del (const std::string &alpn_protocol, Ps... alpn_protocols)
	Delete one or more protocol names from the internal ALPN protocol-list.
bool	exists (const char *alpn_protocol, int len=-1) noexcept
	Indicate whether a given ALPN protocol-name is in the internal structure.
int	find (const char *alpn_protocol)
	Find the array position of the first respective ALPN protocol-name within the internal structure.
size_t	operator[] (const char *alpn_protocol)
	Array-style access to the index of the respective ALPN protocol-name within the internal structure.
std::string	operator[] (int index)
	Array-style access to the respective ALPN protocol-name within the internal structure, which yields the same result as that of the at() method.
size_t	size () noexcept
	Return quantity of names in the internal ALPN protocol-list structure.

Detailed Description

The rsocket_alpn class provides a specialized interface for easily managing a collection of ALPN protocol names, and maintaining the underlying structure that's always immediately ready for use with OpenSSL's ALPN callback function and any other uses that need this.

Note: There's no maximum limit on the number of ALPN protocol name entries that can be added (aside from system memory limits, of course).
At present, the official variety of ALPN protocol names is small, but as this list is expected to grow significantly as QUIC continues to gain popularity, a long list of protocol names will not be a hindering factor.

The DNS protocol uses the same format, although with a slight variation in that the total length of the ALPN structure is known beforehand.

An example of the format of ALPN is presented in the OpenSSL 3.5 documentation as follows:

//
// ALPN strings for TLS handshake. Only 'http/1.0' and 'hq-interop'
// are accepted.
//
static const unsigned char alpn_ossltest[] = {
  8, 'h', 't', 't', 'p', '/', '1', '.', '0',
  10, 'h', 'q', '-', 'i', 'n', 't', 'e', 'r', 'o', 'p',
};

This shows an example of having two entries, each of which begins with one byte indicating the length of the ALPN name, and then that exact quantity of characters (note that there are no terminating zeroes):

<0x08> http/1.0
<0x0a> hq-interop

The total size of the ALPN protocol-list is not included in the list data, and OpenSSL's documentation relies on sizeof(alpn_ossltest) to determine the size of the ALPN protocol-list. While this is fine for simple uses, this class provides a dymamically-maintained size that's always correct.

In summary, the purpose of this rsocket_alpn class is to eliminate the hassle of having to maintain ALPN protocol-list data, which sipmlifies coding efforts in a manner that also makes it much easier to develop software that can have more configuration options, including ALPN protocol-list sets.

Author: Randolf Richardson

Version: 1.00

History

2025-Oct-24 v1.00 Initial version, which has a limited feature-set to get things working: add(), size(), and data() methods only
2025-Oct-26 v1.00 Added del(), exists(), find(), and operator[] methods

Constructor & Destructor Documentation

◆ rsocket_alpn() [1/2]

randolf::rsocket_alpn::rsocket_alpn ( )

inlinenoexceptTLS

Instantiate a new rsocket_alpn object.

See also: ~rsocket_alpn()

Referenced by rsocket_alpn(), add(), add(), add(), del(), del(), and del().

◆ rsocket_alpn() [2/2]

randolf::rsocket_alpn::rsocket_alpn ( const rsocket_alpn & original )

inlinenoexceptTLS

Instantiate a new rsocket_alpn object that is an independent copy of an existing rsocket_alpn object.

See also: ~rsocket_alpn()

Parameters

original Existing rsocket_alpn object to copy from

References rsocket_alpn().

◆ ~rsocket_alpn()

randolf::rsocket_alpn::~rsocket_alpn ( )

inlinenoexceptTLS

Destructor for rsocket_alpn object, which releases all interally-allocated resources.

See also: rsocket_alpn()

Member Function Documentation

◆ add() [1/3]

rsocket_alpn & randolf::rsocket_alpn::add	(	const char *	alpn_protocol,
		int	len = -1 )

inlineTLS

Add one protocol name to the internal ALPN protocol-list structure. If the protocol name provided is already in the list, or it's an empty string (or nullptr was provided), it will simply be ignored.

Exceptions

std::out_of_range If the length of alpn_protocol is greater than 255 characters

Returns: The same rsocket object so as to facilitate stacking

See also: add; del; size

Parameters

alpn_protocol	ALPN protocol as an ASCIIZ string
len	Length of string (-1 = measure ASCIIZ string automatically)

References rsocket_alpn(), and exists().

Referenced by add().

◆ add() [2/3]

rsocket_alpn & randolf::rsocket_alpn::add ( const std::string & alpn_protocol )

inlineTLS

Add one protocol name to the internal ALPN protocol-list structure. If the protocol name provided is already in the list, or it's an empty string, it will simply be ignored.

Exceptions

std::out_of_range If the length of alpn_protocol is greater than 255 characters

Returns: The same rsocket object so as to facilitate stacking

See also: add; del; size

Parameters

alpn_protocol ALPN protocol as a C++ string

References rsocket_alpn(), and exists().

◆ add() [3/3]

template<class... Ps>

rsocket_alpn & randolf::rsocket_alpn::add	(	const std::string &	alpn_protocol,
		Ps...	alpn_protocols )

inlineTLS

Add one or more new protocol names, which will be added to the internal ALPN protocol-list structure.

Note: All of the specified protocol names that already exist, or are empty strings, sill simply be ignored.

Returns: The same rsocket_alpn object so as to facilitate stacking

See also: add; del; size

Parameters

alpn_protocol	First ALPN protocol name as a C++ string (required)
alpn_protocols	Additional ALPN protocol names (optional)

References rsocket_alpn(), and add().

◆ data()

const unsigned char * randolf::rsocket_alpn::data ( )

inlinenoexceptTLS

Return pointer to entire ALPN protocol-list structure.

Returns: Pointer to raw data

See also: size

◆ del() [1/3]

rsocket_alpn & randolf::rsocket_alpn::del	(	const char *	alpn_protocol,
		int	len = -1 )

inlineTLS

Delete one protocol name from the internal ALPN protocol-list structure. If the protocol name provided is not already in the list, or it's an empty string (or nullptr was provided), nothing will be deleted.

Exceptions

std::out_of_range If the length of alpn_protocol is greater than 255 characters

Returns: The same rsocket object so as to facilitate stacking

See also: add; del; size

Parameters

alpn_protocol	ALPN protocol as an ASCIIZ string
len	Length of string (-1 = measure ASCIIZ string automatically)

References rsocket_alpn().

Referenced by del().

◆ del() [2/3]

rsocket_alpn & randolf::rsocket_alpn::del ( const std::string & alpn_protocol )

inlineTLS

Delete one protocol name from the internal ALPN protocol-list structure.

Note: If the protocol name provided is not already in the list, or it's an empty string, nothing will be deleted.

Exceptions

std::out_of_range If the length of alpn_protocol is greater than 255 characters

Returns: The same rsocket object so as to facilitate stacking

See also: add; del; size

Parameters

alpn_protocol ALPN protocol as an ASCIIZ string

References rsocket_alpn().

◆ del() [3/3]

template<class... Ps>

rsocket_alpn & randolf::rsocket_alpn::del	(	const std::string &	alpn_protocol,
		Ps...	alpn_protocols )

inlineTLS

Delete one or more protocol names from the internal ALPN protocol-list.

Note: All of the specified protocol names that already exist, or are empty strings, sill simply be ignored.

Returns: The same rsocket_alpn object so as to facilitate stacking

See also: add; del; size

Parameters

alpn_protocol	First ALPN protocol name as a C++ string (required)
alpn_protocols	Additional ALPN protocol names (optional)

References rsocket_alpn(), and del().

◆ exists()

bool randolf::rsocket_alpn::exists	(	const char *	alpn_protocol,
		int	len = -1 )

inlinenoexceptTLS

Indicate whether a given ALPN protocol-name is in the internal structure.

Note: The ALPN protocol-name is case-sensitive.

Returns: TRUE = specified ALPN protocol-name was found
FALSE = ALPN protocol-name not found

See also: find; operator[](const char*); operator[](int)

Parameters

alpn_protocol	ALPN protocol-name to search for
len	Length of string (-1 = measure ASCIIZ string automatically)

Referenced by add(), and add().

◆ find()

int randolf::rsocket_alpn::find ( const char * alpn_protocol )

inlineTLS

Find the array position of the first respective ALPN protocol-name within the internal structure.

Note: The ALPN protocol-name is case-sensitive.

Returns: Index of the specified ALPN protocol-name (if found)
-1 = not found

See also: exists; operator[](const char*); operator[](int)

Parameters

alpn_protocol ALPN protocol-name to search for

◆ size()

size_t randolf::rsocket_alpn::size ( )

inlinenoexceptTLS

Return quantity of names in the internal ALPN protocol-list structure.

Returns: Total quantity of bytes

See also: add; del

◆ operator[]() [1/2]

std::string randolf::rsocket_alpn::operator[] ( int index )

inlineTLS

Array-style access to the respective ALPN protocol-name within the internal structure, which yields the same result as that of the at() method.

The first element is at index 0.

Exceptions

std::out_of_range if the index is out-of-range

Returns: char

See also: exists; find

Parameters

index Index of ALPN protocol-name to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position)

◆ operator[]() [2/2]

size_t randolf::rsocket_alpn::operator[] ( const char * alpn_protocol )

inlineTLS

Array-style access to the index of the respective ALPN protocol-name within the internal structure.

Note: The ALPN protocol-name is case-sensitive.

Exceptions

std::out_of_range if the specified ALPN protocol-name doesn't exist

Returns: Index of the specified ALPN protocol-name (if exists)

See also: exists; find

Parameters

alpn_protocol ALPN protocol-name to search for

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

randolf/rsocket_alpn

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ rsocket_alpn() [1/2]

◆ rsocket_alpn() [2/2]

◆ ~rsocket_alpn()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ data()

◆ del() [1/3]

◆ del() [2/3]

◆ del() [3/3]

◆ exists()

◆ find()

◆ size()

◆ operator[]() [1/2]

◆ operator[]() [2/2]