Network targets allow traditional syslog messages to be sent to a remote server. More...

#include <NetworkTarget.hpp>

Public Member Functions
	NetworkTarget (struct stumpless_target *equivalent)

	NetworkTarget (const char name, const char destination, NetworkProtocol network_protocol, TransportProtocol transport_protocol)
	Creates a new network target with the given parameters and opens it.

	~NetworkTarget (void)
	Closes this target and releases all memory and other resources held by it.

const char *	GetDefaultAppName (void)
	Returns the default app name used by this target.

const char *	GetDefaultMsgid (void)
	Returns the default msgid used by this target.

Facility	GetDefaultFacility (void)
	Gets the default facility of this target.

stumpless_filter_func_t	GetFilter (void)
	Returns the current filter used by this target to determine if entries should be allowed through it.

int	GetMask (void)
	Gets the log mask of this target.

const char *	GetName (void)
	Returns the name of this target.

int	GetOption (int option)
	Gets the given option for this target.

bool	IsOpen (void)
	Checks to see if this target is open.

NetworkTarget &	Log (const char *message,...)
	Writes a string message to this target.

NetworkTarget &	Log (int priority, const char *message,...)
	Writes a log message with the given priority to this target.

NetworkTarget &	Log (Facility facility, Severity severity, const char *message,...)
	Writes a log message with the given facility and severity to this target.

NetworkTarget &	Log (Entry entry)
	Writes an Entry to this target.

void	Open (void)
	Opens this target if it has been paused.

NetworkTarget &	SetDefaultAppName (const char *app_name)
	Sets the default app name for this target.

NetworkTarget &	SetDefaultFacility (int facility)
	Sets the default facility of the target.

NetworkTarget &	SetDefaultMsgid (const char *msgid)
	Sets the default message id for this target.

NetworkTarget &	SetFilter (stumpless_filter_func_t filter)
	Sets the filter used by this target to determine whether entries should be logged to it.

NetworkTarget &	SetMask (int mask)
	Sets the log mask of a target.

NetworkTarget &	SetOption (int option)
	Sets an option on a target.

NetworkTarget &	UnsetOption (int option)
	Unsets an option on a target.

const char *	GetDestination (void)
	Gets the destination of the target.

const char *	GetTransportPort (void)
	Gets the transport port number of the target.

size_t	GetUdpMaxMessageSize (void)
	Gets the current maximum message size of a UDP network target.

NetworkTarget &	SetDestination (const char *destination)
	Sets the destination of the target.

NetworkTarget &	SetTransportPort (const char *port)
	Sets the transport port of the target.

NetworkTarget &	SetUdpMaxMessageSize (size_t max_msg_size)
	Sets the maximum message size of a UDP network target.

Static Public Member Functions
static NetworkTarget	NewPausedTarget (const char *name, NetworkProtocol network_protocol, TransportProtocol transport_protocol)
	Creates a new network target with the given parameters but does not open it.

static NetworkTarget	NewPausedTcp4Target (const char *name)
	Creates a new network target using TCP over IPv4 with the given name.

static NetworkTarget	NewPausedTcp6Target (const char *name)
	Creates a new network target using TCP over IPv6 with the given name.

static NetworkTarget	NewPausedUdp4Target (const char *name)
	Creates a new network target using UDP over IPv4 with the given name.

static NetworkTarget	NewPausedUdp6Target (const char *name)
	Creates a new network target using UDP over IPv6 with the given name.

static NetworkTarget	OpenTcp4Target (const char name, const char destination)
	Creates a new network network target using TCP over IPv4 with the given parameters and opens it.

static NetworkTarget	OpenTcp6Target (const char name, const char destination)
	Creates a new network network target using TCP over IPv6 with the given parameters and opens it.

static NetworkTarget	OpenUdp4Target (const char name, const char destination)
	Creates a new network network target using UDP over IPv4 with the given parameters and opens it.

static NetworkTarget	OpenUdp6Target (const char name, const char destination)
	Creates a new network network target using UDP over IPv6 with the given parameters and opens it.

Public Attributes
struct stumpless_target *	equivalent

Static Public Attributes
static const char *	DEFAULT_TRANSPORT_PORT
	The default transport port for network targets.

static const size_t	DEFAULT_UDP_MAX_MESSAGE_SIZE
	The default message size for UDP network targets.

Detailed Description

Network targets allow traditional syslog messages to be sent to a remote server.

These can use either UDP or TCP over either IPv4 or IPv6.

Constructor & Destructor Documentation

◆ NetworkTarget() [1/2]

stumpless::NetworkTarget::NetworkTarget ( struct stumpless_target * equivalent )

◆ NetworkTarget() [2/2]

stumpless::NetworkTarget::NetworkTarget	(	const char *	name,
		const char *	destination,
		NetworkProtocol	network_protocol,
		TransportProtocol	transport_protocol )

Creates a new network target with the given parameters and opens it.

Parameters

name	The name of this network target.
destination	The destination to send messages to. This could be a hostname or an IP address.
network_protocol	The network protocol to use.
transport_protocol	The transport protocol to use.

◆ ~NetworkTarget()

stumpless::NetworkTarget::~NetworkTarget ( void )

Closes this target and releases all memory and other resources held by it.

Member Function Documentation

◆ GetDefaultAppName()

const char * stumpless::NetworkTarget::GetDefaultAppName ( void )

Returns the default app name used by this target.

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 default app name of this target.

◆ GetDefaultFacility()

Facility stumpless::NetworkTarget::GetDefaultFacility ( void )

Gets the default facility of this target.

Returns: The default facility of this target.

◆ GetDefaultMsgid()

const char * stumpless::NetworkTarget::GetDefaultMsgid ( void )

Returns the default msgid used by this target.

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 default msgid of this target.

◆ GetDestination()

const char * stumpless::NetworkTarget::GetDestination ( void )

Gets the destination of the target.

Returns: The current destination of the target.

◆ GetFilter()

stumpless_filter_func_t stumpless::NetworkTarget::GetFilter ( void )

Returns the current filter used by this target to determine if entries should be allowed through it.

Note that NULL is a valid return value from this function, indicating that the target does not currently have a filter set. Available since release v2.1.0.

Returns: The filter function in use by this target.

◆ GetMask()

int stumpless::NetworkTarget::GetMask ( void )

Gets the log mask of this target.

The mask is a bit field of severities that this target will allow if the default mask-based filter is in use. These can be formed and checked using the STUMPLESS_SEVERITY_MASK and STUMPLESS_SEVERITY_MASK_UPTO macros, and combining them using bitwise or operations. Available since release v2.1.0.

Returns: The current mask of this target.

◆ GetName()

const char * stumpless::NetworkTarget::GetName ( void )

Returns the name of this target.

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 name of this Target.

◆ GetOption()

int stumpless::NetworkTarget::GetOption ( int option )

Gets the given option for this target.

While the returned value is the option if it is set, callers can also simply use the truth value of the return to see if the provided option is set.

Parameters

option The option to check this target for.

Returns: The option if it is set on the target. If the option is not set, then zero is returned.

◆ GetTransportPort()

const char * stumpless::NetworkTarget::GetTransportPort ( void )

Gets the transport port number of the target.

Returns: The current port number of the network taret, encoded as a NULL-terminated string.

◆ GetUdpMaxMessageSize()

size_t stumpless::NetworkTarget::GetUdpMaxMessageSize ( void )

Gets the current maximum message size of a UDP network target.

Returns: The current maximum message size of the target.

◆ IsOpen()

bool stumpless::NetworkTarget::IsOpen ( void )

Checks to see if this target is open.

Returns: True if the target is open, false otherwise.

◆ Log() [1/4]

NetworkTarget & stumpless::NetworkTarget::Log	(	const char *	message,
			... )

Writes a string message to this target.

Parameters

message	The message to log, optionally containing any format specifiers valid in printf. This may be NULL, in which case an event with no message is logged.
...	Substitutions for any format specifiers provided in message. The number of substitutions provided must exactly match the number of specifiers given.

Returns: The modified target.

◆ Log() [2/4]

NetworkTarget & stumpless::NetworkTarget::Log ( Entry entry )

Writes an Entry to this target.

Parameters

entry the entry to write

Returns: The modified target.

◆ Log() [3/4]

NetworkTarget & stumpless::NetworkTarget::Log	(	Facility	facility,
		Severity	severity,
		const char *	message,
			... )

Writes a log message with the given facility and severity to this target.

Parameters

facility	The facility code of the message.
severity	The severity code of the message.
message	The message to log, optionally containing any format specifiers valid 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 target.

◆ Log() [4/4]

NetworkTarget & stumpless::NetworkTarget::Log	(	int	priority,
		const char *	message,
			... )

Writes a log message with the given priority to this target.

Parameters

priority	The priority of the message, described in RFC 5424 as the PRIVAL. This should be the bitwise or of the integer values of a Facility and a Severity.
message	The message to log, optionally containing any format specifiers valid 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 target.

◆ NewPausedTarget()

static NetworkTarget stumpless::NetworkTarget::NewPausedTarget	(	const char *	name,
		NetworkProtocol	network_protocol,
		TransportProtocol	transport_protocol )

static

Creates a new network target with the given parameters but does not open it.

This function is useful if additional settings need to be set before initiating a network connection, such as the transport port or the maximum UDP message size.

Parameters

name	The name of this network target.
network_protocol	The network protocol to use.
transport_protocol	The transport protocol to use.

Returns: The newly created NetworkTarget.

◆ NewPausedTcp4Target()

static NetworkTarget stumpless::NetworkTarget::NewPausedTcp4Target ( const char * name )

static

Creates a new network target using TCP over IPv4 with the given name.

This is equivalent to calling NewPausedTarget with NetworkProtocol::IPV4 and TransportProtocol::TCP as parameters.

Parameters

name	The name of this network target.

Returns: The newly created NetworkTarget.

◆ NewPausedTcp6Target()

static NetworkTarget stumpless::NetworkTarget::NewPausedTcp6Target ( const char * name )

static

Creates a new network target using TCP over IPv6 with the given name.

This is equivalent to calling NewPausedTarget with NetworkProtocol::IPV6 and TransportProtocol::TCP as parameters.

Parameters

name	The name of this network target.

Returns: The newly created NetworkTarget.

◆ NewPausedUdp4Target()

static NetworkTarget stumpless::NetworkTarget::NewPausedUdp4Target ( const char * name )

static

Creates a new network target using UDP over IPv4 with the given name.

This is equivalent to calling NewPausedTarget with NetworkProtocol::IPV4 and TransportProtocol::UDP as parameters.

Parameters

name	The name of this network target.

Returns: The newly created NetworkTarget.

◆ NewPausedUdp6Target()

static NetworkTarget stumpless::NetworkTarget::NewPausedUdp6Target ( const char * name )

static

Creates a new network target using UDP over IPv6 with the given name.

This is equivalent to calling NewPausedTarget with NetworkProtocol::IPV6 and TransportProtocol::UDP as parameters.

Parameters

name	The name of this network target.

Returns: The newly created NetworkTarget.

◆ Open()

void stumpless::NetworkTarget::Open ( void )

Opens this target if it has been paused.

◆ OpenTcp4Target()

static NetworkTarget stumpless::NetworkTarget::OpenTcp4Target	(	const char *	name,
		const char *	destination )

static

Creates a new network network target using TCP over IPv4 with the given parameters and opens it.

This is equivalent to calling the constructor with NetworkProtocol::IPV4 and TransportProtocol::TCP as parameters.

Parameters

name	The name of this network target.
destination	The destination to send messages to. This could be a hostname or an IP address.

Returns: The newly created NetworkTarget.

◆ OpenTcp6Target()

static NetworkTarget stumpless::NetworkTarget::OpenTcp6Target	(	const char *	name,
		const char *	destination )

static

Creates a new network network target using TCP over IPv6 with the given parameters and opens it.

This is equivalent to calling the constructor with NetworkProtocol::IPV6 and TransportProtocol::TCP as parameters.

Parameters

name	The name of this network target.
destination	The destination to send messages to. This could be a hostname or an IP address.

Returns: The newly created NetworkTarget.

◆ OpenUdp4Target()

static NetworkTarget stumpless::NetworkTarget::OpenUdp4Target	(	const char *	name,
		const char *	destination )

static

Creates a new network network target using UDP over IPv4 with the given parameters and opens it.

This is equivalent to calling the constructor with NetworkProtocol::IPV4 and TransportProtocol::UDP as parameters.

Parameters

name	The name of this network target.
destination	The destination to send messages to. This could be a hostname or an IP address.

Returns: The newly created NetworkTarget.

◆ OpenUdp6Target()

static NetworkTarget stumpless::NetworkTarget::OpenUdp6Target	(	const char *	name,
		const char *	destination )

static

Creates a new network network target using UDP over IPv6 with the given parameters and opens it.

This is equivalent to calling the constructor with NetworkProtocol::IPV6 and TransportProtocol::UDP as parameters.

Parameters

name	The name of this network target.
destination	The destination to send messages to. This could be a hostname or an IP address.

Returns: The newly created NetworkTarget.

◆ SetDefaultAppName()

NetworkTarget & stumpless::NetworkTarget::SetDefaultAppName ( const char * app_name )

Sets the default app name for this target.

Parameters

app_name The new default app name, as a NULL-terminated string.

Returns: The modified target.

◆ SetDefaultFacility()

NetworkTarget & stumpless::NetworkTarget::SetDefaultFacility ( int facility )

Sets the default facility of the target.

Parameters

facility The default facility for the target to use. This should be a STUMPLESS_FACILITY value.

Returns: The modified target.

◆ SetDefaultMsgid()

NetworkTarget & stumpless::NetworkTarget::SetDefaultMsgid ( const char * msgid )

Sets the default message id for this target.

Parameters

msgid The new default message id, as a NULL-terminated string.

Returns: The modified target.

◆ SetDestination()

NetworkTarget & stumpless::NetworkTarget::SetDestination ( const char * destination )

Sets the destination of the target.

If the target is already open when this function is called, then it will attempt to re-open the target after the destination is changed. If the target is in a paused state, then it will be left that way until an explicit call to Open is made.

Parameters

destination The new destination to use.

Returns: The modified target.

◆ SetFilter()

NetworkTarget & stumpless::NetworkTarget::SetFilter ( stumpless_filter_func_t filter )

Sets the filter used by this target to determine whether entries should be logged to it.

Available since release v2.1.0.

Parameters

filter The new filter to use for this target.

Returns: The modified target.

◆ SetMask()

NetworkTarget & stumpless::NetworkTarget::SetMask ( int mask )

Sets the log mask of a target.

The mask is a bit field of severities that this target will allow if the default mask-based filter is in use. These can be formed and checked using the STUMPLESS_SEVERITY_MASK and STUMPLESS_SEVERITY_MASK_UPTO macros, and combining them using bitwise or operations. Available since release v2.1.0.

Parameters

mask	The new mask to use for this target.

Returns: The modified target.

◆ SetOption()

NetworkTarget & stumpless::NetworkTarget::SetOption ( int option )

Sets an option on a target.

Parameters

option The option to set. This should be a STUMPLESS_OPTION value.

Returns: The modified target.

◆ SetTransportPort()

NetworkTarget & stumpless::NetworkTarget::SetTransportPort ( const char * port )

Sets the transport port of the target.

If the target is already open when this function is called, then it will attempt to re-open the target after the port is changed. If the target is in a paused state, then it will be left that way until an explicit call to Open is made.

Parameters

port	The new port to use. as a NULL-terminated string.

Returns: The modified target.

◆ SetUdpMaxMessageSize()

NetworkTarget & stumpless::NetworkTarget::SetUdpMaxMessageSize ( size_t max_msg_size )

Sets the maximum message size of a UDP network target.

Messages that are longer than the maximum size are truncated to this length. If the underlying transport for a network target can support a larger datagram and you need support for longer messages, then you can use this option to increase the size. Likewise, the option can be used to force smaller datagrams if needed, for example in the case of extra overhead in the IP header beyond the typical 20 bytes. Note that truncations due to the maximum size do not take UTF characters into account. If you have entries using multi-byte characters, then you need to be sure that these truncations do not cause parsing or security problems. Without calling this function, UDP targets start with a maximum message size set to DEFAULT_UDP_MAX_MESSAGE_SIZE.

Parameters

max_msg_size The new maximum message size for this target.

Returns: The modified target.

◆ UnsetOption()

NetworkTarget & stumpless::NetworkTarget::UnsetOption ( int option )

Unsets an option on a target.

Parameters

option The option to unset. This should be a STUMPLESS_OPTION value.

Returns: The modified target.

Member Data Documentation

◆ DEFAULT_TRANSPORT_PORT

const char* stumpless::NetworkTarget::DEFAULT_TRANSPORT_PORT

static

The default transport port for network targets.

This is based largely on tradition, but some applications may expect a different port (for example 1514 and 6514 are sometimes used). If a different port is needed on a target, use SetTransportPort to change it.

◆ DEFAULT_UDP_MAX_MESSAGE_SIZE

const size_t stumpless::NetworkTarget::DEFAULT_UDP_MAX_MESSAGE_SIZE

static

The default message size for UDP network targets.

This is set to account for an MTU of 1500 bytes, a 20 byte IP header, and an 8 byte datagram header. If you wish to change this value for a particular target, then you must use SetUdpMaxMessageSize to change it.

◆ equivalent

struct stumpless_target* stumpless::NetworkTarget::equivalent

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

NetworkTarget.hpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ NetworkTarget() [1/2]

◆ NetworkTarget() [2/2]

◆ ~NetworkTarget()

Member Function Documentation

◆ GetDefaultAppName()

◆ GetDefaultFacility()

◆ GetDefaultMsgid()

◆ GetDestination()

◆ GetFilter()

◆ GetMask()

◆ GetName()

◆ GetOption()

◆ GetTransportPort()

◆ GetUdpMaxMessageSize()

◆ IsOpen()

◆ Log() [1/4]

◆ Log() [2/4]

◆ Log() [3/4]

◆ Log() [4/4]

◆ NewPausedTarget()

◆ NewPausedTcp4Target()

◆ NewPausedTcp6Target()

◆ NewPausedUdp4Target()

◆ NewPausedUdp6Target()

◆ Open()

◆ OpenTcp4Target()

◆ OpenTcp6Target()

◆ OpenUdp4Target()

◆ OpenUdp6Target()

◆ SetDefaultAppName()

◆ SetDefaultFacility()

◆ SetDefaultMsgid()

◆ SetDestination()

◆ SetFilter()

◆ SetMask()

◆ SetOption()

◆ SetTransportPort()

◆ SetUdpMaxMessageSize()

◆ UnsetOption()

Member Data Documentation

◆ DEFAULT_TRANSPORT_PORT

◆ DEFAULT_UDP_MAX_MESSAGE_SIZE

◆ equivalent