Index: /trunk/include/iprt/err.h =================================================================== --- /trunk/include/iprt/err.h (revision 35181) +++ /trunk/include/iprt/err.h (revision 35182) @@ -29,4 +29,5 @@ #include #include +#include @@ -279,5 +280,4 @@ */ RTDECL(int) RTErrConvertToErrno(int iErr); - #ifdef IN_RING3 @@ -392,4 +392,152 @@ #endif /* IN_RING3 */ + +/** @defgroup RTERRINFO_FLAGS_XXX RTERRINFO::fFlags + * @{ */ +/** Custom structure (the default). */ +#define RTERRINFO_FLAGS_T_CUSTOM UINT32_C(0) +/** Static structure (RTERRINFOSTATIC). */ +#define RTERRINFO_FLAGS_T_STATIC UINT32_C(1) +/** Allocated structure (RTErrInfoAlloc). */ +#define RTERRINFO_FLAGS_T_ALLOC UINT32_C(2) +/** Reserved type. */ +#define RTERRINFO_FLAGS_T_RESERVED UINT32_C(3) +/** Type mask. */ +#define RTERRINFO_FLAGS_T_MASK UINT32_C(3) +/** Error info is set. */ +#define RTERRINFO_FLAGS_SET RT_BIT_32(2) +/** Fixed flags (magic). */ +#define RTERRINFO_FLAGS_MAGIC UINT32_C(0xbabe0000) +/** The bit mask for the magic value. */ +#define RTERRINFO_FLAGS_MAGIC_MASK UINT32_C(0xffff0000) +/** @} */ + +/** + * Initializes an error info structure. + * + * @returns @a pErrInfo. + * @param pErrInfo The error info structure to init. + * @param pszMsg The message buffer. Must be at least one byte. + * @param cbMsg The size of the message buffer. + */ +DECLINLINE(PRTERRINFO) RTErrInfoInit(PRTERRINFO pErrInfo, char *pszMsg, size_t cbMsg) +{ + *pszMsg = '\0'; + + pErrInfo->fFlags = RTERRINFO_FLAGS_T_CUSTOM | RTERRINFO_FLAGS_MAGIC; + pErrInfo->rc = /*VINF_SUCCESS*/ 0; + pErrInfo->pszMsg = pszMsg; + pErrInfo->cbMsg = cbMsg; + pErrInfo->apvReserved[0] = NULL; + pErrInfo->apvReserved[1] = NULL; + + return pErrInfo; +} + +/** + * Initialize a static error info structure. + * + * @param pStaticErrInfo The static error info structure to init. + */ +DECLINLINE(void) RTErrInfoInitStatic(PRTERRINFOSTATIC pStaticErrInfo) +{ + RTErrInfoInit(&pStaticErrInfo->Core, pStaticErrInfo->szMsg, sizeof(pStaticErrInfo->szMsg)); + pStaticErrInfo->Core.fFlags = RTERRINFO_FLAGS_T_STATIC | RTERRINFO_FLAGS_MAGIC; +} + +/** + * Allocates a error info structure with a buffer at least the given size. + * + * @returns Pointer to an error info structure on success, NULL on failure. + * + * @param cbMsg The minimum message buffer size. Use 0 to get + * the default buffer size. + */ +RTDECL(PRTERRINFO) RTErrInfoAlloc(size_t cbMsg); + +/** + * Same as RTErrInfoAlloc, except that an IPRT status code is returned. + * + * @returns IPRT status code. + * + * @param cbMsg The minimum message buffer size. Use 0 to get + * the default buffer size. + * @param ppErrInfo Where to store the pointer to the allocated + * error info structure on success. This is + * always set to NULL. + */ +RTDECL(int) RTErrInfoAllocEx(size_t cbMsg, PRTERRINFO *ppErrInfo); + +/** + * Frees an error info structure allocated by RTErrInfoAlloc or + * RTErrInfoAllocEx. + * + * @param pErrInfo The error info structure. + */ +RTDECL(void) RTErrInfoFree(PRTERRINFO pErrInfo); + +/** + * Fills in the error info details. + * + * @returns @a rc. + * + * @param pErrInfo The error info structure to fill in. + * @param rc The status code to return. + * @param pszMsg The error message string. + */ +RTDECL(int) RTErrInfoSet(PRTERRINFO pErrInfo, int rc, const char *pszMsg); + +/** + * Fills in the error info details, with a sprintf style message. + * + * @returns @a rc. + * + * @param pErrInfo The error info structure to fill in. + * @param rc The status code to return. + * @param pszFormat The format string. + * @param ... The format arguments. + */ +RTDECL(int) RTErrInfoSetF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...); + +/** + * Fills in the error info details, with a vsprintf style message. + * + * @returns @a rc. + * + * @param pErrInfo The error info structure to fill in. + * @param rc The status code to return. + * @param pszFormat The format string. + * @param va The format arguments. + */ +RTDECL(int) RTErrInfoSetV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va); + +/** + * Checks if the error info is set. + * + * @returns true if set, false if not. + * @param pErrInfo The error info structure. NULL is OK. + */ +DECLINLINE(bool) RTErrInfoIsSet(PCRTERRINFO pErrInfo) +{ + if (!pErrInfo) + return false; + return (pErrInfo->fFlags & (RTERRINFO_FLAGS_MAGIC_MASK | RTERRINFO_FLAGS_SET)) + == (RTERRINFO_FLAGS_MAGIC | RTERRINFO_FLAGS_SET); +} + +/** + * Clears the error info structure. + * + * @param pErrInfo The error info structure. NULL is OK. + */ +DECLINLINE(void) RTErrInfoClear(PRTERRINFO pErrInfo) +{ + if (pErrInfo) + { + pErrInfo->fFlags &= ~RTERRINFO_FLAGS_SET; + pErrInfo->rc = /*VINF_SUCCESS*/0; + *pErrInfo->pszMsg = '\0'; + } +} RT_C_DECLS_END Index: /trunk/include/iprt/types.h =================================================================== --- /trunk/include/iprt/types.h (revision 35181) +++ /trunk/include/iprt/types.h (revision 35182) @@ -1647,10 +1647,51 @@ /** + * Error info. + * + * See RTErrInfo*. + */ +typedef struct RTERRINFO +{ + /** Flags, see RTERRINFO_FLAGS_XXX. */ + uint32_t fFlags; + /** The status code. */ + int32_t rc; + /** The size of the message */ + size_t cbMsg; + /** The error buffer. */ + char *pszMsg; + /** Reserved for future use. */ + void *apvReserved[2]; +} RTERRINFO; +/** Pointer to an error info structure. */ +typedef RTERRINFO *PRTERRINFO; +/** Pointer to a const error info structure. */ +typedef RTERRINFO const *PCRTERRINFO; + +/** + * Static error info structure, see RTErrInfoInitStatic. + */ +typedef struct RTERRINFOSTATIC +{ + /** The core error info. */ + RTERRINFO Core; + /** The static message buffer. */ + char szMsg[3072]; +} RTERRINFOSTATIC; +/** Pointer to a error info buffer. */ +typedef RTERRINFOSTATIC *PRTERRINFOSTATIC; +/** Pointer to a const static error info buffer. */ +typedef RTERRINFOSTATIC const *PCRTERRINFOSTATIC; + + +/** * UUID data type. * - * @note IPRT defines that the first three integers in the @c Gen struct - * interpretation are in little endian representation. This is different to - * many other UUID implementation, and requires conversion if you need to - * achieve consistent results. + * See RTUuid*. + * + * @remarks IPRT defines that the first three integers in the @c Gen struct + * interpretation are in little endian representation. This is + * different to many other UUID implementation, and requires + * conversion if you need to achieve consistent results. */ typedef union RTUUID @@ -1680,7 +1721,5 @@ typedef const RTUUID *PCRTUUID; -/** - * UUID string maximum length. - */ +/** UUID string maximum length. */ #define RTUUID_STR_LENGTH 37 @@ -1688,5 +1727,4 @@ /** Compression handle. */ typedef struct RTZIPCOMP *PRTZIPCOMP; - /** Decompressor handle. */ typedef struct RTZIPDECOMP *PRTZIPDECOMP; Index: /trunk/src/VBox/Runtime/Makefile.kmk =================================================================== --- /trunk/src/VBox/Runtime/Makefile.kmk (revision 35181) +++ /trunk/src/VBox/Runtime/Makefile.kmk (revision 35182) @@ -272,4 +272,5 @@ common/dbg/dbgmodcontainer.cpp \ common/dbg/dbgmodnm.cpp \ + common/err/errinfo.cpp \ common/err/errmsg.cpp \ common/err/RTErrConvertFromErrno.cpp \ Index: /trunk/src/VBox/Runtime/common/err/errinfo.cpp =================================================================== --- /trunk/src/VBox/Runtime/common/err/errinfo.cpp (revision 35182) +++ /trunk/src/VBox/Runtime/common/err/errinfo.cpp (revision 35182) @@ -0,0 +1,110 @@ +/* $Id$ */ +/** @file + * IPRT - Error Info. + */ + +/* + * Copyright (C) 2010 Oracle Corporation + * + * This file is part of VirtualBox Open Source Edition (OSE), as + * available from http://www.virtualbox.org. This file is free software; + * you can redistribute it and/or modify it under the terms of the GNU + * General Public License (GPL) as published by the Free Software + * Foundation, in version 2 as it comes in the "COPYING" file of the + * VirtualBox OSE distribution. VirtualBox OSE is distributed in the + * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. + * + * The contents of this file may alternatively be used under the terms + * of the Common Development and Distribution License Version 1.0 + * (CDDL) only, as it comes in the "COPYING.CDDL" file of the + * VirtualBox OSE distribution, in which case the provisions of the + * CDDL are applicable instead of those of the GPL. + * + * You may elect to license modified versions of this file under the + * terms and conditions of either the GPL or the CDDL or both. + */ + + +/******************************************************************************* +* Header Files * +*******************************************************************************/ +#include "internal/iprt.h" +#include + +#include +#include +#include + + + +RTDECL(PRTERRINFO) RTErrInfoAlloc(size_t cbMsg) +{ + PRTERRINFO pErrInfo; + RTErrInfoAllocEx(cbMsg, &pErrInfo); + return pErrInfo; +} + + +RTDECL(int) RTErrInfoAllocEx(size_t cbMsg, PRTERRINFO *ppErrInfo) +{ + if (cbMsg == 0) + cbMsg = _4K; + else + cbMsg = RT_ALIGN_Z(cbMsg, 256); + + PRTERRINFO pErrInfo; + *ppErrInfo = pErrInfo = (PRTERRINFO)RTMemTmpAlloc(sizeof(*pErrInfo) + cbMsg); + if (RT_UNLIKELY(pErrInfo)) + return VERR_NO_TMP_MEMORY; + + RTErrInfoInit(pErrInfo, (char *)(pErrInfo + 1), cbMsg); + pErrInfo->fFlags = RTERRINFO_FLAGS_T_ALLOC | RTERRINFO_FLAGS_MAGIC; + return VINF_SUCCESS; +} + + +RTDECL(void) RTErrInfoFree(PRTERRINFO pErrInfo) +{ + RTMemTmpFree(pErrInfo); +} + + +RTDECL(int) RTErrInfoSet(PRTERRINFO pErrInfo, int rc, const char *pszMsg) +{ + if (pErrInfo) + { + AssertPtr(pErrInfo); + Assert((pErrInfo->fFlags & RTERRINFO_FLAGS_MAGIC_MASK) == RTERRINFO_FLAGS_MAGIC); + + RTStrCopy(pErrInfo->pszMsg, pErrInfo->cbMsg, pszMsg); + pErrInfo->rc = rc; + pErrInfo->fFlags |= RTERRINFO_FLAGS_SET; + } + return rc; +} + + +RTDECL(int) RTErrInfoSetF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) +{ + va_list va; + va_start(va, pszFormat); + RTErrInfoSetV(pErrInfo, rc, pszFormat, va); + va_end(va); + return rc; +} + + +RTDECL(int) RTErrInfoSetV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) +{ + if (pErrInfo) + { + AssertPtr(pErrInfo); + Assert((pErrInfo->fFlags & RTERRINFO_FLAGS_MAGIC_MASK) == RTERRINFO_FLAGS_MAGIC); + + RTStrPrintfV(pErrInfo->pszMsg, pErrInfo->cbMsg, pszFormat, va); + pErrInfo->rc = rc; + pErrInfo->fFlags |= RTERRINFO_FLAGS_SET; + } + return rc; +} +