\r\n

51Degrees Device Detection C/C++  4.5

A device detection library that is used natively or by 51Degrees products

Exceptions

Detailed Description

Allow the bubbling up or errors in C.

Introduction

An exception structure is used to allow the bubbling up of errors, as C does not support exceptions in that way. This means that instead of an error causing a segmentation fault elsewhere, the exception is set and passed all the way up to be checked.

Creating

Exceptions are created by the caller using the FIFTYONE_DEGREES_EXCEPTION_CREATE macro which creates an exception pointer named "exception". This is then passed into any method which can potentially throw an exception.

Checking

An exception can be checked using the FIFTYONE_DEGREES_EXCEPTION_OKAY macro which will return true if there is no exception, or false if an exception has occurred.

Throwing

In the event that an exception has occurred in a method, it can be checked and thrown using the FIFTYONE_DEGREES_EXCEPTION_THROW macro. If the exception is okay, then nothing will be thrown by this macro, so it is safe to call as a "catch and throw" method. This will behave differently depending on whether it is used in the context of C or C++.

C : C does not support exceptions, so if there is an exception, the exception message will be printed to standard output, then the process will exit.

C++ : As C++ supports exceptions, a fatal exception with the message will be thrown. This can then be caught or handled in whichever way the caller sees fit.

Messages

The error message returned by an exception consists of the error message itself, the name of the source file which caused the error, the name of the function which caused the error and the line in the source file at which the error occurred.

Usage Example

// Create an exception
FIFTYONE_DEGREES_EXCEPTION_CREATE;
// Set the exception a failure status
FIFTYONE_DEGREES_EXCEPTION_SET(FIFTYONE_DEGREES_STATUS_NULL_POINTER);
// Check the exception
if (FIFTYONE_DEGREES_EXCEPTION_FAILED) {
// Throw the exception
FIFTYONE_DEGREES_EXCEPTION_THROW;
}

Disabling

To improve performance, exception handling can be disabled completely by compiling with FIFTYONE_DEGREES_EXCEPTIONS_DISABLED. This changes all the macro calls to do nothing, meaning that no checks occur, and no exceptions are thrown.

Collaboration diagram for Exceptions:

Structs

struct  fiftyoneDegreesException
Structure used to represent a 51Degrees exception and passed into methods that might generate exceptions. More...

Macros

#define  FIFTYONE_DEGREES_EXCEPTION_SET(s)
Macro used to set an exception to a status code. More...
#define  FIFTYONE_DEGREES_EXCEPTION_CLEAR
Macro used to clear an exception type. More...
#define  FIFTYONE_DEGREES_EXCEPTION_CHECK(t)   (exception == NULL || exception->status == t)
Macro used to check if an exception status equals the value of t. More...
#define  FIFTYONE_DEGREES_EXCEPTION_OKAY   FIFTYONE_DEGREES_EXCEPTION_CHECK(FIFTYONE_DEGREES_STATUS_NOT_SET)
Macro used to check if there is no exception currently.
#define  FIFTYONE_DEGREES_EXCEPTION_THROW   fiftyoneDegreesExceptionCheckAndExit(exception);
Macro to print to standard error a message if an exception is set.
#define  FIFTYONE_DEGREES_EXCEPTION_CREATE
Macro used to create an exception. More...
#define  FIFTYONE_DEGREES_EXCEPTION_FAILED   (FIFTYONE_DEGREES_EXCEPTION_OKAY == false)
Macro to test if the exception has been set and is failed.

Functions

const char *  fiftyoneDegreesExceptionGetMessage (fiftyoneDegreesException *exception)
Returns an English error message for the exception. More...
void  fiftyoneDegreesExceptionCheckAndExit (fiftyoneDegreesException *exception)
If the exception is set then will print a message to stderr and exit the process. More...

Macro Definition Documentation

◆ FIFTYONE_DEGREES_EXCEPTION_CHECK

#define FIFTYONE_DEGREES_EXCEPTION_CHECK (   t )    (exception == NULL || exception->status == t)

Macro used to check if an exception status equals the value of t.

Warning: this macro should be avoided in anything other than test code as when exceptions are disabled there will be unpredictable results. Using a local status variable for checks is a better pattern.

◆ FIFTYONE_DEGREES_EXCEPTION_CLEAR

#define FIFTYONE_DEGREES_EXCEPTION_CLEAR
Value:
{ \
exception->file = NULL; \
exception->func = NULL; \
exception->line = -1; \
exception->status = FIFTYONE_DEGREES_STATUS_NOT_SET; \
}
FIFTYONE_DEGREES_STATUS_NOT_SET
Should never be returned to the caller.
Definition: status.h:87

Macro used to clear an exception type.

◆ FIFTYONE_DEGREES_EXCEPTION_CREATE

#define FIFTYONE_DEGREES_EXCEPTION_CREATE
Value:
fiftyoneDegreesException exceptionValue; \
fiftyoneDegreesException *exception = &exceptionValue; \
FIFTYONE_DEGREES_EXCEPTION_CLEAR
fiftyoneDegreesException
Structure used to represent a 51Degrees exception and passed into methods that might generate excepti...
Definition: exceptions.h:111

Macro used to create an exception.

◆ FIFTYONE_DEGREES_EXCEPTION_SET

#define FIFTYONE_DEGREES_EXCEPTION_SET (   s )
Value:
if (exception != NULL) { \
exception->file = __FILE__; \
exception->func = __func__; \
exception->line = __LINE__; \
exception->status = s; \
}

Macro used to set an exception to a status code.

Parameters
s - status code to set

Function Documentation

◆ fiftyoneDegreesExceptionCheckAndExit()

void fiftyoneDegreesExceptionCheckAndExit ( fiftyoneDegreesException *   exception )

If the exception is set then will print a message to stderr and exit the process.

Parameters
exception - to check and exit if set

◆ fiftyoneDegreesExceptionGetMessage()

const char* fiftyoneDegreesExceptionGetMessage ( fiftyoneDegreesException *   exception )

Returns an English error message for the exception.

The caller must free the memory when they have finished consuming the error message.

Parameters
exception - to get a string message from
Returns
pointer to the newly allocated message string
On This Page

Generated by doxygen 1.8.15