annotate Isolated/tErrorLib.h @ 52:53ee4253c925

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