Annotation of gpl/axl/src/axl_error.c, revision 1.1.1.1
1.1 misho 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: * Edificio Alius A, Oficina 102,
32: * C/ Antonio Suarez Nº 10,
33: * Alcalá de Henares 28802 Madrid
34: * Spain
35: *
36: * Email address:
37: * info@aspl.es - http://www.aspl.es/xml
38: */
39: #include <axl.h>
40:
41: struct _axlError {
42: int code;
43: char * error;
44: int defined;
45: };
46:
47: /**
48: * \defgroup axl_error_module Axl Error report: Functions to help AXL library to report internal error to the application level.
49: */
50:
51: /**
52: * \addtogroup axl_error_module
53: * @{
54: */
55:
56: /**
57: * @brief Allows to create a new \ref axlError value that contains an
58: * error code and a error string.
59: *
60: * \ref axlError error reporting abstraction is a convenient way for
61: * the developer and the user that makes use of the API to report and
62: * get textual diagnostic errors produced. Many times, API provided do
63: * not allow to get more information if something wrong happen making
64: * it difficult to reach and solve the problem (including the
65: * development phase).
66: *
67: * From a developer's perspective, here is how works \ref axlError,
68: *
69: * \code
70: * void some_public_exported_function (int param, axlError ** error)
71: * {
72: * // do some work, but if it fails call to produce the error
73: * // reporting.
74: * axl_error_new (-2, // reporting an error code
75: * "Something wasn't ok while processing..",
76: * NULL, // a reference to the stream (optional)
77: * error); // variable received.
78: * return;
79: * }
80: * \endcode
81: *
82: * Previous construction makes error reporting optional but at the
83: * same time, available, because the programmer doesn't requires to
84: * check if the user did define the error variable, making it
85: * available at user option.
86: *
87: * Now, if the user defines the \ref axlError reference, by calling to
88: * the function, it can get the error reported as follows:
89: *
90: * \code
91: * // declare the variable and it to null
92: * axlError * error = NULL;
93: *
94: * // call to function
95: * some_pulic_exported_function (10, &error);
96: * if (! axl_error_was_ok (error)) {
97: * // drop the message
98: * printf ("Something has failed: (code: %d) %s\n",
99: * axl_error_get_code (error),
100: * axl_error_get (error));
101: * // dealloc the reference
102: * axl_error_free (error);
103: * }
104: * \endcode
105: *
106: * Alternatively, the user can just bypass the error reporting
107: * mechanism, without affecting the written code inside the source of
108: * the function supporting the \ref axlError notification (even if the
109: * code calls to \ref axl_error_new):
110: *
111: * \code
112: * // call to the function without error reporting
113: * some_pulic_exported_function (10, NULL);
114: * \endcode
115: *
116: * In most cases, \ref axl_error_new is not used by API consumers but
117: * by API developers. Once returned the \ref axlError reference the
118: * following functions could be checked.
119: *
120: * - \ref axl_error_get returns textual diagnostic reported.
121: *
122: * - \ref axl_error_get_code returns error code reported.
123: *
124: * - \ref axl_error_was_ok allows to check if some error was
125: * reported, base on the value initialization.
126: *
127: *
128: *
129: * @param code The error code to set and the error code string.
130: *
131: * @param error_code String to report.
132: *
133: * @param stream If provided, the error will try to get current stream
134: * position to add more information to the place where the error was
135: * found.
136: *
137: * @param _error The error string to be used to initialize the received \ref axlError.
138: */
139: void axl_error_new (int code, char * error_code, axlStream * stream, axlError ** _error)
140: {
141: axlError * error;
142: const char * following;
143:
144: /* get a reference to the error to be created */
145: if (_error == NULL)
146: return;
147:
148: /* create the error to be reported */
149: error = axl_new (axlError, 1);
150: error->code = code;
151: error->defined = -346715;
152: if (stream == NULL) {
153: /* allocate enough memory */
154: error->error = axl_strdup (error_code);
155: } else {
156: /* get the following */
157: following = axl_stream_get_following (stream, 10);
158:
159: /* alloc enough memory */
160: 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",
161: axl_stream_get_size (stream),
162: axl_stream_get_index (stream),
163: axl_stream_get_global_index (stream),
164: axl_stream_get_near_to (stream, 10),
165: (following != NULL) ? following : "",
166: error_code);
167: }
168:
169: axl_log (NULL, AXL_LEVEL_CRITICAL, "(code: %d) %s", code, error_code);
170:
171: /* set the error into the recevied reference */
172: (* _error ) = error;
173: return;
174: }
175:
176: /**
177: * @brief Allows to report a new error message with an associated
178: * error code on the provided \ref axlError reference.
179: *
180: * This function provides the same function like \ref axl_error_new
181: * but at the same time it provides support for printf-like arguments and
182: * no requires to provide a reference to an \ref axlStream which is
183: * suitable for axl libraries but not applications on top of it.
184: *
185: * @param _error Reference to the axlError to be initialized with the error
186: * to be reported. In the case NULL is received nothing is done.
187: *
188: * @param code The error code to report.
189: *
190: * @param format Printf-like error message to report.
191: */
192: void axl_error_report (axlError ** _error, int code, char * format, ...)
193: {
194: va_list args;
195: char * string;
196: axlError * error;
197:
198: /* do not operate if null is received */
199: if (_error == NULL)
200: return;
201:
202: /* open the stdargs */
203: va_start (args, format);
204:
205: /* build the string */
206: string = axl_stream_strdup_printfv (format, args);
207:
208: /* close the stdargs */
209: va_end (args);
210:
211: /* create the error to be reported */
212: error = axl_new (axlError, 1);
213: error->code = code;
214: error->defined = -346715;
215: /* allocate enough memory */
216: error->error = string;
217:
218: /* set the error into the recevied reference */
219: (* _error ) = error;
220: return;
221: }
222:
223: /**
224: * @brief Allows to check if the provided reference was used to report
225: * an error.
226: *
227: * Those APIs that return an \ref axlError reference filled with the
228: * textual error diagnostic, can take advantage of this function. It
229: * Allows to check if the error was used to report an error, instead
230: * of checking a returning value containing a particular error code.
231: *
232: * See \ref axl_error_new for more information.
233: *
234: * @param _error The error that is being checked.
235: *
236: * @return \ref axl_true if the error reference doesn't contains an
237: * "ERROR" (an error wasn't reported), otherwise, \ref axl_false is
238: * returned.
239: */
240: axl_bool axl_error_was_ok (axlError * _error)
241: {
242: /* check if it was ok */
243: if (_error == NULL || _error->error == NULL || (_error->defined != -346715))
244: return axl_true;
245:
246: /* axl error is defined */
247: return axl_false;
248: }
249:
250: /**
251: * @brief Allows to get current error code from the given \ref axlError value.
252: *
253: * If the provided \ref axlError doesn't not contain a valid error
254: * information, -1 is returned. Otherwise the specific error code is
255: * returned.
256: *
257: * @param _error The \ref axlError to use, while getting error code
258: * inside.
259: *
260: * @return The error code inside or -1 if fails.
261: */
262: int axl_error_get_code (axlError * _error)
263: {
264: /* check received reference */
265: if (_error == NULL)
266: return -1;
267: return _error->code;
268: }
269:
270: /**
271: * @brief Allows to get current textual error string inside the given
272: * \ref axlError value.
273: *
274: * @param _error The \ref axlError where the error string value will
275: * be retrieved.
276: *
277: * @return The error code or the string "no string error defined" if
278: * the given error doesn't contain any string information. You must
279: * not deallocate memory returned by this function because it is an
280: * internal copy.
281: */
282: const char * axl_error_get (axlError * _error)
283: {
284: /* check received reference */
285: if (_error == NULL)
286: return "no string error defined";
287:
288: return _error->error;
289: }
290:
291: /**
292: * @brief Allows to release memory allocated by the given \ref
293: * axlError variable.
294: *
295: * @param _error The axlError to deallocate.
296: */
297: void axl_error_free (axlError * _error)
298: {
299:
300: /* check for null reference received */
301: if (_error == NULL)
302: return;
303:
304: /* release man with no mercy */
305: axl_free (_error->error);
306: axl_free (_error);
307:
308: return;
309: }
310:
311:
312: /* @} */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to axl_error.c CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / gpl / axl / src