C-C++ Code Example: Reading Error Codes

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

This example provides an application-defined function that accepts a Message Queuing or Win32 error code returned in the HRESULT or DWORD return value of a call and returns a description of the error.

This function has the following parameters:

• dwErrorCode: [in] Error code.

• pErrorText: [out] Pointer to a pointer to a buffer that receives a null-terminated string containing the error description.

• pnSize: [out] Number of TCHAR characters.

After calling this function, the caller should use the LocalFree function to free the buffer that contains the returned error description.

Code Example

#define MQDLL_W_ERROR_TEXT  TEXT("MQutil.dll")  
HRESULT GetErrorText(  
                     DWORD dwErrorCode,  
                     TCHAR **ppErrorText,  
                     DWORD *pdwSize  
                     )  
{  
  HMODULE hMod = NULL;  
  TCHAR * pMsgBuf = NULL;  
  DWORD dwSize = 0;  
  
  // Validate the input parameters  
  if (ppErrorText == NULL || pdwSize == NULL)  
  {  
    return ERROR_INVALID_PARAMETER;  
  }  
  
  // Initialize the two OUT parameters  
  *ppErrorText = NULL;  
  *pdwSize = 0;  
  
  if (HRESULT_FACILITY(dwErrorCode) == FACILITY_MSMQ)  
  {  
    // Load MQDLL_W_ERROR_TEXT DLL, i.e., MQutil.dll  
    hMod = LoadLibrary(MQDLL_W_ERROR_TEXT);  
  
    if (hMod)  
    {  
  
      // Use the FormatMessage API to translate the error code  
      dwSize = FormatMessage(FORMAT_MESSAGE_FROM_HMODULE |   
                             FORMAT_MESSAGE_ALLOCATE_BUFFER |  
                             FORMAT_MESSAGE_IGNORE_INSERTS,  
                             hMod, dwErrorCode, 0, (LPTSTR)&pMsgBuf, 0, NULL);  
  
      // Unload MQDLL_W_ERROR_TEXT DLL, i.e., MQutil.dll.  
      FreeLibrary(hMod);  
  
      // Return the description and size to the caller in the OUT parameters.  
      if (dwSize)  
      {  
        *pdwSize = dwSize;  
        *ppErrorText = (TCHAR*)pMsgBuf;  
        return S_OK;  
      }  
    }  
  
    // Return the error code.  
    return GetLastError();  
  }  
  else if (HRESULT_FACILITY(dwErrorCode) == FACILITY_WIN32)  
  {  
  
    // Retrieve the Win32 error message.  
    dwSize = FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_IGNORE_INSERTS,  
                           NULL, dwErrorCode, 0, (LPTSTR) &pMsgBuf, 0, NULL);  
  
    // Return the description and size to the caller in the OUT parameters.  
    if (dwSize)  
    {  
      *pdwSize = dwSize;  
      *ppErrorText = (TCHAR*)pMsgBuf;  
       return S_OK;  
    }  
  
    // Return the error code.  
    return GetLastError();  
  }  
  return ERROR_INVALID_PARAMETER;  
}