BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_diaghandler
Next|Prev|Up
The Structure
Members
Operations
BrDiagHandlerSet()
Copy/Assign
Access & Maintenance
Referencing & Lifetime
Initialisation
Construction & Destruction
Supplementary

br_diaghandler


The Structure

This structure represents the definition of a diagnostic handler. All BRender's diagnostics are handled by just two functions, which can be specified by the programmer. This is essential in cases where stdout and stderr (as used by the standard C library functions) are not available (or not suitable).

The typedef

(See brdiag.h for precise declaration and ordering)

Handling Functions

br_diag_warning_cbfn * warning Warning delivery function

br_diag_failure_cbfn * failure Failure delivery function

Supplementary

char * identifier Diagnostic handler name

Members

Handling Functions

br_diag_warning_cbfn * warning

This is a pointer to the warning delivery function (See br_diag_warning_cbfn114). This is invoked by the warning macros (See Diagnostic Support, page 65).

br_diag_failure_cbfn * failure

This is a pointer to the failure delivery function (See br_diag_failure_cbfn113). This is invoked by the failure, fatal and assertion macros (See Diagnostic Support).

Supplementary

char * identifier

Pointer to unique, zero terminated, character string (or Null if not required). A string constant is recommended.

Operations


BrDiagHandlerSet()

Description:
Install a new diagnostic handler.

Declaration:
br_diaghandler* BrDiagHandlerSet(br_diaghandler* newdh)

Arguments:
br_diaghandler * newdh

A pointer to an instance of a br_diaghandler115 structure (should really be static). If Null the default diagnostic handler will be used (uses the standard C I/O library).

Result:
br_diaghandler *

Returns a pointer to the old diagnostic handler (possibly Null). This may be used to pass diagnostics on, if desired.

Remarks:
The diagnostic handler may be specified at any suitable time. BrBegin()10 will specify a default diagnostic handler if no handler is currently defined.

Note that diagnostics generated without a diagnostic handler present will only be caught in the debug build.

If not BrBegin()10, This should be the first BRender function called.

You should cater for the circumstance arising, if in the process of handling diagnostics, your diagnostic handler may call functions that may themselves generate diagnostics.


Copy/Assign

Beware of copying the structure if identifier has been allocated from the heap.

Access & Maintenance

While the structure is the current handler (most recently passed to BrDiagHandlerSet()116) the members should not be changed. No maintenance required.

Referencing & Lifetime

The structure must remain valid at least until a new handler is passed to BrDiagHandlerSet()116, and may need to remain valid longer if a newer diagnostic handler uses it to pass diagnostics on.

Initialisation

The members should be set before the structure is passed to BrDiagHandlerSet()116.

Construction & Destruction

The structure should ideally be statically constructed.

Supplementary

The identifier may be used to determine the current handler in use.


Generated with
CERN WebMaker