/*=========================================================================== 
    (c) Copyright 1998-2000, Emmanuel KARTMANN, all rights reserved                 
  =========================================================================== 
    File           : WindowsErrorText.h
    $Header: $
    Author         : Emmanuel KARTMANN
    Creation       : Monday 11/15/98 10:35:27 PM
    Remake         : 
  ------------------------------- Description ------------------------------- 

           Declaration of the WindowsGetErrorText function.

  ------------------------------ Modifications ------------------------------ 
    $Log: $  
  =========================================================================== 
*/

#ifndef _WINDOWS_ERROR_TEXT_
#define _WINDOWS_ERROR_TEXT_


/////////////////////////////////////////////////////////////////////
//
// <U>Purpose:</U> return the text for a given Windows Error Code
//
// <U>Parameters:</U> 
//
//       [in] dwErrorCode
//                WIN32 error code (e.g. returned by "GetLastError")
//       [out] lpszBuf
//                buffer where the error text will be written
//       [in] dwSize
//                size of the buffer (maximum size for the error text)
//
// <U>Return value :</U> LPTSTR = error text (points to lpszBuf)
//
// <U>Description  :</U> This function is a wrapper for many error-handling
//                       functions from WIN32. It searches for error text
//                       in the following locations:
//
//  <UL>
//      <LI>In the Operating System, using function FormatMessage (...FORMAT_MESSAGE_FROM_SYSTEM...)
//      <LI>In an hard-coded table for Windows Socket (Winsock) error code (see function WindowsSocketGetErrorText())
//      <LI>In specific modules, using function FormatMessage (...FORMAT_MESSAGE_FROM_HMODULE...):
//      <UL>
//          <LI>wininet.dll (Win32 Internet Errors)
//          <LI>mqutil.dll (Microsoft Message Queue Errors)
//      </UL>
//      <LI>In Extended Internet Errors, using function InternetGetLastResponseInfo()
//  </UL>
//
//  If no error text is found, this function still builds an error message
//  with the format "Error Code 0x%X (%d)" (the error code is shown is hexadecimal
//  and in decimal).
//
LPTSTR WindowsGetErrorText(DWORD dwErrorCode, LPTSTR lpszBuf, DWORD dwSize);


/////////////////////////////////////////////////////////////////////
//
// <U>Purpose:</U> return the clear-text message for a Windows Socket
//                 (winsock) error code.
//
// <U>Parameters:</U> 
//
//       [in] dwErrorCode
//                winsock error code (should be above WSABASEERR = 10000)
//       [out] lplpszTemp
//                clear-text error message
//
// <U>Return value :</U> DWORD = length of the error message, or 0
//                               if the error code cannot be mapped
//                               (not a Winsock error code).
//
// <U>Description  :</U> Winsock error codes cannot be correctly mapped
//                       to clear-text messages using WIN32 function 
//                       FormatMessage (try it; you'll be surprised).
//                       This function uses an hard-coded table
//                       to map code to their real clear-text messages.
//
//                       The calling application must free the string
//                       allocated in variable lplpszTemp 
//                       (using WIN32 function LocalFree()).
//
DWORD WindowsSocketGetErrorText(DWORD dwErrorCode, LPTSTR *lplpszTemp);

#endif // _WINDOWS_ERROR_TEXT_