A log entry. More...

#include <Entry.hpp>

Public Member Functions
	Entry (Facility facility, Severity severity, const char app_name, const char msgid, const char *message,...)
	Creates an Entry with the given properties.

	Entry (struct stumpless_entry *entry)
	Creates an Entry from a stumpless_entry struct.

	Entry (const Entry &entry)
	Creates an Entry as a copy of another Entry.

	~Entry (void)
	Destroys the Entry and frees any memory allocated for it.

Entry &	AddElement (Element &element)
	Adds an element to an entry.

Entry &	AddElement (Element *element)
	Adds an Element to this Entry.

Entry &	AddElement (const char *name)
	Creates a new Element and adds it to this Entry.

Entry &	AddParam (const char element_name, const char param_name, const char *param_value)
	Creates a new Param and adds it to the specified Element in this Entry.

const char *	GetAppName (void)
	Gets the app name from this Entry.

Element	GetElement (size_t index)
	Gets the Element at the given index in this Entry.

Element	GetElement (const char *name)
	Gets the Element with the given name from this Entry.

size_t	GetElementCount (void)
	Returns the number of elements in this Entry.

size_t	GetElementIndex (const char *name)
	Gets the index of the Element with the given name from this Entry.

Facility	GetFacility (void)
	Gets the Facility of this Entry.

const char *	GetMessage (void)
	Gets the message from this Entry.

const char *	GetMsgid (void)
	Gets the msgid of this Entry.

Param	GetParam (size_t element_index, size_t param_index)
	Gets the Param from the Element at the given index from this Entry.

Param	GetParam (const char element_name, const char param_name)
	Gets the first Param from the Element with the given name from this Entry.

const char *	GetParamValue (size_t element_index, size_t param_index)
	Gets the value of the Param from the Element at the given index from this Entry.

const char *	GetParamValue (const char element_name, const char param_name)
	Gets the value of the first Param from the Element with the given name from this Entry.

int	GetPrival (void)
	Gets the prival of this Entry, as defined in RFC 5424.

Severity	GetSeverity (void)
	Gets the Severity of this Entry.

bool	HasElement (const char *name)
	True if this Entry has an Element with the given name, false otherwise.

Entry &	SetAppName (const char *app_name)
	Sets the app name for an entry.

Entry &	SetElement (size_t index, Element &element)
	Puts the element at the given index in this Entry.

Entry &	SetFacility (Facility facility)
	Sets the Facility of this Entry.

Entry &	SetMsgid (const char *msgid)
	Sets the msgid for this Entry.

Entry &	SetMessage (const char *message,...)
	Sets the message of an Entry.

Entry &	SetParam (size_t element_index, size_t param_index, Param &param)
	Puts the Param in the Element at the given index of this Entry.

Entry &	SetParamValue (size_t element_index, size_t param_index, const char *value)
	Sets the value of the Param in the Element at the given index of this Entry.

Entry &	SetParamValue (const char element_name, const char param_name, const char *value)
	Sets the value of the first Param with the given name in the Element with the given name in this Entry.

Entry &	SetPriority (Facility facility, Severity severity)
	Sets the Facility and Severity of this Entry.

Entry &	SetPrival (int prival)
	Sets the prival of this Entry, as defined in RFC 5424.

Entry &	SetSeverity (Severity severity)
	Sets the Severity of this Entry.

Public Attributes
struct stumpless_entry *	equivalent

Detailed Description

A log entry.

Entries are the basic element of logging in Stumpless.

Constructor & Destructor Documentation

◆ Entry() [1/3]

stumpless::Entry::Entry	(	Facility	facility,
		Severity	severity,
		const char *	app_name,
		const char *	msgid,
		const char *	message,
			... )

Creates an Entry with the given properties.

Parameters

facility	The facility code of the event this entry describes.
severity	The severity of the event this entry describes.
app_name	The app_name of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
msgid	The msgid of the entry. If this is NULL, then it will be blank in the entry (a single '-' character).
message	The message in the entry. This message may contain any format specifiers valid in printf. If this is NULL, then it will be blank in the entry (no characters). This also means that characters such as % need to be escaped as they would be in printf.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

◆ Entry() [2/3]

stumpless::Entry::Entry ( struct stumpless_entry * entry )

Creates an Entry from a stumpless_entry struct.

Available since release v1.6.0.

Parameters

entry The struct to create this Entry from. The struct will be copied during this creation, and so any changes made to it after this call will not be reflected in the resulting instance.

◆ Entry() [3/3]

stumpless::Entry::Entry ( const Entry & entry )

Creates an Entry as a copy of another Entry.

Available since release v1.6.0.

Parameters

entry The Entry to copy.

◆ ~Entry()

stumpless::Entry::~Entry ( void )

Destroys the Entry and frees any memory allocated for it.

Member Function Documentation

◆ AddElement() [1/3]

Entry & stumpless::Entry::AddElement ( const char * name )

Creates a new Element and adds it to this Entry.

Note that duplicate elements are not allowed in RFC 5424, and as such attempts to add an element to an entry already having one with the same name will result in a DuplicateElement exception.

Parameters

name	The name of the new Element.

Returns: The modified Entry.

◆ AddElement() [2/3]

Entry & stumpless::Entry::AddElement ( Element & element )

Adds an element to an entry.

Parameters

element The element to add.

Returns: The modified Entry, to support method chaining.

◆ AddElement() [3/3]

Entry & stumpless::Entry::AddElement ( Element * element )

Adds an Element to this Entry.

Note that duplicate elements are not allowed in RFC 5424, and as such attempts to add an Element to an Entry already having one with the same name will result in a DuplicateElement exception.

Parameters

element A pointer to the element to add.

Returns: The modified Entry, to support method chaining.

◆ AddParam()

Entry & stumpless::Entry::AddParam	(	const char *	element_name,
		const char *	param_name,
		const char *	param_value )

Creates a new Param and adds it to the specified Element in this Entry.

If an Element with the given name does not exist in this Entry, then one will be created with the new Param added to it.

Available since release v1.6.0.

Parameters

element_name	The name of the Element to add the Param to. This will be created if it is not found.
param_name	The name of the new Param.
param_value	The value of the new Param.

Returns: The modified Entry.

◆ GetAppName()

const char * stumpless::Entry::GetAppName ( void )

Gets the app name from this Entry.

The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. Available since release v2.0.0.

Returns: The app name of this Entry.

◆ GetElement() [1/2]

Element stumpless::Entry::GetElement ( const char * name )

Gets the Element with the given name from this Entry.

Available since release v1.6.0.

Parameters

name	The name of the Element to retrieve.

Returns: The requested Element.

◆ GetElement() [2/2]

Element stumpless::Entry::GetElement ( size_t index )

Gets the Element at the given index in this Entry.

Available since release v1.6.0.

Parameters

index The index of the Element to retrieve.

Returns: The requested Element.

◆ GetElementCount()

size_t stumpless::Entry::GetElementCount ( void )

Returns the number of elements in this Entry.

Returns: The number of elements this Entry has.

◆ GetElementIndex()

size_t stumpless::Entry::GetElementIndex ( const char * name )

Gets the index of the Element with the given name from this Entry.

Available since release v1.6.0.

Parameters

name	The name of the Element to retrieve.

Returns: The index of the specified Element.

◆ GetFacility()

Facility stumpless::Entry::GetFacility ( void )

Gets the Facility of this Entry.

Available since release v1.6.0.

Returns: The Facility of this Entry.

◆ GetMessage()

const char * stumpless::Entry::GetMessage ( void )

Gets the message from this Entry.

Note that if this message was originally set using format specifiers, the result will have them substituted instead of the original placeholders. The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. Available since release v2.0.0.

Returns: The message of this Entry.

◆ GetMsgid()

const char * stumpless::Entry::GetMsgid ( void )

Gets the msgid of this Entry.

The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. Available since release v2.0.0.

Returns: The msgid of this Entry.

◆ GetParam() [1/2]

Param stumpless::Entry::GetParam	(	const char *	element_name,
		const char *	param_name )

Gets the first Param from the Element with the given name from this Entry.

Note that an Element may contain as many instances of a Param as desired according to RFC 5424, and therefore there may be other Param instances with the same name. If you need a reference to other Params with the same name in the Element, then you must loop through all Params using GetParam with an index, checking each name.

Available since release v1.6.0.

Parameters

element_name	The name of the Element to get the Param from.
param_name	The name of the Param to get within the Element.

Returns: The first Param with the given name.

◆ GetParam() [2/2]

Param stumpless::Entry::GetParam	(	size_t	element_index,
		size_t	param_index )

Gets the Param from the Element at the given index from this Entry.

Available since release v1.6.0.

Parameters

element_index	The index of the Element to get the Param from.
param_index	The index of the Param to get within the Element.

Returns: The Param at the given index.

◆ GetParamValue() [1/2]

const char * stumpless::Entry::GetParamValue	(	const char *	element_name,
		const char *	param_name )

Gets the value of the first Param from the Element with the given name from this Entry.

Note that an Element may contain as many instances of a Param as desired according to RFC 5424, and therefore there may be other Param instances with the same name. If you need the value of other Params with the same name in the Element, then you must loop through all Params using GetParam with an index, checking each name. The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. In versions prior to v2.0.0, the returned pointer was to the internal buffer was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues. Available since release v1.6.0.

Parameters

element_name	The name of the Element to get the Param from.
param_name	The name of the Param to get the value of within the Element.

Returns: The value of the first Param with the given name.

◆ GetParamValue() [2/2]

const char * stumpless::Entry::GetParamValue	(	size_t	element_index,
		size_t	param_index )

Gets the value of the Param from the Element at the given index from this Entry.

The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. In versions prior to v2.0.0, the returned pointer was to the internal buffer was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues. Available since release v1.6.0.

Parameters

element_index	The index of the Element to get the Param from.
param_index	The index of the Param to get the value of within the Element.

Returns: The value of the Param at the given index.

◆ GetPrival()

int stumpless::Entry::GetPrival ( void )

Gets the prival of this Entry, as defined in RFC 5424.

Available since release v1.6.0.

Returns: The prival of this Entry.

◆ GetSeverity()

Severity stumpless::Entry::GetSeverity ( void )

Gets the Severity of this Entry.

Available since release v1.6.0.

Returns: The Severity of this Entry.

◆ HasElement()

bool stumpless::Entry::HasElement ( const char * name )

True if this Entry has an Element with the given name, false otherwise.

Available since release v1.6.0.

Parameters

name	The name of the Element to look for.

Returns: True if the Element is found, false if not.

◆ SetAppName()

Entry & stumpless::Entry::SetAppName ( const char * app_name )

Sets the app name for an entry.

Parameters

app_name The new app_name for the entry as a NULL-terminated string. This will be copied in to the entry, and therefore may be modified or freed after this call without affecting the entry. If this is NULL, then a single '-' character will be used, as specified as the NILVALUE in RFC 5424.

Returns: The modified Entry, to support method chaining.

◆ SetElement()

Entry & stumpless::Entry::SetElement	(	size_t	index,
		Element &	element )

Puts the element at the given index in this Entry.

An Element cannot be set at an index position that does not already hold one. If this is attempted, then an IndexOutOfBounds exception is thrown.

Note that duplicate elements are not allowed in RFC 5424, and as such attempts to set an Element of an Entry which already contains another Element with the same name will result in a DuplicateElement exception.

Available since release v1.6.0.

Parameters

index	The index to set.
element	The Element to put at index.

Returns: The modified Entry.

◆ SetFacility()

Entry & stumpless::Entry::SetFacility ( Facility facility )

Sets the Facility of this Entry.

Available since release v1.6.0.

Parameters

facility The new Facility of this Entry.

Returns: The modified Entry.

◆ SetMessage()

Entry & stumpless::Entry::SetMessage	(	const char *	message,
			... )

Sets the message of an Entry.

Parameters

message	The new message to set on the entry. The message may contain any format specifiers valid in printf. If this is NULL, then it will be blank in the entry (no characters). This also means that characters such as % need to be escaped as they would be in printf.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

Returns: The modified Entry.

◆ SetMsgid()

Entry & stumpless::Entry::SetMsgid ( const char * msgid )

Sets the msgid for this Entry.

Available since release v1.6.0.

Parameters

msgid A NULL-terminated string holding the new msgid. This will be copied in to the Entry, and therefore may be modified or freed after this call without affecting the entry. If this is NULL, then a single '-' character will be used, as specified as the NILVALUE in RFC 5424.

Returns: The modified Entry.

◆ SetParam()

Entry & stumpless::Entry::SetParam	(	size_t	element_index,
		size_t	param_index,
		Param &	param )

Puts the Param in the Element at the given index of this Entry.

A Param cannot be set at an index position that does not already hold one. If this is attempted, then an IndexOutOfBounds exception is thrown.

Available since release v1.6.0.

Parameters

element_index	The index of the Element to set the Param on.
param_index	The index of the Param to set.
param	The new Param.

Returns: The modified Entry.

◆ SetParamValue() [1/2]

Entry & stumpless::Entry::SetParamValue	(	const char *	element_name,
		const char *	param_name,
		const char *	value )

Sets the value of the first Param with the given name in the Element with the given name in this Entry.

If an Element with the given name is not found, one is created with the supplied name and added to the end of this Entry.

If a Param of the given name is not found in the named Element, one is created with the supplied name and value and added to the end of the Element.

If you need to set the value of a Param with this name other than the first one, then you will need to loop through the Params using GetParam with an index to find the necessary ones, and then use SetParamValue with the correct index.

Available since release v1.6.0.

Parameters

element_name	The name of the Element to set the Param value on.
param_name	The name of the Param to set the value of.
value	The new value of the Param.

Returns: The modified Entry.

◆ SetParamValue() [2/2]

Entry & stumpless::Entry::SetParamValue	(	size_t	element_index,
		size_t	param_index,
		const char *	value )

Sets the value of the Param in the Element at the given index of this Entry.

Available since release v1.6.0.

Parameters

element_index	The index of the Element to set the Param value on.
param_index	The index of the Param to set the value of.
value	The new value of the Param.

Returns: The modified Entry.

◆ SetPriority()

Entry & stumpless::Entry::SetPriority	(	Facility	facility,
		Severity	severity )

Sets the Facility and Severity of this Entry.

Available since release v1.6.0.

Parameters

facility	The new Facility of this Entry.
severity	The new Severity of this Entry.

Returns: The modified Entry.

◆ SetPrival()

Entry & stumpless::Entry::SetPrival ( int prival )

Sets the prival of this Entry, as defined in RFC 5424.

Available since release v1.6.0.

Parameters

prival The new prival of this Entry.

Returns: The modified Entry.

◆ SetSeverity()

Entry & stumpless::Entry::SetSeverity ( Severity severity )

Sets the Severity of this Entry.

Available since release v1.6.0.

Parameters

severity The new Severity of this Entry.

Returns: The modified Entry.

Member Data Documentation

◆ equivalent

struct stumpless_entry* stumpless::Entry::equivalent

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

Entry.hpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Entry() [1/3]

◆ Entry() [2/3]

◆ Entry() [3/3]

◆ ~Entry()

Member Function Documentation

◆ AddElement() [1/3]

◆ AddElement() [2/3]

◆ AddElement() [3/3]

◆ AddParam()

◆ GetAppName()

◆ GetElement() [1/2]

◆ GetElement() [2/2]

◆ GetElementCount()

◆ GetElementIndex()

◆ GetFacility()

◆ GetMessage()

◆ GetMsgid()

◆ GetParam() [1/2]

◆ GetParam() [2/2]

◆ GetParamValue() [1/2]

◆ GetParamValue() [2/2]

◆ GetPrival()

◆ GetSeverity()

◆ HasElement()

◆ SetAppName()

◆ SetElement()

◆ SetFacility()

◆ SetMessage()

◆ SetMsgid()

◆ SetParam()

◆ SetParamValue() [1/2]

◆ SetParamValue() [2/2]

◆ SetPriority()

◆ SetPrival()

◆ SetSeverity()

Member Data Documentation

◆ equivalent