VirtualBox

source: vbox/trunk/include/VBox/com/errorprint.h@ 58371

Last change on this file since 58371 was 58110, checked in by vboxsync, 9 years ago

include,misc: Doxygen grouping adjustments, collecting all the VMM bits under one parent group, ditto for the COM library.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.3 KB
Line 
1/** @file
2 * MS COM / XPCOM Abstraction Layer - Error Reporting.
3 *
4 * Error printing macros using shared functions defined in shared glue code.
5 * Use these CHECK_* macros for efficient error checking around calling COM
6 * methods.
7 */
8
9/*
10 * Copyright (C) 2009-2015 Oracle Corporation
11 *
12 * This file is part of VirtualBox Open Source Edition (OSE), as
13 * available from http://www.virtualbox.org. This file is free software;
14 * you can redistribute it and/or modify it under the terms of the GNU
15 * General Public License (GPL) as published by the Free Software
16 * Foundation, in version 2 as it comes in the "COPYING" file of the
17 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
18 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
19 *
20 * The contents of this file may alternatively be used under the terms
21 * of the Common Development and Distribution License Version 1.0
22 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
23 * VirtualBox OSE distribution, in which case the provisions of the
24 * CDDL are applicable instead of those of the GPL.
25 *
26 * You may elect to license modified versions of this file under the
27 * terms and conditions of either the GPL or the CDDL or both.
28 */
29
30#ifndef ___VBox_com_errorprint_h
31#define ___VBox_com_errorprint_h
32
33#include <VBox/com/ErrorInfo.h>
34
35
36/** @defgroup grp_com_error_reporting Error Reporting
37 * @ingroup grp_com
38 * @{
39 */
40
41namespace com
42{
43
44// shared prototypes; these are defined in shared glue code and are
45// compiled only once for all front-ends
46void GluePrintErrorInfo(const com::ErrorInfo &info);
47void GluePrintErrorContext(const char *pcszContext, const char *pcszSourceFile, uint32_t uLine);
48void GluePrintRCMessage(HRESULT rc);
49void GlueHandleComError(ComPtr<IUnknown> iface, const char *pcszContext, HRESULT rc, const char *pcszSourceFile, uint32_t uLine);
50void GlueHandleComErrorProgress(ComPtr<IProgress> progress, const char *pcszContext, HRESULT rc,
51 const char *pcszSourceFile, uint32_t uLine);
52
53/**
54 * Extended macro that implements all the other CHECK_ERROR2XXX macros.
55 *
56 * Calls the method of the given interface and checks the return status code.
57 * If the status indicates failure, as much information as possible is reported
58 * about the error, including current source file and line.
59 *
60 * After reporting an error, the statement |stmtError| is executed.
61 *
62 * This macro family is intended for command line tools like VBoxManage, but
63 * could also be handy for debugging.
64 *
65 * @param type For defining @a hrc locally inside the the macro
66 * expansion, pass |HRESULT| otherwise |RT_NOTHING|.
67 * @param hrc Name of the HRESULT variable to assign the result of the
68 * method call to.
69 * @param iface The interface pointer (can be a smart pointer object).
70 * @param method The method to invoke together with the parameters.
71 * @param stmtError Statement to be executed after reporting failures. This
72 * can be a |break| or |return| statement, if so desired.
73 *
74 * @remarks Unlike CHECK_ERROR, CHECK_ERROR_RET and family, this macro family
75 * does not presuppose a |rc| variable but instead either let the user
76 * specify the variable to use or employs a local variable |hrcCheck|
77 * within its own scope.
78 *
79 * @sa CHECK_ERROR2, CHECK_ERROR2I, CHECK_ERROR2_STMT, CHECK_ERROR2I_STMT,
80 * CHECK_ERROR2_BREAK, CHECK_ERROR2I_BREAK, CHECK_ERROR2_RET,
81 * CHECK_ERROR2I_RET
82 */
83#define CHECK_ERROR2_EX(type, hrc, iface, method, stmtError) \
84 if (1) { \
85 type hrc = iface->method; \
86 if (SUCCEEDED(hrc)) \
87 { /*likely*/ } \
88 else \
89 { \
90 com::GlueHandleComError(iface, #method, (hrc), __FILE__, __LINE__); \
91 stmtError; \
92 } \
93 } else do { /* nothing */ } while (0)
94
95
96/**
97 * Calls the given method of the given interface and then checks if the return
98 * value (COM result code) indicates a failure. If so, prints the failed
99 * function/line/file, the description of the result code and attempts to
100 * query the extended error information on the current thread (using
101 * com::ErrorInfo) if the interface reports that it supports error information.
102 *
103 * Used by command line tools or for debugging and assumes the |HRESULT rc|
104 * variable is accessible for assigning in the current scope.
105 * @sa CHECK_ERROR2, CHECK_ERROR2I
106 */
107#define CHECK_ERROR(iface, method) \
108 do { \
109 rc = iface->method; \
110 if (FAILED(rc)) \
111 com::GlueHandleComError(iface, #method, rc, __FILE__, __LINE__); \
112 } while (0)
113/**
114 * Simplified version of CHECK_ERROR2_EX, no error statement or type necessary.
115 *
116 * @param hrc Name of the HRESULT variable to assign the result of the
117 * method call to.
118 * @param iface The interface pointer (can be a smart pointer object).
119 * @param method The method to invoke together with the parameters.
120 * @sa CHECK_ERROR2I, CHECK_ERROR2_EX
121 */
122#define CHECK_ERROR2(hrc, iface, method) CHECK_ERROR2_EX(RT_NOTHING, hrc, iface, method, (void)1)
123/**
124 * Simplified version of CHECK_ERROR2_EX that uses an internal variable
125 * |hrcCheck| for holding the result and have no error statement.
126 *
127 * @param iface The interface pointer (can be a smart pointer object).
128 * @param method The method to invoke together with the parameters.
129 * @sa CHECK_ERROR2, CHECK_ERROR2_EX
130 */
131#define CHECK_ERROR2I(iface, method) CHECK_ERROR2_EX(HRESULT, hrcCheck, iface, method, (void)1)
132
133
134/**
135 * Same as CHECK_ERROR except that it also executes the statement |stmt| on
136 * failure.
137 * @sa CHECK_ERROR2_STMT, CHECK_ERROR2I_STMT
138 */
139#define CHECK_ERROR_STMT(iface, method, stmt) \
140 do { \
141 rc = iface->method; \
142 if (FAILED(rc)) \
143 { \
144 com::GlueHandleComError(iface, #method, rc, __FILE__, __LINE__); \
145 stmt; \
146 } \
147 } while (0)
148/**
149 * Simplified version of CHECK_ERROR2_EX (no @a hrc type).
150 *
151 * @param hrc Name of the HRESULT variable to assign the result of the
152 * method call to.
153 * @param iface The interface pointer (can be a smart pointer object).
154 * @param method The method to invoke together with the parameters.
155 * @param stmt Statement to be executed after reporting failures.
156 * @sa CHECK_ERROR2I_STMT, CHECK_ERROR2_EX
157 */
158#define CHECK_ERROR2_STMT(hrc, iface, method, stmt) CHECK_ERROR2_EX(RT_NOTHING, hrc, iface, method, stmt)
159/**
160 * Simplified version of CHECK_ERROR2_EX that uses an internal variable
161 * |hrcCheck| for holding the result.
162 *
163 * @param iface The interface pointer (can be a smart pointer object).
164 * @param method The method to invoke together with the parameters.
165 * @param stmt Statement to be executed after reporting failures.
166 * @sa CHECK_ERROR2_STMT, CHECK_ERROR2_EX
167 */
168#define CHECK_ERROR2I_STMT(iface, method, stmt) CHECK_ERROR2_EX(HRESULT, hrcCheck, iface, method, stmt)
169
170
171/**
172 * Does the same as CHECK_ERROR(), but executes the |break| statement on
173 * failure.
174 * @sa CHECK_ERROR2_BREAK, CHECK_ERROR2I_BREAK
175 */
176#ifdef __GNUC__
177# define CHECK_ERROR_BREAK(iface, method) \
178 __extension__ \
179 ({ \
180 rc = iface->method; \
181 if (FAILED(rc)) \
182 { \
183 com::GlueHandleComError(iface, #method, rc, __FILE__, __LINE__); \
184 break; \
185 } \
186 })
187#else
188# define CHECK_ERROR_BREAK(iface, method) \
189 if (1) \
190 { \
191 rc = iface->method; \
192 if (FAILED(rc)) \
193 { \
194 com::GlueHandleComError(iface, #method, rc, __FILE__, __LINE__); \
195 break; \
196 } \
197 } \
198 else do {} while (0)
199#endif
200/**
201 * Simplified version of CHECK_ERROR2_EX that executes the |break| statement
202 * after error reporting (no @a hrc type).
203 *
204 * @param hrc The result variable (type HRESULT).
205 * @param iface The interface pointer (can be a smart pointer object).
206 * @param method The method to invoke together with the parameters.
207 * @sa CHECK_ERROR2I_BREAK, CHECK_ERROR2_EX
208 */
209#define CHECK_ERROR2_BREAK(hrc, iface, method) CHECK_ERROR2_EX(RT_NOTHING, hrc, iface, method, break)
210/**
211 * Simplified version of CHECK_ERROR2_EX that executes the |break| statement
212 * after error reporting and that uses an internal variable |hrcCheck| for
213 * holding the result.
214 *
215 * @param iface The interface pointer (can be a smart pointer object).
216 * @param method The method to invoke together with the parameters.
217 * @sa CHECK_ERROR2_BREAK, CHECK_ERROR2_EX
218 */
219#define CHECK_ERROR2I_BREAK(iface, method) CHECK_ERROR2_EX(HRESULT, hrcCheck, iface, method, break)
220
221
222/**
223 * Does the same as CHECK_ERROR(), but executes the |return ret| statement on
224 * failure.
225 * @sa CHECK_ERROR2_RET, CHECK_ERROR2I_RET
226 */
227#define CHECK_ERROR_RET(iface, method, ret) \
228 do { \
229 rc = iface->method; \
230 if (FAILED(rc)) \
231 { \
232 com::GlueHandleComError(iface, #method, rc, __FILE__, __LINE__); \
233 return (ret); \
234 } \
235 } while (0)
236/**
237 * Simplified version of CHECK_ERROR2_EX that executes the |return (rcRet)|
238 * statement after error reporting.
239 *
240 * @param hrc The result variable (type HRESULT).
241 * @param iface The interface pointer (can be a smart pointer object).
242 * @param method The method to invoke together with the parameters.
243 * @param rcRet What to return on failure.
244 */
245#define CHECK_ERROR2_RET(hrc, iface, method, rcRet) CHECK_ERROR2_EX(RT_NOTHING, hrc, iface, method, return (rcRet))
246/**
247 * Simplified version of CHECK_ERROR2_EX that executes the |return (rcRet)|
248 * statement after error reporting and that uses an internal variable |hrcCheck|
249 * for holding the result.
250 *
251 * @param iface The interface pointer (can be a smart pointer object).
252 * @param method The method to invoke together with the parameters.
253 * @param rcRet What to return on failure. Use |hrcCheck| to return
254 * the status code of the method call.
255 */
256#define CHECK_ERROR2I_RET(iface, method, rcRet) CHECK_ERROR2_EX(HRESULT, hrcCheck, iface, method, return (rcRet))
257
258
259/**
260 * Check the progress object for an error and if there is one print out the
261 * extended error information.
262 * @remarks Requires HRESULT variable named @a rc.
263 */
264#define CHECK_PROGRESS_ERROR(progress, msg) \
265 do { \
266 LONG iRc; \
267 rc = progress->COMGETTER(ResultCode)(&iRc); \
268 if (FAILED(rc) || FAILED(iRc)) \
269 { \
270 if (SUCCEEDED(rc)) rc = iRc; else iRc = rc; \
271 RTMsgError msg; \
272 com::GlueHandleComErrorProgress(progress, __PRETTY_FUNCTION__, iRc, __FILE__, __LINE__); \
273 } \
274 } while (0)
275
276/**
277 * Does the same as CHECK_PROGRESS_ERROR(), but executes the |break| statement
278 * on failure.
279 * @remarks Requires HRESULT variable named @a rc.
280 */
281#ifdef __GNUC__
282# define CHECK_PROGRESS_ERROR_BREAK(progress, msg) \
283 __extension__ \
284 ({ \
285 LONG iRc; \
286 rc = progress->COMGETTER(ResultCode)(&iRc); \
287 if (FAILED(rc) || FAILED(iRc)) \
288 { \
289 if (SUCCEEDED(rc)) rc = iRc; else iRc = rc; \
290 RTMsgError msg; \
291 com::GlueHandleComErrorProgress(progress, __PRETTY_FUNCTION__, iRc, __FILE__, __LINE__); \
292 break; \
293 } \
294 })
295#else
296#define CHECK_PROGRESS_ERROR_BREAK(progress, msg) \
297 if (1) \
298 { \
299 LONG iRc; \
300 rc = progress->COMGETTER(ResultCode)(&iRc); \
301 if (FAILED(rc) || FAILED(iRc)) \
302 { \
303 if (SUCCEEDED(rc)) rc = iRc; else iRc = rc; \
304 RTMsgError msg; \
305 com::GlueHandleComErrorProgress(progress, __PRETTY_FUNCTION__, iRc, __FILE__, __LINE__); \
306 break; \
307 } \
308 } \
309 else do {} while (0)
310#endif
311
312/**
313 * Does the same as CHECK_PROGRESS_ERROR(), but executes the |return ret|
314 * statement on failure.
315 */
316#define CHECK_PROGRESS_ERROR_RET(progress, msg, ret) \
317 do { \
318 LONG iRc; \
319 HRESULT hrcCheck = progress->COMGETTER(ResultCode)(&iRc); \
320 if (SUCCEEDED(hrcCheck) && SUCCEEDED(iRc)) \
321 { /* likely */ } \
322 else \
323 { \
324 RTMsgError msg; \
325 com::GlueHandleComErrorProgress(progress, __PRETTY_FUNCTION__, \
326 SUCCEEDED(hrcCheck) ? iRc : hrcCheck, __FILE__, __LINE__); \
327 return (ret); \
328 } \
329 } while (0)
330
331/**
332 * Asserts the given expression is true. When the expression is false, prints
333 * a line containing the failed function/line/file; otherwise does nothing.
334 */
335#define ASSERT(expr) \
336 do { \
337 if (!(expr)) \
338 { \
339 RTPrintf ("[!] ASSERTION FAILED at line %d: %s\n", __LINE__, #expr); \
340 Log (("[!] ASSERTION FAILED at line %d: %s\n", __LINE__, #expr)); \
341 } \
342 } while (0)
343
344#endif
345
346/**
347 * Does the same as ASSERT(), but executes the |return ret| statement if the
348 * expression to assert is false;
349 * @remarks WARNING! @a expr is evalutated TWICE!
350 */
351#define ASSERT_RET(expr, ret) \
352 do { ASSERT(expr); if (!(expr)) return (ret); } while (0)
353
354/**
355 * Does the same as ASSERT(), but executes the |break| statement if the
356 * expression to assert is false;
357 * @remarks WARNING! @a expr is evalutated TWICE!
358 */
359#define ASSERT_BREAK(expr, ret) \
360 if (1) { ASSERT(expr); if (!(expr)) break; } else do {} while (0)
361
362} /* namespace com */
363
364/** @} */
365
366
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette