Mercurial > almixer_isolated
annotate Isolated/tErrorLib.h @ 71:36644b1b940b
Removed use of dllimport for Windows.
Johnson Lin reported that he was getting warnings about it. I think the problem is that I didn't handle the case where you compile the files into your project or statically link. In this case you don't want dllexport or dllimport. From what I read, dllimport is optional (an optimization hint). Since this is becoming a nuisance, I rather just remove it rather than require another build flag.
author | Eric Wing <ewing . public |-at-| gmail . com> |
---|---|
date | Wed, 20 Jun 2012 10:46:03 -0700 |
parents | 208a9ed20087 |
children | 398d1cb12448 |
rev | line source |
---|---|
38 | 1 /* |
2 * zlib license. | |
3 */ | |
4 /* | |
5 Copyright (c) 2003 Eric Wing <ewing . public @ playcontrol.net> | |
6 | |
7 This software is provided 'as-is', without any express or implied warranty. | |
8 In no event will the authors be held liable for any damages arising from | |
9 the use of this software. | |
10 | |
11 Permission is granted to anyone to use this software for any purpose, | |
12 including commercial applications, and to alter it and redistribute it | |
13 freely, subject to the following restrictions: | |
14 | |
15 1. The origin of this software must not be misrepresented; you must not | |
16 claim that you wrote the original software. If you use this software in a | |
17 product, an acknowledgment in the product documentation would be | |
18 appreciated but is not required. | |
19 | |
20 2. Altered source versions must be plainly marked as such, and must not be | |
21 misrepresented as being the original software. | |
22 | |
23 3. This notice may not be removed or altered from any source distribution. | |
24 | |
25 */ | |
26 /** | |
27 * @file | |
28 * This is a Thread Safe Error handling Library. (How safe is still to be | |
29 * determined.) The name ErrorLib was already taken. TSError might work, but | |
30 * Terror was more fun to use. Named tErrorLib just in case of | |
31 * any conflicts with others who use "terror". | |
32 * | |
33 * This library is a generalized error flagging library. When an error | |
34 * occurs, this library allows you to set an error condition (a number | |
35 * and/or string) which can be fetched by at a later time (perhaps in a | |
36 * different module). It is analgous to perror or glGetError(), though | |
37 * perhaps a closer analogy might be to SDL_SetError() as this library | |
38 * allows you to deal with both integer numbers as well as printf-style | |
39 * formatted strings. | |
40 * | |
41 * This library also attempts to implement a certain degree of thread | |
42 * safety. The problem with a general access error system used | |
43 * by multiple threads is the risk of clobbering error messages set | |
44 * in one thread by error messages set in other threads before you | |
45 * get a chance to read them. This library solves that problem by | |
46 * creating separate error message structures for every unique thread. | |
47 * | |
48 * This library is unique in several ways. First, this is an entirely | |
49 * self-contained, error-handling-only library. Most people seem to at | |
50 * best rewrite their own error handling system for each library they write | |
51 * (and at worst, don't write any error handling system at all). | |
52 * | |
53 * Second, because this library is intended for just error handling, | |
54 * it was designed with the idea that it could be dropped into any | |
55 * library you choose and you are allowed to have separate/isolated | |
56 * error "pools". So for example, if you were writing multiple modules, | |
57 * such as a graphics library, a sound library, and an application core, | |
58 * you might desire to have separate error pools for each system so | |
59 * they don't collide. | |
60 * In order to accommodate the possible multiple instance of pools, the | |
61 * library has been factored into an object-oriented structure. Since | |
62 * this library is C-based, it does impose an additional parameter to | |
63 * be passed around than what people might be used to, but this | |
64 * API could be wrapped easily that hides the object pointer using a | |
65 * static or global variable for your module if you choose. | |
66 * | |
67 * Finally, this library allows the use of either/both integer or string | |
68 * errors. Integer error numbers allow for quick access and easy comparison. | |
69 * It may also allow for easier internationalization of error messages | |
70 * if you maintain a look-up-table. | |
71 * String error messages are nice because you know what the problem is | |
72 * immediately (don't have to hunt down or figure out what error 427 means). | |
73 * They also help make the code self documenting. And if you have errors | |
74 * nested down in function call layers, you can easily report the | |
75 * function call stack by appending information to the error string | |
76 * at each function call. | |
77 * | |
78 * Keep in mind that this library isn't meant to replace other error | |
79 * reporting conventions, but to supplement them. Functions that return | |
80 * error values (true/false,int) and logging systems (Logger) are still | |
81 * good systems that may address other issues. You might continue | |
82 * using error codes for your functions and then use tErrorLib to | |
83 * fetch the error string when you need them. And to log the error, | |
84 * you might pass the string into Logger. | |
85 * | |
86 * There are two different ways to use this library with respect to | |
87 * retrieving errors. You can treat each thread separately and let each | |
88 * live in its own separate world. When you retrieve the error, you only | |
89 * retrieve the error for the current thread. You should use the | |
90 * TError_GetErrorOnCurrentThread family of functions for this scenario. | |
91 * Alternatively, you can use this library to always return you the last | |
92 * set error regardless of the thread it was set in. You should use the | |
93 * TError_GetLastError family of functions for this scenario. | |
94 * | |
95 * Sample Usage: | |
96 * @code | |
97 * TErrorPool* err_pool; | |
98 * TErrorStatus error_status; | |
99 * | |
100 * err_pool = TError_CreateErrorPool(); | |
101 * if(NULL == err_pool) | |
102 * { | |
103 * fprintf(stderr, "Error, could not create error pool\n"); | |
104 * exit(1); | |
105 * } | |
106 * | |
107 * // Set a hypothetical error | |
108 * TError_SetError(err_pool, -1234, "Demo error #%d: %s", 222, "Hello"); | |
109 * | |
110 * // Check/get the error using the isolated thread usage model. | |
111 * // Might use TError_GetErrorNumOnCurrentThread or TError_GetErrorStrOnCurrentThread instead | |
112 * error_status = TError_GetErrorOnCurrentThread(err_pool); | |
113 * // Make sure the string is not NULL before printing it with printf. | |
114 * // (Some systems let you print NULL, but on Solaris, it seg faults.) | |
115 * if(NULL != error_status.errorString) | |
116 * { | |
117 * printf("%d: %s", error_status.errorNumber, error_status.errorString); | |
118 * } | |
119 * | |
120 * // not really necessary to call since single threaded and | |
121 * // going to delete the entire pool right after, but here for show. | |
122 * TError_DeleteEntryOnCurrentThread(err_pool); | |
123 * | |
124 * TError_FreeErrorPool(err_pool); | |
125 * | |
126 * @endcode | |
127 * | |
128 * Sample API Wrapping: | |
129 * This is an example of how you might want to wrap this library into | |
130 * your own API code so you don't have to expose the error pool. | |
131 * This example uses the last set error usage model. | |
132 * (If you didn't want to use both integers and strings, you could | |
133 * also make that decision here.) | |
134 * | |
135 * @code | |
136 * #include "tErrorLib.h" | |
137 * static TErrorPool* s_ErrorPool = NULL; // static error pool for this module | |
138 * | |
139 * int MyLibraryInit() | |
140 * { | |
141 * // Presumably you have you application specific code here too. | |
142 * s_ErrorPool = TError_CreateErrorPool(); | |
143 * if(NULL == s_ErrorPool) | |
144 * { | |
145 * return 0; // couldn't allocate memory | |
146 * } | |
147 * return 1; | |
148 * } | |
149 * | |
150 * void MyLibraryQuit() | |
151 * { | |
152 * TError_FreeErrorPool(s_ErrorPool); | |
153 * s_ErrorPool = NULL; | |
154 * } | |
155 * | |
156 * void MyLibrarySetError(int err_num, const char* err_str, ...) | |
157 * { | |
158 * va_list argp; | |
159 * va_start(argp, err_str); | |
160 * TError_SetErrorv(s_ErrorPool, err_num, err_str, argp); | |
161 * va_end(argp); | |
162 * } | |
163 * | |
164 * const char* MyLibraryGetError() | |
165 * { | |
166 * const char* ret_error = TError_GetLastErrorStr(s_ErrorPool); | |
167 * if(NULL == ret_error) | |
168 * { | |
169 * return ""; // provide an empty string to make it safe for people using printf without checking. | |
170 * } | |
171 * return ret_error; | |
172 * } | |
173 * @endcode | |
174 * | |
175 * @note By default, this library attempts to use vasprintf to generate | |
176 * the printf-style formatted strings. vasprintf is a GNU extension | |
177 * which solves the problem of having enough memory allocated in a buffer | |
178 * to handle an arbitrary length formatted string which you don't know | |
179 * in advance. I recommend you use this implementation if your library | |
180 * can support it as it will allow you to always generate correct strings. | |
181 * (Stack traces can become long and exceed your preallocated buffer sizes.) | |
182 * For compatibility, an alternative vsnprintf implementation is provided. | |
183 * If a string is too large, it will be truncated. vsnprintf is specified | |
184 * in C99, but it critcal for avoid security related issues surrounding | |
185 * sprintf and vsprintf. If your library lacks vsnprintf, you're asking | |
186 * for trouble. I currently do not try to handle this case. | |
187 * | |
188 * @note By default, this library assumes 0 is the no-error value. | |
189 * In addition, if you are using the string-only based APIs, the integer | |
190 * components will be automatically filled to 0 (for no-error) and | |
191 * 1 (for error). If these numbers conflict with your conventions, | |
192 * you may be able to change these values in the implementation file | |
193 * and recompile the library. Look for the defines for TERROR_ERROR_VALUE | |
194 * and TERROR_NOERROR_VALUE. | |
195 * | |
196 * @note This version attempts to provide enough thread safety to get by | |
197 * but it may not be totally safe during creation and destruction of | |
198 * instances (partly since locking is done inside the object-level), | |
199 * so don't create or destroy pools when there is possible contention. | |
200 * Strings you pass into the functions are not necessarily locked so | |
201 * be careful if you are modifying strings that are shared among | |
202 * your threads. | |
203 * | |
204 * @note Error strings returned are pointers to tErrorLib's internal | |
205 * copies of strings. Do not modify these or delete them. Also keep in | |
206 * mind that the pointers to these strings may become invalid when | |
207 * a new error is set (on a per-thread basis). So if you need a copy | |
208 * of the error string, you should make your own copy. | |
209 * | |
210 * @warning For code that frequently generates and destroys many threads, | |
211 * be aware that you should pay attention to memory management with this | |
212 * library. This library works by creating a unique error message | |
213 * structure for each thread. When the thread dies, the error pool | |
214 * will still contain a structure for that thread (if it had called | |
215 * this library in that thread). Just before the thread dies (but after | |
216 * any final error calls), you should call TError_DeleteEntryOnCurrentThread() | |
217 * to free the memory for that thread. Otherwise you will have a | |
218 * pseudo-memory-leak. (Pseudo in the sense that once you free the error pool, | |
219 * all memory will be freed, regardless of whether you remembered to call | |
220 * this function.) | |
221 * @see TERROR_NOERROR_VALUE, TError_DeleteEntryOnCurrentThread | |
222 * | |
223 * @author Eric Wing | |
224 */ | |
225 | |
226 #ifndef TERRORLIB_H | |
227 #define TERRORLIB_H | |
228 | |
229 #ifdef __cplusplus | |
230 extern "C" { | |
231 #endif | |
232 | |
233 #include <stdarg.h> /* for va_list */ | |
234 | |
235 /** | |
236 * This library determines if there is an error by checking | |
237 * both the error number and error string. If the error string is NULL | |
238 * and the error number is 0 (TERROR_NOERROR_VALUE), then it | |
239 * is considered a non-error. Because this library allows you to | |
240 * use just numbers or just strings, a value must be filled in internally | |
241 * as a place holder. It also must return some default/no-error values | |
242 * for GetError if there was no error. In these situations, | |
243 * NULL is set for strings and 0 (TERROR_NOERROR_VALUE) | |
244 * is set for numbers. This will become a point of confusion if you use | |
245 * 0 as an error code to denote a legitimate error and have a NULL error | |
246 * string. | |
247 * | |
248 * To accommodate this problem, this define is provided to let you | |
249 * redefine what the no-error value is (though this is untested). | |
250 * If you have the opportunity to write code that doesn't rely on 0 denoting | |
251 * an error, I recommend using this library as is, instead of trying | |
252 * to change this. If you do change this value, remember you must recompile | |
253 * the entire library. Also make sure that TERROR_ERROR_VALUE (in | |
254 * implementation file) is not equal to your changed value. | |
255 * | |
256 * For most cases, if you just want to check if there was an | |
257 * error, you can check if the error_number == 0. But if | |
258 * you are thinking that you may want to redefine what the no-error | |
259 * value is in the future (say -99999), then you can use this | |
260 * constant name instead (e.g. error_number == TERROR_NOERROR_VALUE). | |
261 */ | |
262 #define TERROR_NOERROR_VALUE 0 | |
263 | |
264 | |
265 #ifndef DOXYGEN_SHOULD_IGNORE_THIS | |
266 /** @cond DOXYGEN_SHOULD_IGNORE_THIS */ | |
267 | |
268 /* Note: For Doxygen to produce clean output, you should set the | |
269 * PREDEFINED option to remove TERROR_TERROR_DECLSPEC, TERROR_CALL, and | |
270 * the DOXYGEN_SHOULD_IGNORE_THIS blocks. | |
271 * PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 TERROR_TERROR_DECLSPEC= TERROR_CALL= | |
272 */ | |
273 | |
274 /** Windows needs to know explicitly which functions to export in a DLL. */ | |
275 #if defined(_WIN32) | |
276 #if defined(TERROR_BUILD_LIBRARY) | |
277 #define TERROR_DECLSPEC __declspec(dllexport) | |
278 #endif | |
279 #else | |
56
208a9ed20087
Added explicit symbol visibility markers to audio support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
38
diff
changeset
|
280 #if defined(TERROR_BUILD_LIBRARY) |
38 | 281 #if defined (__GNUC__) && __GNUC__ >= 4 |
282 #define TERROR_DECLSPEC __attribute__((visibility("default"))) | |
283 #else | |
284 #define TERROR_DECLSPEC | |
285 #endif | |
286 #else | |
287 #define TERROR_DECLSPEC | |
288 #endif | |
289 #endif | |
290 | |
291 /* For Windows, by default, use the C calling convention */ | |
292 #if defined(_WIN32) | |
293 #define TERROR_CALL __cdecl | |
294 #else | |
295 #define TERROR_CALL | |
296 #endif | |
297 | |
298 | |
299 /* Version number is set here. | |
300 * Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL | |
301 */ | |
302 #define TERROR_MAJOR_VERSION 0 | |
303 #define TERROR_MINOR_VERSION 1 | |
304 #define TERROR_PATCH_VERSION 0 | |
305 | |
306 /** @endcond DOXYGEN_SHOULD_IGNORE_THIS */ | |
307 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ | |
308 | |
309 | |
310 /** | |
311 * Struct that contains the version information of this library. | |
312 * This represents the library's version as three levels: major revision | |
313 * (increments with massive changes, additions, and enhancements), | |
314 * minor revision (increments with backwards-compatible changes to the | |
315 * major revision), and patchlevel (increments with fixes to the minor | |
316 * revision). | |
317 * @see TERROR_GET_COMPILED_VERSION, TError_GetLinkedVersion | |
318 */ | |
319 typedef struct | |
320 { | |
321 int major; /**< major revision. */ | |
322 int minor; /**< minor revision. */ | |
323 int patch; /**< patch revision. */ | |
324 } TErrorVersion; | |
325 | |
326 | |
327 /** | |
328 * Struct that contains all the data needed to represent an error (pool) | |
329 * instance. This is the object you pass around to all instance | |
330 * based error functions. Don't touch the data in the struct directly. | |
331 * This should be considered an opaque data type. | |
332 */ | |
333 typedef struct | |
334 { | |
335 void* mutexLock; /**< You probably shouldn't touch this either. */ | |
336 void* opaqueData; /**< Don't touch this. */ | |
337 } TErrorPool; | |
338 | |
339 /** | |
340 * Struct that contains both the error number and error string. | |
341 * This is returned by the TError_GetError functions which | |
342 * allows you to fetch both the errorNumber and errorString. | |
343 * (Other API functions only let you get one or the other). | |
344 * You may read the values directly, but do not modify the string. | |
345 * Keep in mind that once a SetError is called again for your thread, | |
346 * the pointer may become invalid. Copy this data out if you need | |
347 * to keep it. | |
348 */ | |
349 typedef struct | |
350 { | |
351 int errorNumber; /**< The error number. */ | |
352 const char* errorString; /**< The error string (read-only). */ | |
353 } TErrorStatus; | |
354 | |
355 | |
356 /** | |
357 * This macro fills in a TError_Version structure with the version of the | |
358 * library you compiled against. This is determined by what header the | |
359 * compiler uses. Note that if you dynamically linked the library, you might | |
360 * have a slightly newer or older version at runtime. That version can be | |
361 * determined with TError_GetLinkedVersion(), which, unlike | |
362 * TERROR_GET_COMPILED_VERSION, is not a macro. | |
363 * | |
364 * @param X A pointer to a TError_Version struct to initialize. | |
365 * | |
366 * @see TErrorVersion, TError_GetLinkedVersion | |
367 */ | |
368 #define TERROR_GET_COMPILED_VERSION(X) \ | |
369 { \ | |
370 if(NULL != (X)) \ | |
371 { \ | |
372 (X)->major = TERROR_MAJOR_VERSION; \ | |
373 (X)->minor = TERROR_MINOR_VERSION; \ | |
374 (X)->patch = TERROR_PATCH_VERSION; \ | |
375 } \ | |
376 } | |
377 | |
378 /** | |
379 * Gets the library version of tErrorLib you are using. | |
380 * This gets the version of tErrorLib that is linked against your program. | |
381 * If you are using a shared library (DLL) version of tError, then it is | |
382 * possible that it will be different than the version you compiled against. | |
383 * | |
384 * This is a real function; the macro TERROR_GET_COMPILED_VERSION | |
385 * tells you what version of tErrorLib you compiled against: | |
386 * | |
387 * @code | |
388 * TErrorVersion compiled; | |
389 * TErrorVersion linked; | |
390 * | |
391 * TERROR_GET_COMPILED_VERSION(&compiled); | |
392 * TError_GetLinkedVersion(&linked); | |
393 * printf("We compiled against tError version %d.%d.%d ...\n", | |
394 * compiled.major, compiled.minor, compiled.patch); | |
395 * printf("But we linked against tError version %d.%d.%d.\n", | |
396 * linked.major, linked.minor, linked.patch); | |
397 * @endcode | |
398 * | |
399 * @see TErrorVersion, TERROR_GET_COMPILED_VERSION | |
400 */ | |
401 extern TERROR_DECLSPEC void TERROR_CALL TError_GetLinkedVersion(TErrorVersion* ver); | |
402 | |
403 /** | |
404 * This creates a new error pool instance. | |
405 * An error pool is a self-contained object that holds its own | |
406 * errors. You may have multiple error pools to isolate errors for | |
407 * different subsystems if you choose. | |
408 * | |
409 * For most (if not all) other tErrorLib functions, you will | |
410 * pass this instance to each function when you call them. | |
411 * | |
412 * @return Returns a pointer to an error pool which is the | |
413 * instance variable (if successful) or NULL on failure. | |
414 * | |
415 * @see TError_FreeErrorPool | |
416 */ | |
417 extern TERROR_DECLSPEC TErrorPool* TERROR_CALL TError_CreateErrorPool(void); | |
418 | |
419 /** | |
420 * This frees an error pool instance. | |
421 * This properly frees the memory of an error pool instance created by | |
422 * CreateErrorPool. Whenever you create a TErrorPool | |
423 * instance, you should always remember to balance it with a | |
424 * FreeErrorPool() call. | |
425 * | |
426 * @param err_pool A pointer to the error pool instance you want to free. | |
427 * | |
428 * @see TError_CreateErrorPool | |
429 */ | |
430 extern TERROR_DECLSPEC void TERROR_CALL TError_FreeErrorPool(TErrorPool* err_pool); | |
431 | |
432 /** | |
433 * This function will delete the error message memory that has been | |
434 * allocated for the thread you call this function in. | |
435 * This reflects a deficiency in this library's design. | |
436 * If a thread terminates, this library will still have | |
437 * allocated memory for it if it had set an error. | |
438 * If you plan on killing a thread, call this function in that | |
439 * thread before it dies so the memory can be freed. | |
440 * Do not call SetError* again in this thread or memory | |
441 * will be reallocated. | |
442 * It is safe to call if no memory has actually be allocated for the | |
443 * error for the current thread. | |
444 * If you cannot use this function to free the memory for some reason, | |
445 * this is a pseudo-memory-leak. By pseudo, I mean that you won't | |
446 * completely leak. When you delete the entire memory pool, it will | |
447 * be able to free all error message structures that were associated | |
448 * with the pool so you can recover this memory. | |
449 * | |
450 * @param err_pool The error pool instance you want to use. | |
451 */ | |
452 extern TERROR_DECLSPEC void TError_DeleteEntryOnCurrentThread(TErrorPool* err_pool); | |
453 | |
454 | |
455 /** | |
456 * This function sets an error. | |
457 * Calling this function will set an error (for this thread) | |
458 * with the specified error number and error string which | |
459 * can later be retrieved by a GetError call. | |
460 * The function usage is similar to printf. | |
461 * If both the err_num is set to 0 (see other notes TERROR_NOERROR_VALUE) | |
462 * and the err_str is set to NULL, then this is considered clearing an | |
463 * error and no error will be marked. | |
464 * | |
465 * @param err_pool The error pool instance you want to use. | |
466 * | |
467 * @param err_num The error number you want to use for this error. | |
468 * The value for this number is up to you, based on your own | |
469 * conventions. But this library reserves one number to denote "no error". | |
470 * This number for initial implementation and documentation purposes is 0, | |
471 * and is defined in the implementation as TERROR_NOERROR_VALUE. | |
472 * You can still specify this number to be anything you choose | |
473 * if and only if you also always specify an error string that is not NULL. | |
474 * As long as an error string exists, the system will recognize there | |
475 * is an error. But if you have a NULL string and use 0 to denote an | |
476 * error, this will be interpreted as a clear error message. | |
477 * So I recommend you treat 0 as a no-error value and avoid using it | |
478 * as an error value in your code to avoid confusion. | |
479 * | |
480 * @param err_str This is where your error text goes. It is compatible with | |
481 * printf style format strings. There is no imposed limit on how long | |
482 * the strings can be if you are using the vasprintf backend. The | |
483 * vsnprintf implemention will automatically truncate the string if it | |
484 * is too long. | |
485 * You if don't wish to specify an error string, you may enter NULL here. | |
486 * But remember to note the effect if this string is NULL and the err_num is | |
487 * set to 0 (TERROR_NOERROR_VALUE). | |
488 * | |
489 * @param ... This is the variable argument list used to accomodate | |
490 * printf style format strings. | |
491 * | |
492 * @see TError_SetErrorv, TError_SetErrorNoFormat, TError_SetErrorNum, | |
493 * TError_SetErrorStr, TError_SetErrorStrv, TError_SetErrorStrNoFormat, | |
494 * TERROR_NOERROR_VALUE | |
495 */ | |
496 extern TERROR_DECLSPEC void TERROR_CALL TError_SetError(TErrorPool* err_pool, int err_num, const char* err_str, ...); | |
497 | |
498 | |
499 /** | |
500 * This function sets an error. | |
501 * This is the va_list version of TError_SetError. | |
502 * The same rules apply to this as with TError_SetError. | |
503 * | |
504 * @see TError_SetError | |
505 */ | |
506 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorv(TErrorPool* err_pool, int err_num, const char* err_str, va_list argp); | |
507 | |
508 /** | |
509 * This is a "No Format Strings Allowed" version of SetError. | |
510 * This version of SetError disallows the use of format strings. | |
511 * This was written if you needed to expose the SetError function to | |
512 * an untrusted source because it is quite easy to crash a system (or worse) | |
513 * with an invalid format string. An untrusted source might include | |
514 * arguments passed through the command line, any user input that | |
515 * gets fed to Logger, or strings taken from runtime generated sources | |
516 * like scripts. | |
517 * I was probably being overly paranoid when I created this function, | |
518 * and there may be ways to achive this level of safety without | |
519 * this function, but here it is anyway. | |
520 * In addition, if your compiler has problems with both vasprintf and | |
521 * vsnprintf, (you will have to modify some source code) you might | |
522 * consider basing all SetError functions around this function because | |
523 * since the strings are known length because there is no argument | |
524 * expansion. | |
525 * | |
526 * @see TError_SetError | |
527 */ | |
528 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorNoFormat(TErrorPool* err_pool, int err_num, const char* err_str); | |
529 | |
530 /** | |
531 * This function sets an error. | |
532 * This version only lets you set the error number. The backend | |
533 * will automatically set the error string to NULL. | |
534 * This API call is intended to be used only if you don't plan on using | |
535 * any error strings in your code. | |
536 * Also be aware of the notes about TERROR_NOERROR_VALUE. | |
537 * | |
538 * @see TError_SetError, TERROR_NOERROR_VALUE | |
539 */ | |
540 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorNum(TErrorPool* err_pool, int err_num); | |
541 | |
542 /** | |
543 * This function sets an error. | |
544 * This version only lets you set the error string. The backend | |
545 * will automatically set the error number to TERROR_NOERROR_VALUE | |
546 * which is currently implemented as 0. | |
547 * This API call is intended to be used only if you don't plan on using | |
548 * any error numbers in your code. | |
549 * Also be aware of the notes about TERROR_NOERROR_VALUE if you use NULL | |
550 * strings. | |
551 * | |
552 * @see TError_SetError, TERROR_NOERROR_VALUE | |
553 */ | |
554 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorStr(TErrorPool* err_pool, const char* err_str, ...); | |
555 | |
556 /** | |
557 * This function sets an error. | |
558 * This is the va_list version of TError_SetErrorStr. | |
559 * | |
560 * @see TError_SetError, TError_SetErrorStr, TERROR_NOERROR_VALUE | |
561 */ | |
562 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorStrv(TErrorPool* err_pool, const char* err_str, va_list argp); | |
563 | |
564 /** | |
565 * This function sets an error. | |
566 * This is the "No Format Strings Allowed" version of TError_SetErrorStr. | |
567 * | |
568 * @see TError_SetError, TError_SetErrorNoFormat, | |
569 * TError_SetErrorStr, TERROR_NOERROR_VALUE | |
570 */ | |
571 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorStrNoFormat(TErrorPool* err_pool, const char* err_str); | |
572 | |
573 /** | |
574 * This function gets the last error to be set by one of the SetError | |
575 * functions (from within your current thread). This version of the function | |
576 * returns just the error number. | |
577 * After this function is called, the error will be cleared, so your | |
578 * next call to a GetError function (with no SetError calls in between) | |
579 * will return a struct set with no-error values. | |
580 * | |
581 * @param err_pool The error pool instance you want to use. | |
582 * | |
583 * @return Returns the error number. | |
584 * If no error was set, the error number will be set | |
585 * to 0 (TERROR_NOERROR_VALUE). | |
586 * | |
587 * @see TError_GetErrorOnCurrentThread, TError_GetErrorStrOnCurrentThread, TERROR_NOERROR_VALUE | |
588 */ | |
589 extern TERROR_DECLSPEC int TERROR_CALL TError_GetErrorNumOnCurrentThread(TErrorPool* err_pool); | |
590 | |
591 /** | |
592 * This function gets the last error to be set by one of the SetError | |
593 * functions (from within your current thread). This version of the function | |
594 * returns a pointer to the error string. | |
595 * After this function is called, the error will be cleared, so your | |
596 * next call to a GetError function (with no SetError calls in between) | |
597 * will return a struct set with no-error values. | |
598 * | |
599 * @param err_pool The error pool instance you want to use. | |
600 * | |
601 * @return Returns the pointer to the error string. | |
602 * The pointer is to tErrorLib's own copy | |
603 * of the error message so you should not modify this string. Furthermore, | |
604 * the pointer may become invalid at the next call to SetError within this | |
605 * same thread, so if you need to keep the string, you must make your | |
606 * own copy of it. | |
607 * If no error was set, the error string will be set to NULL. | |
608 * | |
609 * @see TError_GetErrorNumOnCurrentThread, TError_GetErrorOnCurrentThread, TERROR_NOERROR_VALUE | |
610 */ | |
611 extern TERROR_DECLSPEC const char* TERROR_CALL TError_GetErrorStrOnCurrentThread(TErrorPool* err_pool); | |
612 | |
613 /** | |
614 * This function gets the last error to be set by one of the SetError | |
615 * functions (from within your current thread). This version of the function | |
616 * returns a struct containing the error number and a pointer to the | |
617 * error string. | |
618 * After this function is called, the error will be cleared, so your | |
619 * next call to a GetError function (with no SetError calls in between) | |
620 * will return a struct set with no-error values. | |
621 * | |
622 * @param err_pool The error pool instance you want to use. | |
623 * | |
624 * @return Returns (by-value) a struct containing the error number and | |
625 * pointer to the error string. The pointer is to tErrorLib's own copy | |
626 * of the error message so you should not modify this string. Furthermore, | |
627 * the pointer may become invalid at the next call to SetError within this | |
628 * same thread, so if you need to keep the string, you must make your | |
629 * own copy of it. | |
630 * If no error was set, the error number will be set to 0 (TERROR_NOERROR_VALUE) | |
631 * and the error string will be set to NULL. | |
632 * | |
633 * @see TError_GetErrorNumOnCurrentThread, TError_GetErrorStrOnCurrentThread, TERROR_NOERROR_VALUE | |
634 */ | |
635 extern TERROR_DECLSPEC TErrorStatus TERROR_CALL TError_GetErrorOnCurrentThread(TErrorPool* err_pool); | |
636 | |
637 | |
638 /** | |
639 * This function gets the last error to be set by one of the SetError | |
640 * functions (regardless of thread). | |
641 * This version of the function | |
642 * returns just the error number. | |
643 * After this function is called, the error will be cleared, so your | |
644 * next call to a GetError function (with no SetError calls in between) | |
645 * will return a struct set with no-error values. | |
646 * | |
647 * @param err_pool The error pool instance you want to use. | |
648 * | |
649 * @return Returns the error number. | |
650 * If no error was set, the error number will be set | |
651 * to 0 (TERROR_NOERROR_VALUE). | |
652 * | |
653 * @see TError_GetLastError, TError_GetLastErrorStr, TERROR_NOERROR_VALUE | |
654 */ | |
655 extern TERROR_DECLSPEC int TERROR_CALL TError_GetLastErrorNum(TErrorPool* err_pool); | |
656 | |
657 /** | |
658 * This function gets the last error to be set by one of the SetError | |
659 * functions (regardless of thread). | |
660 * This version of the function | |
661 * returns a pointer to the error string. | |
662 * After this function is called, the error will be cleared, so your | |
663 * next call to a GetError function (with no SetError calls in between) | |
664 * will return a struct set with no-error values. | |
665 * | |
666 * @param err_pool The error pool instance you want to use. | |
667 * | |
668 * @return Returns the pointer to the error string. | |
669 * The pointer is to tErrorLib's own copy | |
670 * of the error message so you should not modify this string. Furthermore, | |
671 * the pointer may become invalid at the next call to SetError within this | |
672 * same thread, so if you need to keep the string, you must make your | |
673 * own copy of it. | |
674 * If no error was set, the error string will be set to NULL. | |
675 * | |
676 * @see TError_GetLastErrorNum, TError_GetLastError, TERROR_NOERROR_VALUE | |
677 */ | |
678 extern TERROR_DECLSPEC const char* TERROR_CALL TError_GetLastErrorStr(TErrorPool* err_pool); | |
679 | |
680 /** | |
681 * This function gets the last error to be set by one of the SetError | |
682 * functions (regardless of thread). | |
683 * This version of the function | |
684 * returns a struct containing the error number and a pointer to the | |
685 * error string. | |
686 * After this function is called, the error will be cleared, so your | |
687 * next call to a GetError function (with no SetError calls in between) | |
688 * will return a struct set with no-error values. | |
689 * | |
690 * @param err_pool The error pool instance you want to use. | |
691 * | |
692 * @return Returns (by-value) a struct containing the error number and | |
693 * pointer to the error string. The pointer is to tErrorLib's own copy | |
694 * of the error message so you should not modify this string. Furthermore, | |
695 * the pointer may become invalid at the next call to SetError within this | |
696 * same thread, so if you need to keep the string, you must make your | |
697 * own copy of it. | |
698 * If no error was set, the error number will be set to 0 (TERROR_NOERROR_VALUE) | |
699 * and the error string will be set to NULL. | |
700 * | |
701 * @see TError_GetLastErrorNum, TError_GetLastErrorStr, TERROR_NOERROR_VALUE | |
702 */ | |
703 extern TERROR_DECLSPEC TErrorStatus TERROR_CALL TError_GetLastError(TErrorPool* err_pool); | |
704 | |
705 | |
706 #ifdef __cplusplus | |
707 } | |
708 #endif | |
709 | |
710 | |
711 #endif /* TERRORLIB_H */ | |
712 |