Mercurial > almixer_isolated
annotate Isolated/tErrorLib.h @ 79:358b0bd5df43 tip
Added support for Apportable's alcSuspend()/alcResume() in BeginInterruption()/EndInterruption. You must define ALMIXER_USE_APPORTABLE_OPENAL_EXTENSIONS to compile in this support.
| author | Eric Wing <ewing@coronalabs.com> |
|---|---|
| date | Tue, 30 Oct 2012 16:01:30 -0700 |
| parents | 398d1cb12448 |
| children |
| 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) | |
|
72
398d1cb12448
Bug fix for unbalanced #if/#endif blocks. I think I broke it when removing the dllimport for Windows.
Eric Wing <ewing . public |-at-| gmail . com>
parents:
71
diff
changeset
|
278 #else |
|
398d1cb12448
Bug fix for unbalanced #if/#endif blocks. I think I broke it when removing the dllimport for Windows.
Eric Wing <ewing . public |-at-| gmail . com>
parents:
71
diff
changeset
|
279 #define TERROR_DECLSPEC |
| 38 | 280 #endif |
| 281 #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
|
282 #if defined(TERROR_BUILD_LIBRARY) |
| 38 | 283 #if defined (__GNUC__) && __GNUC__ >= 4 |
| 284 #define TERROR_DECLSPEC __attribute__((visibility("default"))) | |
| 285 #else | |
| 286 #define TERROR_DECLSPEC | |
| 287 #endif | |
| 288 #else | |
| 289 #define TERROR_DECLSPEC | |
| 290 #endif | |
| 291 #endif | |
| 292 | |
| 293 /* For Windows, by default, use the C calling convention */ | |
| 294 #if defined(_WIN32) | |
| 295 #define TERROR_CALL __cdecl | |
| 296 #else | |
| 297 #define TERROR_CALL | |
| 298 #endif | |
| 299 | |
| 300 | |
| 301 /* Version number is set here. | |
| 302 * Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL | |
| 303 */ | |
| 304 #define TERROR_MAJOR_VERSION 0 | |
| 305 #define TERROR_MINOR_VERSION 1 | |
| 306 #define TERROR_PATCH_VERSION 0 | |
| 307 | |
| 308 /** @endcond DOXYGEN_SHOULD_IGNORE_THIS */ | |
| 309 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ | |
| 310 | |
| 311 | |
| 312 /** | |
| 313 * Struct that contains the version information of this library. | |
| 314 * This represents the library's version as three levels: major revision | |
| 315 * (increments with massive changes, additions, and enhancements), | |
| 316 * minor revision (increments with backwards-compatible changes to the | |
| 317 * major revision), and patchlevel (increments with fixes to the minor | |
| 318 * revision). | |
| 319 * @see TERROR_GET_COMPILED_VERSION, TError_GetLinkedVersion | |
| 320 */ | |
| 321 typedef struct | |
| 322 { | |
| 323 int major; /**< major revision. */ | |
| 324 int minor; /**< minor revision. */ | |
| 325 int patch; /**< patch revision. */ | |
| 326 } TErrorVersion; | |
| 327 | |
| 328 | |
| 329 /** | |
| 330 * Struct that contains all the data needed to represent an error (pool) | |
| 331 * instance. This is the object you pass around to all instance | |
| 332 * based error functions. Don't touch the data in the struct directly. | |
| 333 * This should be considered an opaque data type. | |
| 334 */ | |
| 335 typedef struct | |
| 336 { | |
| 337 void* mutexLock; /**< You probably shouldn't touch this either. */ | |
| 338 void* opaqueData; /**< Don't touch this. */ | |
| 339 } TErrorPool; | |
| 340 | |
| 341 /** | |
| 342 * Struct that contains both the error number and error string. | |
| 343 * This is returned by the TError_GetError functions which | |
| 344 * allows you to fetch both the errorNumber and errorString. | |
| 345 * (Other API functions only let you get one or the other). | |
| 346 * You may read the values directly, but do not modify the string. | |
| 347 * Keep in mind that once a SetError is called again for your thread, | |
| 348 * the pointer may become invalid. Copy this data out if you need | |
| 349 * to keep it. | |
| 350 */ | |
| 351 typedef struct | |
| 352 { | |
| 353 int errorNumber; /**< The error number. */ | |
| 354 const char* errorString; /**< The error string (read-only). */ | |
| 355 } TErrorStatus; | |
| 356 | |
| 357 | |
| 358 /** | |
| 359 * This macro fills in a TError_Version structure with the version of the | |
| 360 * library you compiled against. This is determined by what header the | |
| 361 * compiler uses. Note that if you dynamically linked the library, you might | |
| 362 * have a slightly newer or older version at runtime. That version can be | |
| 363 * determined with TError_GetLinkedVersion(), which, unlike | |
| 364 * TERROR_GET_COMPILED_VERSION, is not a macro. | |
| 365 * | |
| 366 * @param X A pointer to a TError_Version struct to initialize. | |
| 367 * | |
| 368 * @see TErrorVersion, TError_GetLinkedVersion | |
| 369 */ | |
| 370 #define TERROR_GET_COMPILED_VERSION(X) \ | |
| 371 { \ | |
| 372 if(NULL != (X)) \ | |
| 373 { \ | |
| 374 (X)->major = TERROR_MAJOR_VERSION; \ | |
| 375 (X)->minor = TERROR_MINOR_VERSION; \ | |
| 376 (X)->patch = TERROR_PATCH_VERSION; \ | |
| 377 } \ | |
| 378 } | |
| 379 | |
| 380 /** | |
| 381 * Gets the library version of tErrorLib you are using. | |
| 382 * This gets the version of tErrorLib that is linked against your program. | |
| 383 * If you are using a shared library (DLL) version of tError, then it is | |
| 384 * possible that it will be different than the version you compiled against. | |
| 385 * | |
| 386 * This is a real function; the macro TERROR_GET_COMPILED_VERSION | |
| 387 * tells you what version of tErrorLib you compiled against: | |
| 388 * | |
| 389 * @code | |
| 390 * TErrorVersion compiled; | |
| 391 * TErrorVersion linked; | |
| 392 * | |
| 393 * TERROR_GET_COMPILED_VERSION(&compiled); | |
| 394 * TError_GetLinkedVersion(&linked); | |
| 395 * printf("We compiled against tError version %d.%d.%d ...\n", | |
| 396 * compiled.major, compiled.minor, compiled.patch); | |
| 397 * printf("But we linked against tError version %d.%d.%d.\n", | |
| 398 * linked.major, linked.minor, linked.patch); | |
| 399 * @endcode | |
| 400 * | |
| 401 * @see TErrorVersion, TERROR_GET_COMPILED_VERSION | |
| 402 */ | |
| 403 extern TERROR_DECLSPEC void TERROR_CALL TError_GetLinkedVersion(TErrorVersion* ver); | |
| 404 | |
| 405 /** | |
| 406 * This creates a new error pool instance. | |
| 407 * An error pool is a self-contained object that holds its own | |
| 408 * errors. You may have multiple error pools to isolate errors for | |
| 409 * different subsystems if you choose. | |
| 410 * | |
| 411 * For most (if not all) other tErrorLib functions, you will | |
| 412 * pass this instance to each function when you call them. | |
| 413 * | |
| 414 * @return Returns a pointer to an error pool which is the | |
| 415 * instance variable (if successful) or NULL on failure. | |
| 416 * | |
| 417 * @see TError_FreeErrorPool | |
| 418 */ | |
| 419 extern TERROR_DECLSPEC TErrorPool* TERROR_CALL TError_CreateErrorPool(void); | |
| 420 | |
| 421 /** | |
| 422 * This frees an error pool instance. | |
| 423 * This properly frees the memory of an error pool instance created by | |
| 424 * CreateErrorPool. Whenever you create a TErrorPool | |
| 425 * instance, you should always remember to balance it with a | |
| 426 * FreeErrorPool() call. | |
| 427 * | |
| 428 * @param err_pool A pointer to the error pool instance you want to free. | |
| 429 * | |
| 430 * @see TError_CreateErrorPool | |
| 431 */ | |
| 432 extern TERROR_DECLSPEC void TERROR_CALL TError_FreeErrorPool(TErrorPool* err_pool); | |
| 433 | |
| 434 /** | |
| 435 * This function will delete the error message memory that has been | |
| 436 * allocated for the thread you call this function in. | |
| 437 * This reflects a deficiency in this library's design. | |
| 438 * If a thread terminates, this library will still have | |
| 439 * allocated memory for it if it had set an error. | |
| 440 * If you plan on killing a thread, call this function in that | |
| 441 * thread before it dies so the memory can be freed. | |
| 442 * Do not call SetError* again in this thread or memory | |
| 443 * will be reallocated. | |
| 444 * It is safe to call if no memory has actually be allocated for the | |
| 445 * error for the current thread. | |
| 446 * If you cannot use this function to free the memory for some reason, | |
| 447 * this is a pseudo-memory-leak. By pseudo, I mean that you won't | |
| 448 * completely leak. When you delete the entire memory pool, it will | |
| 449 * be able to free all error message structures that were associated | |
| 450 * with the pool so you can recover this memory. | |
| 451 * | |
| 452 * @param err_pool The error pool instance you want to use. | |
| 453 */ | |
| 454 extern TERROR_DECLSPEC void TError_DeleteEntryOnCurrentThread(TErrorPool* err_pool); | |
| 455 | |
| 456 | |
| 457 /** | |
| 458 * This function sets an error. | |
| 459 * Calling this function will set an error (for this thread) | |
| 460 * with the specified error number and error string which | |
| 461 * can later be retrieved by a GetError call. | |
| 462 * The function usage is similar to printf. | |
| 463 * If both the err_num is set to 0 (see other notes TERROR_NOERROR_VALUE) | |
| 464 * and the err_str is set to NULL, then this is considered clearing an | |
| 465 * error and no error will be marked. | |
| 466 * | |
| 467 * @param err_pool The error pool instance you want to use. | |
| 468 * | |
| 469 * @param err_num The error number you want to use for this error. | |
| 470 * The value for this number is up to you, based on your own | |
| 471 * conventions. But this library reserves one number to denote "no error". | |
| 472 * This number for initial implementation and documentation purposes is 0, | |
| 473 * and is defined in the implementation as TERROR_NOERROR_VALUE. | |
| 474 * You can still specify this number to be anything you choose | |
| 475 * if and only if you also always specify an error string that is not NULL. | |
| 476 * As long as an error string exists, the system will recognize there | |
| 477 * is an error. But if you have a NULL string and use 0 to denote an | |
| 478 * error, this will be interpreted as a clear error message. | |
| 479 * So I recommend you treat 0 as a no-error value and avoid using it | |
| 480 * as an error value in your code to avoid confusion. | |
| 481 * | |
| 482 * @param err_str This is where your error text goes. It is compatible with | |
| 483 * printf style format strings. There is no imposed limit on how long | |
| 484 * the strings can be if you are using the vasprintf backend. The | |
| 485 * vsnprintf implemention will automatically truncate the string if it | |
| 486 * is too long. | |
| 487 * You if don't wish to specify an error string, you may enter NULL here. | |
| 488 * But remember to note the effect if this string is NULL and the err_num is | |
| 489 * set to 0 (TERROR_NOERROR_VALUE). | |
| 490 * | |
| 491 * @param ... This is the variable argument list used to accomodate | |
| 492 * printf style format strings. | |
| 493 * | |
| 494 * @see TError_SetErrorv, TError_SetErrorNoFormat, TError_SetErrorNum, | |
| 495 * TError_SetErrorStr, TError_SetErrorStrv, TError_SetErrorStrNoFormat, | |
| 496 * TERROR_NOERROR_VALUE | |
| 497 */ | |
| 498 extern TERROR_DECLSPEC void TERROR_CALL TError_SetError(TErrorPool* err_pool, int err_num, const char* err_str, ...); | |
| 499 | |
| 500 | |
| 501 /** | |
| 502 * This function sets an error. | |
| 503 * This is the va_list version of TError_SetError. | |
| 504 * The same rules apply to this as with TError_SetError. | |
| 505 * | |
| 506 * @see TError_SetError | |
| 507 */ | |
| 508 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorv(TErrorPool* err_pool, int err_num, const char* err_str, va_list argp); | |
| 509 | |
| 510 /** | |
| 511 * This is a "No Format Strings Allowed" version of SetError. | |
| 512 * This version of SetError disallows the use of format strings. | |
| 513 * This was written if you needed to expose the SetError function to | |
| 514 * an untrusted source because it is quite easy to crash a system (or worse) | |
| 515 * with an invalid format string. An untrusted source might include | |
| 516 * arguments passed through the command line, any user input that | |
| 517 * gets fed to Logger, or strings taken from runtime generated sources | |
| 518 * like scripts. | |
| 519 * I was probably being overly paranoid when I created this function, | |
| 520 * and there may be ways to achive this level of safety without | |
| 521 * this function, but here it is anyway. | |
| 522 * In addition, if your compiler has problems with both vasprintf and | |
| 523 * vsnprintf, (you will have to modify some source code) you might | |
| 524 * consider basing all SetError functions around this function because | |
| 525 * since the strings are known length because there is no argument | |
| 526 * expansion. | |
| 527 * | |
| 528 * @see TError_SetError | |
| 529 */ | |
| 530 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorNoFormat(TErrorPool* err_pool, int err_num, const char* err_str); | |
| 531 | |
| 532 /** | |
| 533 * This function sets an error. | |
| 534 * This version only lets you set the error number. The backend | |
| 535 * will automatically set the error string to NULL. | |
| 536 * This API call is intended to be used only if you don't plan on using | |
| 537 * any error strings in your code. | |
| 538 * Also be aware of the notes about TERROR_NOERROR_VALUE. | |
| 539 * | |
| 540 * @see TError_SetError, TERROR_NOERROR_VALUE | |
| 541 */ | |
| 542 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorNum(TErrorPool* err_pool, int err_num); | |
| 543 | |
| 544 /** | |
| 545 * This function sets an error. | |
| 546 * This version only lets you set the error string. The backend | |
| 547 * will automatically set the error number to TERROR_NOERROR_VALUE | |
| 548 * which is currently implemented as 0. | |
| 549 * This API call is intended to be used only if you don't plan on using | |
| 550 * any error numbers in your code. | |
| 551 * Also be aware of the notes about TERROR_NOERROR_VALUE if you use NULL | |
| 552 * strings. | |
| 553 * | |
| 554 * @see TError_SetError, TERROR_NOERROR_VALUE | |
| 555 */ | |
| 556 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorStr(TErrorPool* err_pool, const char* err_str, ...); | |
| 557 | |
| 558 /** | |
| 559 * This function sets an error. | |
| 560 * This is the va_list version of TError_SetErrorStr. | |
| 561 * | |
| 562 * @see TError_SetError, TError_SetErrorStr, TERROR_NOERROR_VALUE | |
| 563 */ | |
| 564 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorStrv(TErrorPool* err_pool, const char* err_str, va_list argp); | |
| 565 | |
| 566 /** | |
| 567 * This function sets an error. | |
| 568 * This is the "No Format Strings Allowed" version of TError_SetErrorStr. | |
| 569 * | |
| 570 * @see TError_SetError, TError_SetErrorNoFormat, | |
| 571 * TError_SetErrorStr, TERROR_NOERROR_VALUE | |
| 572 */ | |
| 573 extern TERROR_DECLSPEC void TERROR_CALL TError_SetErrorStrNoFormat(TErrorPool* err_pool, const char* err_str); | |
| 574 | |
| 575 /** | |
| 576 * This function gets the last error to be set by one of the SetError | |
| 577 * functions (from within your current thread). This version of the function | |
| 578 * returns just the error number. | |
| 579 * After this function is called, the error will be cleared, so your | |
| 580 * next call to a GetError function (with no SetError calls in between) | |
| 581 * will return a struct set with no-error values. | |
| 582 * | |
| 583 * @param err_pool The error pool instance you want to use. | |
| 584 * | |
| 585 * @return Returns the error number. | |
| 586 * If no error was set, the error number will be set | |
| 587 * to 0 (TERROR_NOERROR_VALUE). | |
| 588 * | |
| 589 * @see TError_GetErrorOnCurrentThread, TError_GetErrorStrOnCurrentThread, TERROR_NOERROR_VALUE | |
| 590 */ | |
| 591 extern TERROR_DECLSPEC int TERROR_CALL TError_GetErrorNumOnCurrentThread(TErrorPool* err_pool); | |
| 592 | |
| 593 /** | |
| 594 * This function gets the last error to be set by one of the SetError | |
| 595 * functions (from within your current thread). This version of the function | |
| 596 * returns a pointer to the error string. | |
| 597 * After this function is called, the error will be cleared, so your | |
| 598 * next call to a GetError function (with no SetError calls in between) | |
| 599 * will return a struct set with no-error values. | |
| 600 * | |
| 601 * @param err_pool The error pool instance you want to use. | |
| 602 * | |
| 603 * @return Returns the pointer to the error string. | |
| 604 * The pointer is to tErrorLib's own copy | |
| 605 * of the error message so you should not modify this string. Furthermore, | |
| 606 * the pointer may become invalid at the next call to SetError within this | |
| 607 * same thread, so if you need to keep the string, you must make your | |
| 608 * own copy of it. | |
| 609 * If no error was set, the error string will be set to NULL. | |
| 610 * | |
| 611 * @see TError_GetErrorNumOnCurrentThread, TError_GetErrorOnCurrentThread, TERROR_NOERROR_VALUE | |
| 612 */ | |
| 613 extern TERROR_DECLSPEC const char* TERROR_CALL TError_GetErrorStrOnCurrentThread(TErrorPool* err_pool); | |
| 614 | |
| 615 /** | |
| 616 * This function gets the last error to be set by one of the SetError | |
| 617 * functions (from within your current thread). This version of the function | |
| 618 * returns a struct containing the error number and a pointer to the | |
| 619 * error string. | |
| 620 * After this function is called, the error will be cleared, so your | |
| 621 * next call to a GetError function (with no SetError calls in between) | |
| 622 * will return a struct set with no-error values. | |
| 623 * | |
| 624 * @param err_pool The error pool instance you want to use. | |
| 625 * | |
| 626 * @return Returns (by-value) a struct containing the error number and | |
| 627 * pointer to the error string. The pointer is to tErrorLib's own copy | |
| 628 * of the error message so you should not modify this string. Furthermore, | |
| 629 * the pointer may become invalid at the next call to SetError within this | |
| 630 * same thread, so if you need to keep the string, you must make your | |
| 631 * own copy of it. | |
| 632 * If no error was set, the error number will be set to 0 (TERROR_NOERROR_VALUE) | |
| 633 * and the error string will be set to NULL. | |
| 634 * | |
| 635 * @see TError_GetErrorNumOnCurrentThread, TError_GetErrorStrOnCurrentThread, TERROR_NOERROR_VALUE | |
| 636 */ | |
| 637 extern TERROR_DECLSPEC TErrorStatus TERROR_CALL TError_GetErrorOnCurrentThread(TErrorPool* err_pool); | |
| 638 | |
| 639 | |
| 640 /** | |
| 641 * This function gets the last error to be set by one of the SetError | |
| 642 * functions (regardless of thread). | |
| 643 * This version of the function | |
| 644 * returns just the error number. | |
| 645 * After this function is called, the error will be cleared, so your | |
| 646 * next call to a GetError function (with no SetError calls in between) | |
| 647 * will return a struct set with no-error values. | |
| 648 * | |
| 649 * @param err_pool The error pool instance you want to use. | |
| 650 * | |
| 651 * @return Returns the error number. | |
| 652 * If no error was set, the error number will be set | |
| 653 * to 0 (TERROR_NOERROR_VALUE). | |
| 654 * | |
| 655 * @see TError_GetLastError, TError_GetLastErrorStr, TERROR_NOERROR_VALUE | |
| 656 */ | |
| 657 extern TERROR_DECLSPEC int TERROR_CALL TError_GetLastErrorNum(TErrorPool* err_pool); | |
| 658 | |
| 659 /** | |
| 660 * This function gets the last error to be set by one of the SetError | |
| 661 * functions (regardless of thread). | |
| 662 * This version of the function | |
| 663 * returns a pointer to the error string. | |
| 664 * After this function is called, the error will be cleared, so your | |
| 665 * next call to a GetError function (with no SetError calls in between) | |
| 666 * will return a struct set with no-error values. | |
| 667 * | |
| 668 * @param err_pool The error pool instance you want to use. | |
| 669 * | |
| 670 * @return Returns the pointer to the error string. | |
| 671 * The pointer is to tErrorLib's own copy | |
| 672 * of the error message so you should not modify this string. Furthermore, | |
| 673 * the pointer may become invalid at the next call to SetError within this | |
| 674 * same thread, so if you need to keep the string, you must make your | |
| 675 * own copy of it. | |
| 676 * If no error was set, the error string will be set to NULL. | |
| 677 * | |
| 678 * @see TError_GetLastErrorNum, TError_GetLastError, TERROR_NOERROR_VALUE | |
| 679 */ | |
| 680 extern TERROR_DECLSPEC const char* TERROR_CALL TError_GetLastErrorStr(TErrorPool* err_pool); | |
| 681 | |
| 682 /** | |
| 683 * This function gets the last error to be set by one of the SetError | |
| 684 * functions (regardless of thread). | |
| 685 * This version of the function | |
| 686 * returns a struct containing the error number and a pointer to the | |
| 687 * error string. | |
| 688 * After this function is called, the error will be cleared, so your | |
| 689 * next call to a GetError function (with no SetError calls in between) | |
| 690 * will return a struct set with no-error values. | |
| 691 * | |
| 692 * @param err_pool The error pool instance you want to use. | |
| 693 * | |
| 694 * @return Returns (by-value) a struct containing the error number and | |
| 695 * pointer to the error string. The pointer is to tErrorLib's own copy | |
| 696 * of the error message so you should not modify this string. Furthermore, | |
| 697 * the pointer may become invalid at the next call to SetError within this | |
| 698 * same thread, so if you need to keep the string, you must make your | |
| 699 * own copy of it. | |
| 700 * If no error was set, the error number will be set to 0 (TERROR_NOERROR_VALUE) | |
| 701 * and the error string will be set to NULL. | |
| 702 * | |
| 703 * @see TError_GetLastErrorNum, TError_GetLastErrorStr, TERROR_NOERROR_VALUE | |
| 704 */ | |
| 705 extern TERROR_DECLSPEC TErrorStatus TERROR_CALL TError_GetLastError(TErrorPool* err_pool); | |
| 706 | |
| 707 | |
| 708 #ifdef __cplusplus | |
| 709 } | |
| 710 #endif | |
| 711 | |
| 712 | |
| 713 #endif /* TERRORLIB_H */ | |
| 714 |