windows-xp/Source/XPSP1/NT/net/tapi/skywalker/h323tsp/address.c

/*++

Copyright (c) 1997  Microsoft Corporation

Module Name:

    address.c

Abstract:

    TAPI Service Provider functions related to manipulating addresses.

        TSPI_lineGetAddressCaps
        TSPI_lineGetAddressStatus

Environment:

    User Mode - Win32

--*/
 
///////////////////////////////////////////////////////////////////////////////
//                                                                           //
// Include files                                                             //
//                                                                           //
///////////////////////////////////////////////////////////////////////////////

#include "globals.h"
#include "provider.h"
#include "version.h"
#include "line.h"


///////////////////////////////////////////////////////////////////////////////
//                                                                           //
// TSPI procedures                                                           //
//                                                                           //
///////////////////////////////////////////////////////////////////////////////

LONG
TSPIAPI
TSPI_lineGetAddressCaps(
    DWORD             dwDeviceID,
    DWORD             dwAddressID,
    DWORD             dwTSPIVersion,
    DWORD             dwExtVersion,
    LPLINEADDRESSCAPS pAddressCaps
    )
    
/*++

Routine Description:

    This function queries the specified address on the specified line device 
    to determine its telephony capabilities.

    The line device IDs supported by a particular driver are numbered 
    sequentially starting at a value set by the TAPI DLL using the 
    TSPI_lineSetDeviceIDBase function.

    The version number supplied has been negotiated by the TAPI DLL using 
    TSPI_lineNegotiateTSPIVersion.

Arguments:

    dwDeviceID - Specifies the line device containing the address to be 
        queried.

    dwAddressID - Specifies the address on the given line device whose 
        capabilities are to be queried.

    dwTSPIVersion - Specifies the version number of the Telephony SPI to be 
        used. The high order word contains the major version number; the low 
        order word contains the minor version number.

    dwExtVersion - Specifies the version number of the service 
        provider-specific extensions to be used. This number can be left 
        zero if no device specific extensions are to be used. Otherwise, 
        the high order word contains the major version number; the low 
        order word contain the minor version number.

    pAddressCaps - Specifies a far pointer to a variable sized structure 
        of type LINEADDRESSCAPS. Upon successful completion of the request, 
        this structure is filled with address capabilities information.

Return Values:

    Returns zero if the function is successful or a negative error
    number if an error has occurred. Possible error returns are:

        LINEERR_BADDEVICEID - The specified line device ID is out of the range 
            of line devices IDs supported by this driver.

        LINEERR_INVALADDRESSID - The specified address ID is out of range.

        LINEERR_INCOMPATIBLEVERSION - The specified TSPI and/or extension 
            version number is not supported by the Service Provider for the 
            specified line device.

        LINEERR_INVALEXTVERSION - The app requested an invalid extension 
            version number.

        LINEERR_STRUCTURETOOSMALL - The dwTotalSize member of a structure 
            does not specify enough memory to contain the fixed portion of 
            the structure. The dwNeededSize field has been set to the amount 
            required.

--*/

{
    DWORD dwAddressSize;
    PH323_LINE pLine = NULL;

    // make sure this is a version we support    
    if (!H323ValidateTSPIVersion(dwTSPIVersion)) {

        // do not support tspi version
        return LINEERR_INCOMPATIBLEAPIVERSION;
    }

    // make sure this is a version we support    
    if (!H323ValidateExtVersion(dwExtVersion)) {

        // do not support extensions 
        return LINEERR_INVALEXTVERSION;
    }

    // make sure address id is supported
    if (!H323IsValidAddressID(dwAddressID)) {

        // invalid address id
        return LINEERR_INVALADDRESSID;
    }

    // retrieve line device pointer from device id
    if (!H323GetLineFromIDAndLock(&pLine, dwDeviceID)) {

        // invalid line device id
        return LINEERR_BADDEVICEID;
    }

    // determine size of address name
    dwAddressSize = H323SizeOfWSZ(pLine->wszAddr);

    // calculate number of bytes needed
    pAddressCaps->dwNeededSize = sizeof(LINEADDRESSCAPS) + 
                                 dwAddressSize
                                 ;

    // validate buffer allocated is large enough
    if (pAddressCaps->dwTotalSize >= pAddressCaps->dwNeededSize) {

        // record amount of memory used
        pAddressCaps->dwUsedSize = pAddressCaps->dwNeededSize;

        // position address name after fixed portion
        pAddressCaps->dwAddressSize = dwAddressSize;
        pAddressCaps->dwAddressOffset = sizeof(LINEADDRESSCAPS);
    
        // copy address name after fixed portion
        memcpy((LPBYTE)pAddressCaps + pAddressCaps->dwAddressOffset, 
               (LPBYTE)pLine->wszAddr,
               pAddressCaps->dwAddressSize
               );
           
    } else if (pAddressCaps->dwTotalSize >= sizeof(LINEADDRESSCAPS)) {

        H323DBG((
            DEBUG_LEVEL_WARNING,
            "lineaddresscaps structure too small for strings.\n"
            ));

        // record amount of memory used
        pAddressCaps->dwUsedSize = sizeof(LINEADDRESSCAPS);

    } else {
                                 
        H323DBG((
            DEBUG_LEVEL_ERROR,
            "lineaddresscaps structure too small.\n"
            ));

        // release line device
        H323UnlockLine(pLine);

        // allocated structure too small 
        return LINEERR_STRUCTURETOOSMALL;
    }

    H323DBG((
        DEBUG_LEVEL_VERBOSE,
        "addr 0 capabilities requested.\n"
        ));
    
    // transfer associated device id 
    pAddressCaps->dwLineDeviceID = dwDeviceID;

    // initialize number of calls allowed per address 
    pAddressCaps->dwMaxNumActiveCalls = H323_MAXCALLSPERADDR;

    // initialize supported address capabilities
    pAddressCaps->dwAddressSharing     = H323_ADDR_ADDRESSSHARING;
    pAddressCaps->dwCallInfoStates     = H323_ADDR_CALLINFOSTATES;
    pAddressCaps->dwCallStates         = H323_ADDR_CALLSTATES;
    pAddressCaps->dwDisconnectModes    = H323_ADDR_DISCONNECTMODES;
    pAddressCaps->dwAddrCapFlags       = H323_ADDR_CAPFLAGS;
    pAddressCaps->dwCallFeatures       = H323_ADDR_CALLFEATURES;
    pAddressCaps->dwAddressFeatures    = H323_ADDR_ADDRFEATURES;
    pAddressCaps->dwCallerIDFlags      = H323_ADDR_CALLERIDFLAGS;
    pAddressCaps->dwCalledIDFlags      = H323_ADDR_CALLEDIDFLAGS;

    // initialize unsupported address capabilities
    pAddressCaps->dwConnectedIDFlags   = LINECALLPARTYID_UNAVAIL;
    pAddressCaps->dwRedirectionIDFlags = LINECALLPARTYID_UNAVAIL;
    pAddressCaps->dwRedirectingIDFlags = LINECALLPARTYID_UNAVAIL;
    
    // release line device
    H323UnlockLine(pLine);

    // success
    return NOERROR;
}


LONG
TSPIAPI
TSPI_lineGetAddressStatus(
    HDRVLINE            hdLine,
    DWORD               dwAddressID,
    LPLINEADDRESSSTATUS pAddressStatus
    )
    
/*++

Routine Description:

    This operation allows the TAPI DLL to query the specified address for its 
    current status.

Arguments:

    hdLine - Specifies the Service Provider's opaque handle to the line 
        containing the address to be queried.

    dwAddressID - Specifies an address on the given open line device. 
        This is the address to be queried.

    pAddressStatus - Specifies a far pointer to a variable sized data 
        structure of type LINEADDRESSSTATUS.

Return Values:

    Returns zero if the function is successful or a negative error
    number if an error has occurred. Possible error returns are:

        LINEERR_INVALLINEHANDLE - The specified device handle is invalid.

        LINEERR_INVALADDRESSID - The specified address ID is out of range.

        LINEERR_STRUCTURETOOSMALL - The dwTotalSize member of a structure 
            does not specify enough memory to contain the fixed portion of 
            the structure. The dwNeededSize field has been set to the amount 
            required.

--*/

{
    PH323_LINE pLine = NULL;

    // make sure address id is supported
    if (!H323IsValidAddressID(dwAddressID)) {

        // invalid address id
        return LINEERR_INVALADDRESSID;
    }

    // retrieve line device pointer from handle
    if (!H323GetLineAndLock(&pLine, hdLine)) {

        // invalid line device handle
        return LINEERR_INVALLINEHANDLE;
    }

    // calculate the number of bytes required
    pAddressStatus->dwNeededSize = sizeof(LINEADDRESSSTATUS);

    // see if lineaddressstatus structure is of correct size
    if (pAddressStatus->dwTotalSize < pAddressStatus->dwNeededSize) {

        H323DBG((
            DEBUG_LEVEL_ERROR,
            "lineaddressstatus structure too small.\n"
            ));

        // release line device
        H323UnlockLine(pLine);

        // allocated structure too small 
        return LINEERR_STRUCTURETOOSMALL;
    }

    // record amount of memory used
    pAddressStatus->dwUsedSize = pAddressStatus->dwNeededSize;

    // transfer number of active calls from line device structure
    pAddressStatus->dwNumActiveCalls = pLine->pCallTable->dwNumInUse;
    
    // specify that outbound call is possible on the address
    pAddressStatus->dwAddressFeatures = H323_ADDR_ADDRFEATURES;    

    // release line device
    H323UnlockLine(pLine);

    // success
    return NOERROR;
}