Basic defines, macros, and global functions for JabberWerxC. More...

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

Data Structures
struct	jw_err

Macros
#define	JABBERWERX_API

#define	UNUSED_PARAM(p) ((void)&(p))

#define	__attribute__(x)

#define	PRAGMA(x) _Pragma(#x)

#define	GCC_BEGIN_IGNORED_WARNING(x)

#define	GCC_END_IGNORED_WARNING(x)

#define	BASE10_WIDTH2(s) sizeof(#s)

#define	BASE10_WIDTH(s) BASE10_WIDTH2(s)

#define	UINT64_MAX_WIDTH BASE10_WIDTH(UINT64_MAX)

#define	UINT32_MAX_WIDTH BASE10_WIDTH(UINT32_MAX)

#define	JABBERWERX_ERROR(err, errcode)

Enumerations
enum	jw_errcode { JW_ERR_NONE = 0, JW_ERR_INVALID_ARG, JW_ERR_INVALID_STATE, JW_ERR_NO_MEMORY, JW_ERR_OVERFLOW, JW_ERR_SOCKET_CONNECT, JW_ERR_BAD_FORMAT, JW_ERR_PROTOCOL, JW_ERR_TIMEOUT, JW_ERR_NOT_AUTHORIZED, JW_ERR_NOT_IMPLEMENTED, JW_ERR_USER }

Functions
JABBERWERX_API const char *	jw_err_message (jw_errcode code)

JABBERWERX_API const char *	jw_version (bool full)

JABBERWERX_API bool	jw_global_init (jw_err *err)

JABBERWERX_API void	jw_global_cleanup ()

Detailed Description

Basic defines, macros, and global functions for JabberWerxC.

Copyrights

Macro Definition Documentation

#define __attribute__ ( x )

Hide GCC attribute definitions from non-GCC compilers

#define BASE10_WIDTH ( s ) BASE10_WIDTH2(s)

Dereferences a symbol so its value can be stringified

#define BASE10_WIDTH2 ( s ) sizeof(#s)

Calculates the length of a stringified symbol value, including the terminating NULL.

#define GCC_BEGIN_IGNORED_WARNING ( x )

This is a noop for non-gcc compilers

#define GCC_END_IGNORED_WARNING ( x )

This is a noop for non-gcc compilers

#define JABBERWERX_API

Marks a symbol as part of the public API.

#define JABBERWERX_ERROR	(	err,
		errcode
	)

Value:

GCC_BEGIN_IGNORED_WARNING(-Waddress) \
        if ((err) != NULL) \
        { \
            (err)->code = (errcode); \
            (err)->message = jw_err_message((errcode)); \
            (err)->function = __func__; \
            (err)->file = __FILE__; \
            (err)->line = __LINE__; \
        } \
    GCC_END_IGNORED_WARNING(-Waddress)

Macro to initialize an error context.

Parameters

err	The pointer to the error context, or NULL if none
errcode	The error code

#define PRAGMA ( x ) _Pragma(#x)

Compiler pragma helper.

Insert a C99 compiler pragma based on an unterminated string. This allows for pragmas to be generated dynamically.

#define UINT32_MAX_WIDTH BASE10_WIDTH(UINT32_MAX)

The size of a buffer large enough to hold a base 10 string version of the largest unsigned 32-bit value

#define UINT64_MAX_WIDTH BASE10_WIDTH(UINT64_MAX)

The size of a buffer large enough to hold a base 10 string version of the largest unsigned 64-bit value

#define UNUSED_PARAM ( p ) ((void)&(p))

A macro for quelling compiler warnings about unused variables.

Enumeration Type Documentation

enum jw_errcode

Enumeration of defined error codes.

Enumerator
JW_ERR_NONE	No error
JW_ERR_INVALID_ARG	argument was invalid (beyond invariants)
JW_ERR_INVALID_STATE	context is not in a valid state
JW_ERR_NO_MEMORY	out of memory
JW_ERR_OVERFLOW	buffer would overflow
JW_ERR_SOCKET_CONNECT	error connecting to a remote endpoint
JW_ERR_BAD_FORMAT	provided data could not be parsed by consuming entity
JW_ERR_PROTOCOL	invalid protocol
JW_ERR_TIMEOUT	timed out
JW_ERR_NOT_AUTHORIZED	authentication-related error
JW_ERR_NOT_IMPLEMENTED	functionality not implemented (often because of a compile-time switch
JW_ERR_USER	user-defined error. feel free to define specific user-defined errors as long as their values are greater than JW_ERR_USER

Function Documentation

JABBERWERX_API const char* jw_err_message ( jw_errcode code )

Retrieves the error message for the given error code.

Parameters

code	The error code to lookup

Return values

const char * The message for {code}

JABBERWERX_API void jw_global_cleanup ( )

Performs global cleanup of the JabberWerxC library and all used 3rd party libraries. This function can be called regardless of whether jw_global_init() was ever called. If this function is not called, valgrind may report memory leaks.

JABBERWERX_API bool jw_global_init ( jw_err * err )

Performs global initialization of the JabberWerxC library and sets the 3rd party libraries to use JWC memory allocator functions. It is currently not required to call this function or its cleanup counterpart, but eventually the proper functioning of JWC will depend on them. This function may be called multiple times, but will only have an effect the first time it is called or the first time it is called after jw_global_cleanup() is called.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if library stat could not be allocated.

Parameters

[out] err The error information (provide NULL to ignore).

Return values

bool	true if the library was initialized successfully.

JABBERWERX_API const char* jw_version ( bool full )

Retrieves the (runtime) version string of this library. This function can be called without first calling jw_global_init().

Parameters

full	true to return the full version (with build number), false to return the common version (without build number)

Return values

const char * The version string.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation