Error report system. More...

#include <pmacros.h>
#include <ptypes.h>
#include <perrortypes.h>

Typedefs
typedef struct PError_	PError
	Opaque data structure for an error object.

Functions
P_LIB_API PError *	p_error_new (void)
	Initializes a new empty PError.

P_LIB_API PError *	p_error_new_literal (pint code, pint native_code, const pchar *message)
	Initializes a new PError with data.

P_LIB_API const pchar *	p_error_get_message (const PError *error)
	Gets an error message.

P_LIB_API pint	p_error_get_code (const PError *error)
	Gets an error code.

P_LIB_API pint	p_error_get_native_code (const PError *error)
	Gets a platform native error code, if any.

P_LIB_API PErrorDomain	p_error_get_domain (const PError *error)
	Gets an error domain.

P_LIB_API PError *	p_error_copy (const PError *error)
	Creates a copy of a PError object.

P_LIB_API void	p_error_set_error (PError error, pint code, pint native_code, const pchar message)
	Sets error data.

P_LIB_API void	p_error_set_error_p (PError *error, pint code, pint native_code, const pchar message)
	Sets error data through a double pointer.

P_LIB_API void	p_error_set_code (PError *error, pint code)
	Sets an error code.

P_LIB_API void	p_error_set_native_code (PError *error, pint native_code)
	Sets a platform native error code.

P_LIB_API void	p_error_set_message (PError error, const pchar message)
	Sets an error message.

P_LIB_API void	p_error_clear (PError *error)
	Clears error data.

P_LIB_API void	p_error_free (PError *error)
	Frees a previously initialized error object.

P_LIB_API pint	p_error_get_last_system (void)
	Gets the last system native error code.

P_LIB_API pint	p_error_get_last_net (void)
	Gets the last network native error code.

P_LIB_API void	p_error_set_last_system (pint code)
	Sets the last system native error code.

P_LIB_API void	p_error_set_last_net (pint code)
	Sets the last network native error code.

Detailed Description

Error report system.

Author: Alexander Saprykin

An error report system is used to notify a caller about fatal situations during the library API invocation. Usually the sequence is as following:

PError *error = NULL;
...
 
if (error != NULL) {
        ...
        p_error_free (error);
}

Note that you should not initialize a new PError object before passing the pointer into an API call. Simply initialize it with zero and check the result after. Therefore you need to free memory if an error occurred.

Most operating systems store the last error code of the most system calls in a thread-specific variable. Moreover, Windows stores the error code of the last socket related call in a separate variable. Use p_error_get_last_system() and p_error_set_last_system() to access the last system error code, p_error_get_last_net() and p_error_set_last_net() to access the last network error code.

Definition in file perror.h.

Typedef Documentation

◆ PError

typedef struct PError_ PError

Opaque data structure for an error object.

Definition at line 68 of file perror.h.

Function Documentation

◆ p_error_clear()

P_LIB_API void p_error_clear ( PError * error )

Clears error data.

Parameters

error PError object to clear the data for.

Since: 0.0.1

Note: Error code is reseted to 0.

◆ p_error_copy()

P_LIB_API PError * p_error_copy ( const PError * error )

Creates a copy of a PError object.

Parameters

error PError object to copy.

Returns: Newly created PError object in case of success, NULL otherwise.

Since: 0.0.1

Note: The caller is responsible to free memory of the created object after usage.

◆ p_error_free()

P_LIB_API void p_error_free ( PError * error )

Frees a previously initialized error object.

Parameters

error PError object to free.

Since: 0.0.1

◆ p_error_get_code()

P_LIB_API pint p_error_get_code ( const PError * error )

Gets an error code.

Parameters

error PError object to get the code from.

Returns: Error code in case of success, 0 otherwise.

Since: 0.0.1

◆ p_error_get_domain()

P_LIB_API PErrorDomain p_error_get_domain ( const PError * error )

Gets an error domain.

Parameters

error PError object to get the domain from.

Returns: Error domain in case of success, P_ERROR_DOMAIN_NONE otherwise.

Since: 0.0.1

◆ p_error_get_last_net()

P_LIB_API pint p_error_get_last_net ( void )

Gets the last network native error code.

Returns: Last network native error code.

Since: 0.0.2

See also: p_error_get_last_system(), p_error_set_last_net(), p_error_set_last_system()

◆ p_error_get_last_system()

P_LIB_API pint p_error_get_last_system ( void )

Gets the last system native error code.

Returns: Last system native error code.

Since: 0.0.2

See also: p_error_get_last_net(), p_error_set_last_system(), p_error_set_last_net()

Note: If you want get an error code for socket-related calls, use p_error_get_last_net() instead.

◆ p_error_get_message()

P_LIB_API const pchar * p_error_get_message ( const PError * error )

Gets an error message.

Parameters

error PError object to get the message from.

Returns: Error message in case of success, NULL otherwise.

Since: 0.0.1

◆ p_error_get_native_code()

P_LIB_API pint p_error_get_native_code ( const PError * error )

Gets a platform native error code, if any.

Parameters

error PError object to get the native code from.

Returns: Error code in case of success, 0 otherwise.

Since: 0.0.1

Note: In some situations there can be no native code error, i.e. when an internal library call failed. Do not rely on this code.

◆ p_error_new()

P_LIB_API PError * p_error_new ( void )

Initializes a new empty PError.

Returns: Newly initialized PError object in case of success, NULL otherwise.

Since: 0.0.1

◆ p_error_new_literal()

P_LIB_API PError * p_error_new_literal	(	pint	code,
		pint	native_code,
		const pchar *	message )

Initializes a new PError with data.

Parameters

code	Error code.
native_code	Native error code, leave 0 to ignore.
message	Error message.

Returns: Newly initialized PError object in case of success, NULL otherwise.

Since: 0.0.1

◆ p_error_set_code()

P_LIB_API void p_error_set_code	(	PError *	error,
		pint	code )

Sets an error code.

Parameters

error	PError object to set the code for.
code	Error code.

Since: 0.0.1

◆ p_error_set_error()

P_LIB_API void p_error_set_error	(	PError *	error,
		pint	code,
		pint	native_code,
		const pchar *	message )

Sets error data.

Parameters

error	PError object to set the data for.
code	Error code.
native_code	Native error code, leave 0 to ignore.
message	Error message.

Since: 0.0.1

◆ p_error_set_error_p()

P_LIB_API void p_error_set_error_p	(	PError **	error,
		pint	code,
		pint	native_code,
		const pchar *	message )

Sets error data through a double pointer.

Parameters

error	PError object to set the data for.
code	Error code.
native_code	Native error code, leave 0 to ignore.
message	Error message.

Since: 0.0.1

If error is NULL it does nothing. If error is not NULL then *error should be NULL, otherwise it does nothing. It creates a PError object, sets error data and assigns it to *error. The caller is responsible to free memory of the created object after usage.

◆ p_error_set_last_net()

P_LIB_API void p_error_set_last_net ( pint code )

Sets the last network native error code.

Parameters

code	Error code to set.

Since: 0.0.2

See also: p_error_set_last_system(), p_error_get_last_net(), p_error_get_last_system()

◆ p_error_set_last_system()

P_LIB_API void p_error_set_last_system ( pint code )

Sets the last system native error code.

Parameters

code	Error code to set.

Since: 0.0.2

See also: p_error_set_last_net(), p_error_get_last_system(), p_error_get_last_net()

Note: If you want set an error code for socket-related calls, use p_error_set_last_net() instead.

◆ p_error_set_message()

P_LIB_API void p_error_set_message	(	PError *	error,
		const pchar *	message )

Sets an error message.

Parameters

error	PError object to set the message for.
message	Error message.

Since: 0.0.1

◆ p_error_set_native_code()

P_LIB_API void p_error_set_native_code	(	PError *	error,
		pint	native_code )

Sets a platform native error code.

Parameters

error	PError object to set the native error code for.
native_code	Platform native error code.

Since: 0.0.1

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ PError

Function Documentation

◆ p_error_clear()

◆ p_error_copy()

◆ p_error_free()

◆ p_error_get_code()

◆ p_error_get_domain()

◆ p_error_get_last_net()

◆ p_error_get_last_system()

◆ p_error_get_message()

◆ p_error_get_native_code()

◆ p_error_new()

◆ p_error_new_literal()

◆ p_error_set_code()

◆ p_error_set_error()

◆ p_error_set_error_p()

◆ p_error_set_last_net()

◆ p_error_set_last_system()

◆ p_error_set_message()

◆ p_error_set_native_code()