Copyright (C) Kevin Larke 2009-2020

This file is part of libcm.

libcm is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

libcm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See the GNU General Public License distributed with the libcm package or look here: .

cmErr : Format error messages and track the last error generated.

This class is used to format error messages and track the last error generated.

Most of the cmHandle_t based classes use cmErr_t to format error messages with a title, maintain the last result code which indicated an error, and to hold a cmRpt_t object to manage application supplied text printing callbacks.




typedef struct
{
  cmRpt_t*        rpt;        // Pointer to a cmRpt_t object which is used to direct error messages to an application supplied console.
  const cmChar_t* label;      // This field contains a pointer to a text label used to form the error message title.
  cmRC_t          rc;         // This is the last result code passed via one of the cmErrXXXMsg() functions.
  cmRC_t          warnRC;     // Last warning RC
} cmErr_t;

// Setup a cmErr_t record.
//
// Note that rpt and staticLabelStr must point to client supplied objects
// whose lifetime is at least that of this cmErr_t object. 
void cmErrSetup( cmErr_t* err, cmRpt_t* rpt, const cmChar_t* staticLabelStr );

// Duplicate a cmErr_t record.
void cmErrClone( cmErr_t* dstErr, const cmErr_t* srcErr );

// Error Reporting functions:
// Functions to signal an error. The rc argument is generally specific to the 
// client class using the error.  See the kXXXRC enumerations in the handle based
// classes for examples of result codes.
cmRC_t cmErrMsg( cmErr_t* err, cmRC_t rc, const cmChar_t* fmt, ... );
cmRC_t cmErrVMsg(cmErr_t* err, cmRC_t rc, const cmChar_t* fmt, va_list vl );


// Report Errors which contain accompanying system error codes.
// Use these functions when a system error (e.g. Unix errno) gives additional information
// about the source of the error. 
cmRC_t cmErrSysMsg( cmErr_t* err, cmRC_t rc, cmSysErrCode_t sysErrCode, const cmChar_t* fmt, ... );
cmRC_t cmErrVSysMsg(cmErr_t* err, cmRC_t rc, cmSysErrCode_t sysErrCode, const cmChar_t* fmt, va_list vl );

// Warning Reporting functions:
// Errors generally result in a task aborting. Warnings are informative but the task is
// expected to continue.
// Functions to signal a warning. The rc argument is generally specific to the 
// client class using the error.  See the kXXXRC enumerations in the handle based
// classes for examples of result codes.
cmRC_t cmErrWarnMsg( cmErr_t* err, cmRC_t rc, const cmChar_t* fmt, ... );
cmRC_t cmErrWarnVMsg(cmErr_t* err, cmRC_t rc, const cmChar_t* fmt, va_list vl );


// Report warnings which contain accompanying system error codes.
// Use these functions when a system error (e.g. Unix errno) gives additional information
// about the source of the error. 
cmRC_t cmErrWarnSysMsg( cmErr_t* err, cmRC_t rc, cmSysErrCode_t sysErrCode, const cmChar_t* fmt, ... );
cmRC_t cmErrWarnVSysMsg(cmErr_t* err, cmRC_t rc, cmSysErrCode_t sysErrCode, const cmChar_t* fmt, va_list vl );

// Return the last recorded RC.
cmRC_t cmErrLastRC( cmErr_t* err );

// Return the last recorded RC and set it to a new value.
cmRC_t cmErrSetRC( cmErr_t* err, cmRC_t rc );

// Return the last recorded RC and set it to cmOkRC.
cmRC_t cmErrClearRC( cmErr_t* err );