tapiinfo.c

一份有用的TAPI编程源码

//    This is the actual function that OutputDebugLineError
//    expands to.  Its not likely to be usefull except
//    through the OutputDebugLineError macro, or to print
//    errors without line and file information.
//
//    If szFileName == NULL, then the File and Line are not printed.
//   
//    Note that there is an internal string length limit of
//    MAXOUTPUTSTRINGLENGTH.  If this length is exceeded,
//    the behavior will be the same as wsprintf, although
//    it will be undetectable.  *KEEP szPrefix SHORT!*
//
//

void OutputDebugLineErrorFileLine(
    long lLineError, LPSTR szPrefix, 
    LPSTR szFileName, DWORD nLineNumber)
{
    LPSTR szLineError;
    char szOutputLineError[MAXOUTPUTSTRINGLENGTH];

    if (szPrefix == NULL)
        szPrefix = "";

    // Pretty print the error message.
    szLineError = FormatLineError(lLineError, NULL, 0);

    // The only reason FormatLineError should fail is "Out of memory".
    if (szLineError == NULL)
    {
        if (szFileName == NULL)
            wsprintf(szOutputLineError, "%sOut of memory", szPrefix);
        else
            wsprintf(szOutputLineError, 
                "%sOut of memory in file %s, line %d\r\n",
                szPrefix, szFileName, nLineNumber);

        OutputDebugString(szOutputLineError);

        return;
    }

    // If szFileName, then use it; else don't.
    if (szFileName != NULL)
    {
        wsprintf(szOutputLineError,
            "%sTapi Line Error: \"%s\" in File \"%s\", Line %d\r\n",
            szPrefix, szLineError, szFileName, nLineNumber);
    }
    else
    {
        wsprintf(szOutputLineError,
            "%sTapi Line Error: \"%s\"\r\n",
            szPrefix, szLineError);
    }

    // Pointer returned from FormatLineError *must* be freed!
    LocalFree(szLineError);

    // Print it!
    OutputDebugString(szOutputLineError);

    return;
}


//
//  FUNCTION: FormatLineError(long, LPSTR, DWORD)
//
//  PURPOSE: Pretty print a line error to a string.
//
//  PARAMETERS:
//    lLineError           - Actual error code to decipher.
//    szOutputBuffer       - String buffer to pretty print to.
//    dwSizeofOutputBuffer - Size of String buffer.
//
//  RETURN VALUE:
//    Returns the buffer printed to.
//
//  COMMENTS:
//    If szOutputBuffer isn't big enough to hold the whole string,
//    then the string gets truncated to fit the buffer.
//
//    If szOutputBuffer == NULL, then dwSizeofOutputBuffer
//    is ignored, a buffer 'big enough' is LocalAlloc()d and
//    a pointer to it is returned.  However, its *very* important
//    that this pointer be LocalFree()d by the calling application.
//
//

LPSTR FormatLineError(long lLineError,
    LPSTR szOutputBuffer, DWORD dwSizeofOutputBuffer)
{
    char szUnknownLineError[256];
    LPSTR szLineError;
    int nSizeofLineError;
    long lErrorIndex;
    DWORD * pdwLineError;

    // Strip off the high bit to make the error code positive.
    pdwLineError = &lLineError;
    lErrorIndex = (long) (0x7FFFFFFF & *pdwLineError);

    // Is it an unknown error?
    if ((lErrorIndex >= sizeofArray(pszLineErrorNameArray)) ||
        (lErrorIndex < 0))
    {
        nSizeofLineError = 
            wsprintf(szUnknownLineError, "Unknown TAPI line error code: 0x%lx",
                lLineError);
        szLineError = szUnknownLineError;
    }
    else
    {
        szLineError = pszLineErrorNameArray[lErrorIndex];
        nSizeofLineError = strlen(szLineError);
    }

    // allocate a buffer if necessary
    if (szOutputBuffer == NULL)
    {
        szOutputBuffer = (LPSTR) LocalAlloc(LPTR, nSizeofLineError + 1);
        if (szOutputBuffer == NULL)
            return NULL;
    }
    else // truncate string if it won't fit in the specified buffer.
    {
        if ((DWORD) nSizeofLineError >= dwSizeofOutputBuffer)
            nSizeofLineError = dwSizeofOutputBuffer - 1;
    }

    // Put the string into the buffer and null terminate.
    memcpy(szOutputBuffer, szLineError, nSizeofLineError);
    szOutputBuffer[nSizeofLineError] = '\0';

    return szOutputBuffer;
}


//
//  MACRO: OutputDebugLastError(DWORD, LPSTR)
//
//  PURPOSE: Pretty print a system error to the debugging output.
//
//  PARAMETERS:
//    dwLastError - Actual error code to decipher.
//    pszPrefix   - String to prepend to the printed message.
//
//  RETURN VALUE:
//    none
//
//  COMMENTS:
//    This macro is actually defined in the .h file.
//    It will take an error that was retrieved by GetLastError(),
//    turn it into a human readable string, prepend pszPrefix
//    (so you can tag your errors), append __FILE__ and __LINE__
//    and print it to the debugging output.
//
//    This macro is just a wrapper around OutputDebugLastErrorFileLine
//    that is necessary to get proper values for __FILE__ and __LINE__.
//
//

/*
#define OuputDebugLastError(dwLastError, pszPrefix) \
    OutputDebugLastErrorFileLine(dwLastError, pszPrefix,\
        __FILE__, __LINE__)
*/


//
//  FUNCTION: OutputDebugLastErrorFileLine(..)
//
//  PURPOSE: Pretty print a line error to the debugging output.
//
//  PARAMETERS:
//    dwLastError - Actual error code to decipher.
//    pszPrefix   - String to prepend to the printed message.
//    szFileName  - Filename the error occured in.
//    nLineNumber - Line number the error occured at.
//
//  RETURN VALUE:
//    none
//
//  COMMENTS:
//    This is the actual function that OutputDebugLastError
//    expands to.  Its not likely to be usefull except
//    through the OutputDebugLastError macro or to print
//    errors without line and file information.
//
//    If szFileName == NULL, then the File and Line are not printed.
//   
//    Note that there is an internal string length limit of
//    MAXOUTPUTSTRINGLENGTH.  If this length is exceeded,
//    the behavior will be the same as wsprintf, although
//    it will be undetectable.  *KEEP szPrefix SHORT!*
//
//

void OutputDebugLastErrorFileLine(
    DWORD dwLastError, LPSTR szPrefix, 
    LPSTR szFileName, DWORD nLineNumber)
{
    LPSTR szLastError;
    char szOutputLastError[MAXOUTPUTSTRINGLENGTH];

    if (szPrefix == NULL)
        szPrefix = "";

    // Pretty print the error.
    szLastError = FormatLastError(dwLastError, NULL, 0);

    // The only reason FormatLastError should fail is "Out of memory".
    if (szLastError == NULL)
    {
        if (szFileName == NULL)
            wsprintf(szOutputLastError, "%sOut of memory\r\n", szPrefix);
        else
            wsprintf(szOutputLastError, "%sOut of memory in file %s, line %d\r\n",
                szPrefix, szFileName, nLineNumber);

        OutputDebugString(szOutputLastError);

        return;
    }

    // If szFileName, then use it; else don't.
    if (szFileName != NULL)
    {
        wsprintf(szOutputLastError,
            "%sGetLastError returned: \"%s\" in File \"%s\", Line %d\r\n",
            szPrefix, szLastError, szFileName, nLineNumber);
    }
    else
    {
        wsprintf(szOutputLastError,
            "%sGetLastError returned: \"%s\"\r\n",
            szPrefix, szLastError);
    }

    // Pointer returned from FormatLineError *must* be freed!
    LocalFree(szLastError);

    // Print it!
    OutputDebugString(szOutputLastError);
    return;
}


//
//  FUNCTION: FormatLastError(DWORD, LPSTR, DWORD)
//
//  PURPOSE: Pretty print a system error to a string.
//
//  PARAMETERS:
//    dwLastError          - Actual error code to decipher.
//    szOutputBuffer       - String buffer to pretty print to.
//    dwSizeofOutputBuffer - Size of String buffer.
//
//  RETURN VALUE:
//    Returns the buffer printed to.
//
//  COMMENTS:
//    If szOutputBuffer isn't big enough to hold the whole string,
//    then the string gets truncated to fit the buffer.
//
//    If szOutputBuffer == NULL, then dwSizeofOutputBuffer
//    is ignored, a buffer 'big enough' is LocalAlloc()d and
//    a pointer to it is returned.  However, its *very* important
//    that this pointer be LocalFree()d by the calling application.
//
//

LPSTR FormatLastError(DWORD dwLastError,
    LPSTR szOutputBuffer, DWORD dwSizeofOutputBuffer)
{
    DWORD dwRetFM;
    DWORD dwFlags = FORMAT_MESSAGE_FROM_SYSTEM;

    // Should we allocate a buffer?
    if (szOutputBuffer == NULL)
    {
        // Actually, we make FormatMessage allocate the buffer, if needed.
        dwFlags |= FORMAT_MESSAGE_ALLOCATE_BUFFER;

        // minimum size FormatMessage should allocate.
        dwSizeofOutputBuffer = 1;  
    }

    // Make FormatMessage pretty print the system error.
    dwRetFM = FormatMessage(
        dwFlags, NULL, dwLastError,
        MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US),
        (LPTSTR) &szOutputBuffer, dwSizeofOutputBuffer,
        NULL);

    // FormatMessage failed to print the error.
    if (dwRetFM == 0)
    {
        DWORD dwGetLastError;
        LPSTR szFormatMessageError;

        dwGetLastError = GetLastError();

        // If we asked FormatMessage to allocate a buffer, then it
        // might have allocated one.  Lets be safe and LocalFree it.
        if (dwFlags & FORMAT_MESSAGE_ALLOCATE_BUFFER)
        {
            __try
            {
                LocalFree(szOutputBuffer);
            }
            __except(EXCEPTION_EXECUTE_HANDLER)
            {
                // Actually, we do nothing for this fault.  If
                // there was a fault, it meant the buffer wasn't
                // allocated, and the LocalFree was unnecessary.
                ;
            }

            szOutputBuffer = LocalAlloc(LPTR, MAXOUTPUTSTRINGLENGTH);
            dwSizeofOutputBuffer = MAXOUTPUTSTRINGLENGTH;

            if (szOutputBuffer == NULL)
            {
                OutputDebugString("Out of memory trying to FormatLastError\r\n");
                return NULL;
            }
        }

        szFormatMessageError = 
            FormatLastError(dwGetLastError, NULL, 0);

        if (szFormatMessageError == NULL)
            return NULL;

        wsprintf(szOutputBuffer, 
            "FormatMessage failed on error 0x%lx for the following reason: %s",
            dwLastError, szFormatMessageError);

        LocalFree(szFormatMessageError);
    }

    return szOutputBuffer;
}


//
//  FUNCTION: OutputDebugLineCallback(...)
//
//  PURPOSE: Pretty print a message passed into a lineCallbackFunc.
//
//  PARAMETERS:
//    Standard lineCallbackFunc parameters.
//
//  RETURN VALUE:
//    none.
//
//  COMMENTS:
//
//    This function takes all of the parameters passed into a
//    lineCallbackFunc callback function, and pretty prints the
//    meaning of the message.  It then prints the result to
//    the debugging output.
//
//

void OutputDebugLineCallback(
    DWORD dwDevice, DWORD dwMsg, DWORD dwCallbackInstance, 
    DWORD dwParam1, DWORD dwParam2, DWORD dwParam3)
{
    char szOutputBuff[MAXOUTPUTSTRINGLENGTH];

    FormatLineCallback(szOutputBuff, 
        dwDevice, dwMsg, dwCallbackInstance, 
        dwParam1, dwParam2, dwParam3);

    strcat(szOutputBuff,"\r\n");

    OutputDebugString(szOutputBuff);
}


//
//  FUNCTION: FormatLineCallback(...)
//
//  PURPOSE: Pretty prints into a buffer a lineCallbackFunc message.
//
//  PARAMETERS:
//    Standard lineCallbackFunc parameters.
//
//  RETURN VALUE:
//    The pointer to the buffer that has the resulting string.
//
//  COMMENTS:
//
//    This function takes all of the parameters passed into a
//    lineCallbackFunc callback function, and pretty prints the
//    meaning of the message.  It then returns the pointer to
//    the buffer containing this string.
//
//    If szOutputBuffer == NULL, then a buffer is LocalAlloc()d
//    and returned.  However, it is *very* important that this buffer
//    is LocalFree()d.
//

LPSTR FormatLineCallback(LPSTR szOutputBuffer,
    DWORD dwDevice, DWORD dwMsg, DWORD dwCallbackInstance, 
    DWORD dwParam1, DWORD dwParam2, DWORD dwParam3)
{
    long lBufferIndex = 0;

    // Allocate the buffer if necessary.
    if (szOutputBuffer == NULL)
    {
        szOutputBuffer = (LPSTR) LocalAlloc(LPTR, MAXOUTPUTSTRINGLENGTH);

        if (szOutputBuffer == NULL)
            return NULL;
    }

    // Is this a known message?
    if (dwMsg >= sizeofArray(psz_dwMsg))
    {
        wsprintf(szOutputBuffer, "lineCallback: Unknown dwMsg: '0x%lx', "
            "dwDevice: '0x%lx', dwCallbackInstance: '0x%lx', "
            "dwParam1: '0x%lx', dwParam2: '0x%lx', dwParam3: '0x%lx'", dwMsg, 
            dwDevice, dwCallbackInstance, dwParam1, dwParam2, dwParam3);
        return szOutputBuffer;
    }

    // Lets start pretty printing.
    lBufferIndex +=
        wsprintf(szOutputBuffer, "lineCallback: %s; dwDevice: '0x%lx'; ",
            psz_dwMsg[dwMsg], dwDevice);

    // Which message was it?  And start decoding it!