src/axl/axl_error.c

   1 /**
   2  *  LibAxl:  Another XML library
   3  *  Copyright (C) 2006 Advanced Software Production Line, S.L.
   4  *
   5  *  This program is free software; you can redistribute it and/or
   6  *  modify it under the terms of the GNU Lesser General Public License
   7  *  as published by the Free Software Foundation; either version 2.1 of
   8  *  the License, or (at your option) any later version.
   9  *
  10  *  This program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  *  GNU Lesser General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Lesser General Public
  16  *  License along with this program; if not, write to the Free
  17  *  Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  18  *  02111-1307 USA
  19  *
  20  *  You may find a copy of the license under this software is released
  21  *  at COPYING file. This is LGPL software: you are welcome to
  22  *  develop proprietary applications using this library without any
  23  *  royalty or fee but returning back any change, improvement or
  24  *  addition in the form of source code, project image, documentation
  25  *  patches, etc.
  26  *
  27  *  For commercial support on build XML enabled solutions contact us:
  28  *
  29  *      Postal address:
  30  *         Advanced Software Production Line, S.L.
  31  *         C/ Dr. Michavila Nº 14
  32  *         Coslada 28820 Madrid
  33  *         Spain
  34  *
  35  *      Email address:
  36  *         info@aspl.es - http://fact.aspl.es
  37  */
  38 #include <axl.h>
  39
  40 struct _axlError {
  41         int    code;
  42         char * error;
  43         int    defined;
  44 };
  45
  46 /**
  47  * \defgroup axl_error_module Axl Error report: Functions to help AXL library to report internal error to the application level.
  48  */
  49
  50 /**
  51  * \addtogroup axl_error_module
  52  * @{
  53  */
  54
  55 /**
  56  * @brief Allows to create a new \ref axlError value that contains an
  57  * error code and a error string.
  58  *
  59  * \ref axlError error reporting abstraction is a convenient way for
  60  * the developer and the user that makes use of the API to report and
  61  * get textual diagnostic errors produced. Many times, API provided do
  62  * not allow to get more information if something wrong happen making
  63  * it difficult to reach and solve the problem (including the
  64  * development phase).
  65  *
  66  * From a developer's perspective, here is how works \ref axlError,
  67  *
  68  * \code
  69  * void some_public_exported_function (int param, axlError ** error)
  70  * {
  71  *      // do some work, but if it fails call to produce the error
  72  *      // reporting.
  73  *      axl_error_new (-2,     // reporting an error code
  74  *                     "Something wasn't ok while processing..",
  75  *                     NULL,   // a reference to the stream (optional)
  76  *                     error); // variable received.
  77  *      return;
  78  * }
  79  * \endcode
  80  *
  81  * Previous construction makes error reporting optional but at the
  82  * same time, available, because the programmer doesn't requires to
  83  * check if the user did define the error variable, making it
  84  * available at user option.
  85  *
  86  * Now, if the user defines the \ref axlError reference, by calling to
  87  * the function, it can get the error reported as follows:
  88  *
  89  * \code
  90  * // declare the variable and it to null
  91  * axlError * error = NULL;
  92  *
  93  * // call to function
  94  * some_pulic_exported_function (10, &error);
  95  * if (! axl_error_was_ok (error)) {
  96  *     // drop the message
  97  *     printf ("Something has failed: (code: %d) %s\n",
  98  *             axl_error_get_code (error),
  99  *             axl_error_get (error));
 100  *     // dealloc the reference
 101  *     axl_error_free (error);
 102  * }
 103  * \endcode
 104  *
 105  * Alternatively, the user can just bypass the error reporting
 106  * mechanism, without affecting the written code inside the source of
 107  * the function supporting the \ref axlError notification (even if the
 108  * code calls to \ref axl_error_new):
 109  *
 110  * \code
 111  * // call to the function without error reporting
 112  * some_pulic_exported_function (10, NULL);
 113  * \endcode
 114  *
 115  * In most cases, \ref axl_error_new is not used by API consumers but
 116  * by API developers. Once returned the \ref axlError reference the
 117  * following functions could be checked.
 118  *
 119  * - \ref axl_error_get returns textual diagnostic reported.
 120  *
 121  * - \ref axl_error_get_code returns error code reported.
 122  *
 123  * - \ref axl_error_was_ok allows to check if some error was
 124  * reported, base on the value initialization.
 125  *
 126  *
 127  *
 128  * @param code The error code to set and the error code string.
 129  *
 130  * @param error_code String to report.
 131  *
 132  * @param stream If provided, the error will try to get current stream
 133  * position to add more information to the place where the error was
 134  * found.
 135  *
 136  * @param _error The error string to be used to initialize the received \ref axlError.
 137  */
 138 void axl_error_new (int code, char * error_code, axlStream * stream, axlError ** _error)
 139 {
 140         axlError * error;
 141         char     * following;
 142
 143         /* get a reference to the error to be created */
 144         if (_error == NULL)
 145                 return;
 146
 147         /* create the error to be reported */
 148         error             = axl_new (axlError, 1);
 149         error->code       = code;
 150         error->defined    = -346715;
 151         if (stream == NULL) {
 152                 /* allocate enough memory */
 153                 error->error = axl_strdup (error_code);
 154         } else {
 155                 /* get the following */
 156                 following    = axl_stream_get_following (stream, 10);
 157
 158                 /* alloc enough memory */
 159                 error->error = axl_stream_strdup_printf ("Error found (stream size: %d, at byte %d (global index: %d), near to ...%s..., while reading: %s): %s\n",
 160                                                          axl_stream_get_size (stream),
 161                                                          axl_stream_get_index (stream),
 162                                                          axl_stream_get_global_index (stream),
 163                                                          axl_stream_get_near_to (stream, 10),
 164                                                          (following != NULL) ? following : "",
 165                                                          error_code);
 166         }
 167
 168         axl_log (NULL, AXL_LEVEL_CRITICAL, "(code: %d) %s", code, error_code);
 169
 170         /* set the error into the recevied reference */
 171         (* _error )       = error;
 172         return;
 173 }
 174
 175 /**
 176  * @brief Allows to check if the provided reference was used to report
 177  * an error.
 178  *
 179  * Those APIs that return an \ref axlError reference filled with the
 180  * textual error diagnostic, can take advantage of this function. It
 181  * Allows to check if the error was used to report an error, instead
 182  * of checking a returning value containing a particular error code.
 183  *
 184  * See \ref axl_error_new for more information.
 185  *
 186  * @param _error The error that is being checked.
 187  *
 188  * @return \ref true if the error reference doesn't contains an
 189  * "ERROR" (an error wasn't reported), otherwise, \ref false is
 190  * returned.
 191  */
 192 bool   axl_error_was_ok   (axlError * _error)
 193 {
 194         /* check if it was ok */
 195         if (_error == NULL || _error->error == NULL || (_error->defined != -346715))
 196                 return true;
 197
 198         /* axl error is defined */
 199         return false;
 200 }
 201
 202 /**
 203  * @brief Allows to get current error code from the given \ref axlError value.
 204  *
 205  * If the provided \ref axlError doesn't not contain a valid error
 206  * information, -1 is returned. Otherwise the specific error code is
 207  * returned.
 208  *
 209  * @param _error The \ref axlError to use, while getting error code
 210  * inside.
 211  *
 212  * @return The error code inside or -1 if fails.
 213  */
 214 int axl_error_get_code (axlError * _error)
 215 {
 216         /* check received reference */
 217         if (_error == NULL)
 218                 return -1;
 219         return _error->code;
 220 }
 221
 222 /**
 223  * @brief Allows to get current textual error string inside the given
 224  * \ref axlError value.
 225  *
 226  * @param _error The \ref axlError where the error string value will
 227  * be retrieved.
 228  *
 229  * @return The error code or the string "no string error defined" if
 230  * the given error doesn't contain any string information. You must
 231  * not deallocate memory returned by this function because it is an
 232  * internal copy.
 233  */
 234 char * axl_error_get      (axlError * _error)
 235 {
 236         /* check received reference */
 237         if (_error == NULL)
 238                 return "no string error defined";
 239
 240         return _error->error;
 241 }
 242
 243 /**
 244  * @brief Allows to release memory allocated by the given \ref
 245  * axlError variable.
 246  *
 247  * @param _error The axlError to deallocate.
 248  */
 249 void   axl_error_free     (axlError * _error)
 250 {
 251
 252         /* check for null reference received */
 253         if (_error == NULL)
 254                 return;
 255
 256         /* release man with no mercy */
 257         axl_free (_error->error);
 258         axl_free (_error);
 259
 260         return;
 261 }
 262
 263
 264 /* @} */