windows-xp/Source/XPSP1/NT/base/pnp/cfgmgr32/traverse.c

/*++

Copyright (c) 1995-2001  Microsoft Corporation

Module Name:

    traverse.c

Abstract:

    This module contains the API routines that perform hardware tree
    traversal.
               CM_Locate_DevNode
               CM_Get_Parent
               CM_Get_Child
               CM_Get_Sibling
               CM_Get_Device_ID_Size
               CM_Get_Device_ID
               CM_Enumerate_Enumerators
               CM_Get_Device_ID_List
               CM_Get_Device_ID_List_Size
               CM_Get_Depth

Author:

    Paula Tomlinson (paulat) 6-20-1995

Environment:

    User mode only.

Revision History:

    6-Jun-1995     paulat

        Creation and initial implementation.

--*/


//
// includes
//
#include "precomp.h"
#include "cfgi.h"
#include "setupapi.h"
#include "spapip.h"



CONFIGRET
CM_Locate_DevNode_ExW(
    OUT PDEVINST    pdnDevInst,
    IN  DEVINSTID_W pDeviceID,       OPTIONAL
    IN  ULONG       ulFlags,
    IN  HMACHINE    hMachine
    )

/*++

Routine Description:

   This routine retrieves the handle of the device instance that
   corresponds to a specified device identifier.

Parameters:

   pdnDevInst     Supplies the address of the variable that receives the
                  handle of a device instance.

   pDeviceID      Supplies the address of a null-terminated string specifying
                  a device identifier.  If this parameter is NULL, the API
                  retrieves a handle to the device instance at the root of
                  the hardware tree.

   ulFlags        Supplies flags specifying options for locating the device
                  instance.  May be a combination of the following values:

                  CM_LOCATE_DEVNODE_NORMAL  - Locate only device instances
                     that are currently alive from the ConfigMgr's point of
                     view.
                  CM_LOCATE_DEVNODE_PHANTOM - Allows a device instance handle
                     to be returned for a device instance that is not
                     currently alive, but that does exist in the registry.
                     This may be used with other CM APIs that require a
                     devnode handle, but for which there currently is none
                     for a particular device (e.g., you want to set a device
                     registry property for a device not currently present).
                     This flag does not allow you to locate phantom devnodes
                     created by using CM_Create_DevNode with the
                     CM_CREATE_DEVNODE_PHANTOM flag (such device instances
                     are only accessible by the caller who holds the devnode
                     handle returned from that API).

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_DEVICE_ID,
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_NO_SUCH_DEVNODE,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET Status = CR_SUCCESS;
    WCHAR     szFixedUpDeviceID[MAX_DEVICE_ID_LEN];
    PVOID     hStringTable = NULL;
    handle_t  hBinding = NULL;


    try {
        //
        // validate input parameters
        //
        if (!ARGUMENT_PRESENT(pdnDevInst)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, CM_LOCATE_DEVNODE_BITS)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *pdnDevInst = 0;

        //
        // setup rpc binding handle and string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }


        //------------------------------------------------------------------
        // if the device instance is NULL or it's a zero-length string, then
        // retreive the root device instance
        //------------------------------------------------------------------

        if ((!ARGUMENT_PRESENT(pDeviceID)) || (lstrlen(pDeviceID) == 0)) {

            RpcTryExcept {
                //
                // call rpc service entry point
                //
                Status = PNP_GetRootDeviceInstance(
                    hBinding,              // rpc binding handle
                    szFixedUpDeviceID,     // return device instance string
                    MAX_DEVICE_ID_LEN);    // length of DeviceInstanceID
            }
            RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
                KdPrintEx((DPFLTR_PNPMGR_ID,
                           DBGF_ERRORS,
                           "PNP_GetRootDeviceInstance caused an exception (%d)\n",
                           RpcExceptionCode()));

                Status = MapRpcExceptionToCR(RpcExceptionCode());
            }
            RpcEndExcept
        }

        //------------------------------------------------------------------
        // if the device instance was specified, validate the string
        //------------------------------------------------------------------

        else {
            //
            // first see if the format of the device id string is valid, this
            // can be done on the client side
            //
            if (!IsLegalDeviceId(pDeviceID)) {
                Status = CR_INVALID_DEVICE_ID;
                goto Clean0;
            }

            //
            // Next, fix up the device ID string for consistency (uppercase, etc)
            //
            CopyFixedUpDeviceId(szFixedUpDeviceID, pDeviceID,
                                lstrlen(pDeviceID));

            //
            // finally, validate the presense of the device ID string, this must
            // be done by the server
            //
            RpcTryExcept {
                //
                // call rpc service entry point
                //
                Status = PNP_ValidateDeviceInstance(
                    hBinding,               // rpc binding handle
                    szFixedUpDeviceID,      // device id
                    ulFlags);               // locate flag
            }
            RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
                KdPrintEx((DPFLTR_PNPMGR_ID,
                           DBGF_ERRORS,
                           "PNP_ValidateDeviceInstance caused an exception (%d)\n",
                           RpcExceptionCode()));

                Status = MapRpcExceptionToCR(RpcExceptionCode());
            }
            RpcEndExcept
        }

        if (Status != CR_SUCCESS) {
            goto Clean0;
        }


        //------------------------------------------------------------------
        // In either case, if we're successful then we have a valid device
        // ID. Use the string table to assign a unique DevNode to this
        // device id (if it's already in the string table, it just retrieves
        // the existing unique value)
        //------------------------------------------------------------------

        ASSERT(*szFixedUpDeviceID && IsLegalDeviceId(szFixedUpDeviceID));

        *pdnDevInst = pSetupStringTableAddString(hStringTable,
                                           szFixedUpDeviceID,
                                           STRTAB_CASE_SENSITIVE);
        if (*pdnDevInst == 0xFFFFFFFF) {
            Status = CR_FAILURE;    // probably out of memory
        }

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Locate_DevNode_ExW



CONFIGRET
CM_Get_Parent_Ex(
    OUT PDEVINST pdnDevInst,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the handle of the parent of a device instance.

Parameters:

   pdnDevInst     Supplies the address of the variable that receives a
                  handle to the parent device instance.

   dnDevInst      Supplies the handle of the child device instance string.

   ulFlags        Must be zero.

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_DEVNODE,
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_NO_SUCH_DEVNODE,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    WCHAR       szDeviceID[MAX_DEVICE_ID_LEN],
                pDeviceID [MAX_DEVICE_ID_LEN];
    ULONG       ulSize = MAX_DEVICE_ID_LEN;
    PVOID       hStringTable = NULL;
    handle_t    hBinding = NULL;
    BOOL        Success;


    try {
        //
        // validate input parameters
        //
        if (dnDevInst == 0) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        if (!ARGUMENT_PRESENT(pdnDevInst)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *pdnDevInst = 0;

        //
        // setup rpc binding handle and string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        //
        // retreive device instance string that corresponds to dnDevInst
        //
        Success = pSetupStringTableStringFromIdEx(hStringTable, dnDevInst,pDeviceID,&ulSize);
        if (Success == FALSE  ||  INVALID_DEVINST(pDeviceID)) {
            Status = CR_INVALID_DEVINST;     // "input" devinst doesn't exist
            goto Clean0;
        }

        ulSize = MAX_DEVICE_ID_LEN;

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_GetRelatedDeviceInstance(
                hBinding,               // rpc binding handle
                PNP_GET_PARENT_DEVICE_INSTANCE,    // requested action
                pDeviceID,              // base device instance
                szDeviceID,             // returns parent device instance
                &ulSize,
                ulFlags);               // not used
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_GetRelatedDeviceInstance caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

        if (Status != CR_SUCCESS) {
            goto Clean0;
        }

        //
        // add the returned device id to the string table so I can get a
        // devnode id for it (if it's already in the string table, the
        // existing id will be returned)
        //
        CharUpper(szDeviceID);

        ASSERT(*szDeviceID && IsLegalDeviceId(szDeviceID));

        *pdnDevInst = pSetupStringTableAddString(hStringTable,
                                           szDeviceID,
                                           STRTAB_CASE_SENSITIVE);
        if (*pdnDevInst == 0xFFFFFFFF) {
            Status = CR_FAILURE;    // probably out of memory
        }


    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Parent_Ex



CONFIGRET
CM_Get_Child_Ex(
    OUT PDEVINST pdnDevInst,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the first child of a given device instance.

Parameters:

   pdnDevInst     Supplies the address of the variable that receives the
                  handle of the device instance.

   dnDevInst      Supplies the handle of the parent device instance.

   ulFlags        Must be zero.

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_DEVNODE,
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_NO_SUCH_DEVNODE,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    WCHAR       szDeviceID[MAX_DEVICE_ID_LEN],
                pDeviceID [MAX_DEVICE_ID_LEN];
    ULONG       ulSize = MAX_DEVICE_ID_LEN;
    PVOID       hStringTable = NULL;
    handle_t    hBinding = NULL;
    BOOL        Success;


    try {
        //
        // validate input parameters
        //
        if (dnDevInst == 0) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        if (!ARGUMENT_PRESENT(pdnDevInst)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *pdnDevInst = 0;

        //
        // setup rpc binding handle and string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        //
        // retreive device instance string that corresponds to dnDevInst
        //
        Success = pSetupStringTableStringFromIdEx(hStringTable, dnDevInst,pDeviceID,&ulSize);
        if (Success == FALSE  ||  INVALID_DEVINST(pDeviceID)) {
            Status = CR_INVALID_DEVINST;     // "input" devinst doesn't exist
            goto Clean0;
        }

        ulSize = MAX_DEVICE_ID_LEN;

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_GetRelatedDeviceInstance(
                hBinding,               // rpc binding handle
                PNP_GET_CHILD_DEVICE_INSTANCE,    // requested action
                pDeviceID,              // base device instance
                szDeviceID,             // child device instance
                &ulSize,
                ulFlags);               // not used
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_GetRelatedDeviceInstance caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

        if (Status != CR_SUCCESS) {
            goto Clean0;
        }

        //
        // add the returned device id to the string table so I can get a
        // devnode id for it (if it's already in the string table, the
        // existing id will be returned)
        //
        CharUpper(szDeviceID);

        ASSERT(*szDeviceID && IsLegalDeviceId(szDeviceID));

        *pdnDevInst = pSetupStringTableAddString(hStringTable,
                                           szDeviceID,
                                           STRTAB_CASE_SENSITIVE);
        if (*pdnDevInst == 0xFFFFFFFF) {
            Status = CR_FAILURE;             // probably out of memory
        }

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Child_Ex



CONFIGRET
CM_Get_Sibling_Ex(
    OUT PDEVINST pdnDevInst,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the sibling of a device instance.

   This API can be called in a loop to retrieve all the siblings of a
   device instance.  When the API returns CR_NO_SUCH_DEVNODE, there are no
   more siblings to enumerate.  In order to enumerate all children of a
   device instance, this loop must start with the device instance retrieved
   by calling CM_Get_Child to get the first sibling.

Parameters:

   pdnDevInst     Supplies the address of the variable that receives a
                  handle to the sibling device  instance.

   dnDevInst      Supplies the handle of a device instance.

   ulFlags        Must be zero.

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_DEVNODE,
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_NO_SUCH_DEVNODE,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    WCHAR       szDeviceID[MAX_DEVICE_ID_LEN],
                pDeviceID [MAX_DEVICE_ID_LEN];
    ULONG       ulSize = MAX_DEVICE_ID_LEN;
    PVOID       hStringTable = NULL;
    handle_t    hBinding = NULL;
    BOOL        Success;


    try {
        //
        // validate input parameters
        //
        if (dnDevInst == 0) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        if (!ARGUMENT_PRESENT(pdnDevInst)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *pdnDevInst = 0;

        //
        // setup rpc binding handle and string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        //
        // retreive device instance string that corresponds to dnDevInst
        //
        Success = pSetupStringTableStringFromIdEx(hStringTable, dnDevInst,pDeviceID,&ulSize);
        if (Success == FALSE  ||  INVALID_DEVINST(pDeviceID)) {
            Status = CR_INVALID_DEVINST;     // "input" devinst doesn't exist
            goto Clean0;
        }

        ulSize = MAX_DEVICE_ID_LEN;

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_GetRelatedDeviceInstance(
                hBinding,               // rpc binding handle
                PNP_GET_SIBLING_DEVICE_INSTANCE,    // requested action
                pDeviceID,              // base device instance
                szDeviceID,             // sibling device instance
                &ulSize,
                ulFlags);               // not used
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_GetRelatedDeviceInstance caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

        if (Status != CR_SUCCESS) {
            goto Clean0;
        }

        //
        // add the returned device id to the string table so I can get a
        // devnode id for it (if it's already in the string table, the
        // existing id will be returned)
        //
        CharUpper(szDeviceID);

        ASSERT(*szDeviceID && IsLegalDeviceId(szDeviceID));

        *pdnDevInst = pSetupStringTableAddString(hStringTable,
                                           szDeviceID,
                                           STRTAB_CASE_SENSITIVE);
        if (*pdnDevInst == 0xFFFFFFFF) {
            Status = CR_FAILURE;                // probably out of memory
        }

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Sibling_Ex



CONFIGRET
CM_Get_Device_ID_Size_Ex(
    OUT PULONG   pulLen,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the size of a device identifier from a
   device instance.

Parameters:

   pulLen      Supplies the address of the variable that receives the size
               in characters, not including the terminating NULL, of the
               device identifier.  The API sets the variable to 0 if no
               identifier exists.  The size is always less than or equal to
               MAX_DEVICE_ID_LEN.

   dnDevInst   Supplies the handle of the device instance.

   ulFlags     Must be zero.

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return Value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_DEVNODE,
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.
--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    WCHAR       pDeviceID [MAX_DEVICE_ID_LEN];
    PVOID       hStringTable = NULL;
    BOOL        Success;
    DWORD       ulLen;


    try {
        //
        // validate parameters
        //
        if (dnDevInst == 0) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        if (!ARGUMENT_PRESENT(pulLen)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // setup string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, NULL)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        //
        // retrieve the string form of the device id string
        // use private ulLen, since we know this is valid
        //
        ulLen = MAX_DEVICE_ID_LEN;
        Success = pSetupStringTableStringFromIdEx(hStringTable, dnDevInst,pDeviceID,&ulLen);
        if (Success == FALSE  ||  INVALID_DEVINST(pDeviceID)) {
            *pulLen = 0;
            Status = CR_INVALID_DEVINST;
        }
        //
        // discount the terminating NULL char,
        // included in the size reported by pSetupStringTableStringFromIdEx
        //
        *pulLen = ulLen - 1;

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Device_ID_Size_Ex



CONFIGRET
CM_Get_Device_ID_ExW(
    IN  DEVINST  dnDevInst,
    OUT PWCHAR   Buffer,
    IN  ULONG    BufferLen,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the device identifier for a device instance.

Parameters:

   dnDevNode   Supplies the handle of the device instance for which to
               retrieve the device identifier.

   Buffer      Supplies the address of the buffer that receives the device
               identifier.  If this buffer is larger than the device
               identifier, the API appends a null-terminating character to
               the data.  If it is smaller than the device identifier, the API
               fills it with as much of the device identifier as will fit
               and returns CR_BUFFER_SMALL.

   BufferLen   Supplies the size, in characters, of the buffer for the device
               identifier.

   ulFlags     Must be zero.

   hMachine    Machine handle returned from CM_Connect_Machine or NULL.

Return Value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_BUFFER_SMALL,
      CR_INVALID_DEVNODE,
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    WCHAR       pDeviceID [MAX_DEVICE_ID_LEN];
    ULONG       ulLength = MAX_DEVICE_ID_LEN;
    PVOID       hStringTable = NULL;
    BOOL        Success;


    try {
        //
        // validate parameters
        //
        if (dnDevInst == 0) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        if (!ARGUMENT_PRESENT(Buffer)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // setup string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, NULL)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        //
        // retrieve the string form of the device id string
        //
        Success = pSetupStringTableStringFromIdEx(hStringTable, dnDevInst,pDeviceID,&ulLength);
        if (Success == FALSE || INVALID_DEVINST(pDeviceID)) {
            *Buffer = '\0';
            Status = CR_INVALID_DEVNODE;
            goto Clean0;
        }

        //
        // copy as much of the the device id string as possible to the user
        // buffer.  the length reported by pSetupStringTableStringFromIdEx accounts
        // for the NULL term char; include it as well, if there is room.
        //
        memcpy(Buffer,
               pDeviceID,
               min(ulLength * sizeof(WCHAR), BufferLen * sizeof(WCHAR)));

        //
        // if the length of device id string (without NULL termination) is
        // longer than the supplied buffer, report CR_BUFFER_SMALL.
        //
        if ((ulLength - 1) > BufferLen) {
            Status = CR_BUFFER_SMALL;
        }

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Device_ID_ExW



CONFIGRET
CM_Enumerate_Enumerators_ExW(
    IN ULONG      ulEnumIndex,
    OUT PWCHAR    Buffer,
    IN OUT PULONG pulLength,
    IN ULONG      ulFlags,
    IN HMACHINE   hMachine
    )

/*++

Routine Description:

   This routine enumerates the enumerator subkeys under the Enum branch
   (e.g., Root, PCI, etc.).  These names should not be used to access the
   registry directly, but may be used as input to the CM_Get_Device_ID_List
   routine.  To enumerate enumerator subkey names, an application should
   initially call the CM_Enumerate_Enumerators function with the ulEnumIndex
   parameter set to zero. The application should then increment the
   ulEnumIndex parameter and call CM_Enumerate_Enumerators until there are
   no more subkeys (until the function returns CR_NO_SUCH_VALUE).

Parameters:

   ulEnumIndex Supplies the index of the enumerator subkey name to retrieve.

   Buffer      Supplies the address of the character buffer that receives
               the enumerator subkey name whose index is specified by
               ulEnumIndex.

   pulLength   Supplies the address of the variable that contains the length,
               in characters, of the Buffer.  Upon return, this variable
               will contain the number of characters (including terminating
               NULL) written to Buffer (if the supplied buffer is't large
               enough, then the routine will fail with CR_BUFFER_SMALL, and
               this value will indicate how large the buffer needs to be in
               order to succeed).

   ulFlags     Must be zero.

   hMachine    Machine handle returned from CM_Connect_Machine or NULL.

Return Value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_BUFFER_SMALL,
      CR_NO_SUCH_VALUE,
      CR_REGISTRY_ERROR,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    handle_t    hBinding = NULL;


    try {
        //
        // validate input parameters
        //
        if ((!ARGUMENT_PRESENT(Buffer)) ||
            (!ARGUMENT_PRESENT(pulLength))) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *Buffer = L'\0';

        //
        // setup rpc binding handle
        //
        if (!PnPGetGlobalHandles(hMachine, NULL, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_EnumerateSubKeys(
                hBinding,               // rpc binding handle
                PNP_ENUMERATOR_SUBKEYS, // subkeys of enum branch
                ulEnumIndex,            // index of enumerator to enumerate
                Buffer,                 // will contain enumerator name
                *pulLength,             // max length of Buffer in chars
                pulLength,              // chars copied (or chars required)
                ulFlags);               // currently unused
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_EnumerateSubKeys caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Enumerate_Enumerators_ExW



CONFIGRET
CM_Get_Device_ID_List_ExW(
    IN PCWSTR   pszFilter,    OPTIONAL
    OUT PWCHAR  Buffer,
    IN ULONG    BufferLen,
    IN ULONG    ulFlags,
    IN HMACHINE hMachine
    )

/*++

Routine Description:
   This routine retrieve a list of all device IDs (device instance names)
   stored in the system.

Parameters:

   pszFilter      This string filters the list of device IDs returned.  Its
                  interpretation is dependent on the ulFlags specified.   If
                  CM_GETDEVID_FILTER_ENUMERATORS is specified, then this
                  value can be either the name of an enumerator or the name
                  of an enumerator plus the device id.  If
                  CM_GETDEVID_FILTER_SERVICE is specified, then this value
                  is a service name.

   Buffer         Supplies the address of the character buffer that receives
                  the device ID list.  Each device ID is null-terminated, with
                  an extra NULL at the end.

   BufferLen      Supplies the size, in characters, of the Buffer.  This size
                  may be ascertained by calling CM_Get_Device_ID_List_Size.

   ulFlags        Must be either CM_GETDEVID_FILTER_ENUMERATOR or
                  CM_GETDEVID_FILTER_SERVICE.  The flags value controls how
                  the pszFilter string is used.

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return Value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_BUFFER_SMALL,
      CR_REGISTRY_ERROR,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    handle_t    hBinding = NULL;


    try {
        //
        // validate input parameters
        //
        if ((!ARGUMENT_PRESENT(Buffer)) || (BufferLen == 0)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, CM_GETIDLIST_FILTER_BITS)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *Buffer = L'\0';

        //
        // setup rpc binding handle
        //
        if (!PnPGetGlobalHandles(hMachine, NULL, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_GetDeviceList(
                hBinding,            // RPC Binding Handle
                pszFilter,           // filter string, optional
                Buffer,              // will contain device list
                &BufferLen,          // in/out size of Buffer
                ulFlags);            // filter flag
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_GetDeviceList caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Device_ID_List_ExW



CONFIGRET
CM_Get_Device_ID_List_Size_ExW(
    OUT PULONG  pulLen,
    IN PCWSTR   pszFilter,   OPTIONAL
    IN ULONG    ulFlags,
    IN HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the size, in characters, of a list of device
   identifiers.  It may be used to supply the buffer size necessary for a
   call to CM_Get_Device_ID_List.

Parameters:

   pulLen         Supplies the address of the variable that receives the
                  size, in characters, required to store a list of all device
                  identifiers (possibly limited to those existing under the
                  pszEnumerator subkey described below).  The size reflects
                  a list of null-terminated device identifiers, with an extra
                  null at the end.  For efficiency, this number represents an
                  upper bound on the size required, and the actual list size
                  may be slightly smaller.

   pszFilter      This string filters the list of device IDs returned.  Its
                  interpretation is dependent on the ulFlags specified.   If
                  CM_GETDEVID_FILTER_ENUMERATORS is specified, then this
                  value can be either the name of an enumerator or the name
                  of an enumerator plus the device id.  If
                  CM_GETDEVID_FILTER_SERVICE is specified, then this value
                  is a service name.

   ulFlags        Must be either CM_GETDEVID_FILTER_ENUMERATOR or
                  CM_GETDEVID_FILTER_SERVICE.  The flags value controls how
                  the pszFilter string is used.

   hMachine       Machine handle returned from CM_Connect_Machine or NULL.

Return Value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_FLAG,
      CR_INVALID_POINTER,
      CR_REGISTRY_ERROR,
      CR_REMOTE_COMM_FAILURE,
      CR_MACHINE_UNAVAILABLE,
      CR_FAILURE.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    handle_t    hBinding = NULL;


    try {
        //
        // validate input parameters
        //
        if (!ARGUMENT_PRESENT(pulLen)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, CM_GETIDLIST_FILTER_BITS)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // initialize output parameters
        //
        *pulLen = 0;

        //
        // setup rpc binding handle
        //
        if (!PnPGetGlobalHandles(hMachine, NULL, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_GetDeviceListSize(
                hBinding,       // rpc binding handle
                pszFilter,      // Enumerator subkey, optional
                pulLen,         // length of device list in chars
                ulFlags);       // filter flag
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_GetDeviceListSize caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Device_ID_List_SizeW



CONFIGRET
CM_Get_Depth_Ex(
    OUT PULONG   pulDepth,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )

/*++

Routine Description:

   This routine retrieves the depth of a device instance in the
   hardware tree.

Parameters:

   pulDepth    Supplies the address of the variable that receives the
               depth of the device instance.  This value is 0 to designate
               the root of the tree, 1 to designate a child of the root,
               and so on.

   dnDevNode   Supplies the handle of a device instance.

   ulFlags     Must be zero.

Return Value:

   If the function succeeds, the return value is CR_SUCCESS.
   If the function fails, the return value is one of the following:
      CR_INVALID_DEVNODE,
      CR_INVALID_FLAG, or
      CR_INVALID_POINTER.

--*/

{
    CONFIGRET   Status = CR_SUCCESS;
    WCHAR       pDeviceID [MAX_DEVICE_ID_LEN];
    PVOID       hStringTable = NULL;
    handle_t    hBinding = NULL;
    ULONG       ulLen = MAX_DEVICE_ID_LEN;
    BOOL        Success;

    try {
        //
        // validate parameters
        //
        if (dnDevInst == 0) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        if (!ARGUMENT_PRESENT(pulDepth)) {
            Status = CR_INVALID_POINTER;
            goto Clean0;
        }

        if (INVALID_FLAGS(ulFlags, 0)) {
            Status = CR_INVALID_FLAG;
            goto Clean0;
        }

        //
        // setup rpc binding handle and string table handle
        //
        if (!PnPGetGlobalHandles(hMachine, &hStringTable, &hBinding)) {
            Status = CR_FAILURE;
            goto Clean0;
        }

        //
        // retrieve the device instance ID string associated with the devinst
        //
        Success = pSetupStringTableStringFromIdEx(hStringTable, dnDevInst,pDeviceID,&ulLen);
        if (Success == FALSE || INVALID_DEVINST(pDeviceID)) {
            Status = CR_INVALID_DEVINST;
            goto Clean0;
        }

        RpcTryExcept {
            //
            // call rpc service entry point
            //
            Status = PNP_GetDepth(
                hBinding,     // rpc binding handle
                pDeviceID,    // device instance
                pulDepth,     // returns the depth
                ulFlags);     // not used
        }
        RpcExcept (I_RpcExceptionFilter(RpcExceptionCode())) {
            KdPrintEx((DPFLTR_PNPMGR_ID,
                       DBGF_ERRORS,
                       "PNP_GetDepth caused an exception (%d)\n",
                       RpcExceptionCode()));

            Status = MapRpcExceptionToCR(RpcExceptionCode());
        }
        RpcEndExcept

    Clean0:
        NOTHING;

    } except(EXCEPTION_EXECUTE_HANDLER) {
        Status = CR_FAILURE;
    }

    return Status;

} // CM_Get_Depth



//-------------------------------------------------------------------
// Local Stubs
//-------------------------------------------------------------------


CONFIGRET
CM_Locate_DevNodeW(
    OUT PDEVINST    pdnDevInst,
    IN  DEVINSTID_W pDeviceID,       OPTIONAL
    IN  ULONG       ulFlags
    )
{
    return CM_Locate_DevNode_ExW(pdnDevInst, pDeviceID, ulFlags, NULL);
}


CONFIGRET
CM_Locate_DevNodeA(
    OUT PDEVINST    pdnDevInst,
    IN  DEVINSTID_A pDeviceID,       OPTIONAL
    IN  ULONG       ulFlags
    )
{
    return CM_Locate_DevNode_ExA(pdnDevInst, pDeviceID, ulFlags, NULL);
}


CONFIGRET
CM_Get_Parent(
    OUT PDEVINST pdnDevInst,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags
    )
{
    return CM_Get_Parent_Ex(pdnDevInst, dnDevInst, ulFlags, NULL);
}


CONFIGRET
CM_Get_Child(
    OUT PDEVINST pdnDevInst,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags
    )
{
    return CM_Get_Child_Ex(pdnDevInst, dnDevInst, ulFlags, NULL);
}


CONFIGRET
CM_Get_Sibling(
    OUT PDEVINST pdnDevInst,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags
    )
{
    return CM_Get_Sibling_Ex(pdnDevInst, dnDevInst, ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_ID_Size(
    OUT PULONG  pulLen,
    IN  DEVINST dnDevInst,
    IN  ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_Size_Ex(pulLen, dnDevInst, ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_IDW(
    IN  DEVINST dnDevInst,
    OUT PWCHAR  Buffer,
    IN  ULONG   BufferLen,
    IN  ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_ExW(dnDevInst, Buffer, BufferLen, ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_IDA(
    IN  DEVINST dnDevInst,
    OUT PCHAR   Buffer,
    IN  ULONG   BufferLen,
    IN  ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_ExA(dnDevInst, Buffer, BufferLen, ulFlags, NULL);
}


CONFIGRET
CM_Enumerate_EnumeratorsW(
    IN ULONG      ulEnumIndex,
    OUT PWCHAR    Buffer,
    IN OUT PULONG pulLength,
    IN ULONG      ulFlags
    )
{
    return CM_Enumerate_Enumerators_ExW(ulEnumIndex, Buffer, pulLength,
                                        ulFlags, NULL);
}


CONFIGRET
CM_Enumerate_EnumeratorsA(
    IN ULONG      ulEnumIndex,
    OUT PCHAR     Buffer,
    IN OUT PULONG pulLength,
    IN ULONG      ulFlags
    )
{
    return CM_Enumerate_Enumerators_ExA(ulEnumIndex, Buffer, pulLength,
                                        ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_ID_ListW(
    IN PCWSTR  pszFilter,    OPTIONAL
    OUT PWCHAR Buffer,
    IN ULONG   BufferLen,
    IN ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_List_ExW(pszFilter, Buffer, BufferLen,
                                     ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_ID_ListA(
    IN PCSTR   pszFilter,    OPTIONAL
    OUT PCHAR  Buffer,
    IN ULONG   BufferLen,
    IN ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_List_ExA(pszFilter, Buffer, BufferLen,
                                     ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_ID_List_SizeW(
    OUT PULONG pulLen,
    IN PCWSTR  pszFilter,   OPTIONAL
    IN ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_List_Size_ExW(pulLen, pszFilter, ulFlags, NULL);
}


CONFIGRET
CM_Get_Device_ID_List_SizeA(
    OUT PULONG pulLen,
    IN PCSTR   pszFilter,   OPTIONAL
    IN ULONG   ulFlags
    )
{
    return CM_Get_Device_ID_List_Size_ExA(pulLen, pszFilter, ulFlags, NULL);
}


CONFIGRET
CM_Get_Depth(
    OUT PULONG   pulDepth,
    IN  DEVINST  dnDevInst,
    IN  ULONG    ulFlags
    )
{
    return CM_Get_Depth_Ex(pulDepth, dnDevInst, ulFlags, NULL);
}



//-------------------------------------------------------------------
// ANSI STUBS
//-------------------------------------------------------------------


CONFIGRET
CM_Locate_DevNode_ExA(
    OUT PDEVINST    pdnDevInst,
    IN  DEVINSTID_A pDeviceID,    OPTIONAL
    IN  ULONG       ulFlags,
    IN  HMACHINE    hMachine
    )
{
    CONFIGRET Status = CR_SUCCESS;


    if (!ARGUMENT_PRESENT(pDeviceID)) {
        //
        // If the DEVINSTID parameter is NULL, then no conversion is necessary,
        // just call the wide version
        //
        Status = CM_Locate_DevNode_ExW(pdnDevInst,
                                       NULL,
                                       ulFlags,
                                       hMachine);
    } else {
        //
        // if a device id string was passed in, convert to UNICODE before
        // passing on to the wide version
        //
        PWSTR pUniDeviceID = NULL;

        if (pSetupCaptureAndConvertAnsiArg(pDeviceID, &pUniDeviceID) == NO_ERROR) {

            Status = CM_Locate_DevNode_ExW(pdnDevInst,
                                           pUniDeviceID,
                                           ulFlags,
                                           hMachine);

            pSetupFree(pUniDeviceID);

        } else {
            Status = CR_INVALID_DEVICE_ID;
        }
    }

    return Status;

} // CM_Locate_DevNode_ExA



CONFIGRET
CM_Get_Device_ID_ExA(
    IN  DEVINST  dnDevInst,
    OUT PCHAR    Buffer,
    IN  ULONG    BufferLen,
    IN  ULONG    ulFlags,
    IN  HMACHINE hMachine
    )
{
    CONFIGRET Status = CR_SUCCESS;
    WCHAR     UniBuffer[MAX_DEVICE_ID_LEN];
    ULONG     ulAnsiBufferLen;

    //
    // validate essential parameters only
    //
    if ((!ARGUMENT_PRESENT(Buffer)) || (BufferLen == 0)) {
        return CR_INVALID_POINTER;
    }

    //
    // call the wide version, passing a unicode buffer as a parameter
    //
    Status = CM_Get_Device_ID_ExW(dnDevInst,
                                  UniBuffer,
                                  MAX_DEVICE_ID_LEN,
                                  ulFlags,
                                  hMachine);

    //
    // We should never return a DeviceId longer than MAX_DEVICE_ID_LEN.
    //
    ASSERT(Status != CR_BUFFER_SMALL);

    if (Status == CR_SUCCESS) {
        //
        // if the call succeeded, convert the device id to ansi before returning
        //
        ulAnsiBufferLen = BufferLen;
        Status = PnPUnicodeToMultiByte(UniBuffer,
                                       (lstrlenW(UniBuffer)+1)*sizeof(WCHAR),
                                       Buffer,
                                       &ulAnsiBufferLen);
    }

    return Status;

} // CM_Get_Device_ID_ExA




CONFIGRET
CM_Enumerate_Enumerators_ExA(
    IN ULONG      ulEnumIndex,
    OUT PCHAR     Buffer,
    IN OUT PULONG pulLength,
    IN ULONG      ulFlags,
    IN HMACHINE   hMachine
    )
{
    CONFIGRET Status = CR_SUCCESS;
    WCHAR     UniBuffer[MAX_DEVICE_ID_LEN];
    ULONG     UniLen = MAX_DEVICE_ID_LEN;

    //
    // validate parameters
    //
    if ((!ARGUMENT_PRESENT(Buffer)) ||
        (!ARGUMENT_PRESENT(pulLength))) {
        return CR_INVALID_POINTER;
    }

    //
    // call the wide version, passing a unicode buffer as a parameter
    //
    Status = CM_Enumerate_Enumerators_ExW(ulEnumIndex,
                                          UniBuffer,
                                          &UniLen,
                                          ulFlags,
                                          hMachine);

    ASSERT(Status != CR_BUFFER_SMALL);

    if (Status == CR_SUCCESS) {
        //
        // convert the unicode buffer to an ansi string and copy to the caller's
        // buffer
        //
        Status = PnPUnicodeToMultiByte(UniBuffer,
                                       (lstrlenW(UniBuffer)+1)*sizeof(WCHAR),
                                       Buffer,
                                       pulLength);
    }

    return Status;

} // CM_Enumerate_Enumerators_ExA



CONFIGRET
CM_Get_Device_ID_List_ExA(
      IN PCSTR    pszFilter,    OPTIONAL
      OUT PCHAR   Buffer,
      IN ULONG    BufferLen,
      IN ULONG    ulFlags,
      IN HMACHINE hMachine
      )
{
    CONFIGRET Status = CR_SUCCESS;
    PWSTR     pUniBuffer, pUniFilter = NULL;
    ULONG     ulAnsiBufferLen;

    //
    // validate input parameters
    //
    if ((!ARGUMENT_PRESENT(Buffer)) || (BufferLen == 0)) {
        return CR_INVALID_POINTER;
    }

    if (ARGUMENT_PRESENT(pszFilter)) {
        //
        // if a filter string was passed in, convert to UNICODE before
        // passing on to the wide version
        //
        if (pSetupCaptureAndConvertAnsiArg(pszFilter, &pUniFilter) != NO_ERROR) {
            return CR_INVALID_DATA;
        }
        ASSERT(pUniFilter != NULL);
    } else {
        ASSERT(pUniFilter == NULL);
    }

    //
    // prepare a larger buffer to hold the unicode formatted
    // multi_sz data returned by CM_Get_Device_ID_List.
    //
    pUniBuffer = pSetupMalloc(BufferLen*sizeof(WCHAR));
    if (pUniBuffer == NULL) {
        Status = CR_OUT_OF_MEMORY;
        goto Clean0;
    }

    *pUniBuffer = L'\0';

    //
    // call the wide version
    //
    Status = CM_Get_Device_ID_List_ExW(pUniFilter,
                                       pUniBuffer,
                                       BufferLen,   // size in chars
                                       ulFlags,
                                       hMachine);
    if (Status == CR_SUCCESS) {
        //
        // if the call succeeded, must convert the multi_sz list to ansi before
        // returning
        //
        ulAnsiBufferLen = BufferLen;
        Status = PnPUnicodeToMultiByte(pUniBuffer,
                                       BufferLen*sizeof(WCHAR),
                                       Buffer,
                                       &ulAnsiBufferLen);
    }

    pSetupFree(pUniBuffer);

 Clean0:

    if (pUniFilter) {
        pSetupFree(pUniFilter);
    }

    return Status;

} // CM_Get_Device_ID_List_ExA



CONFIGRET
CM_Get_Device_ID_List_Size_ExA(
    OUT PULONG  pulLen,
    IN PCSTR    pszFilter,   OPTIONAL
    IN ULONG    ulFlags,
    IN HMACHINE hMachine
    )
{
    CONFIGRET Status = CR_SUCCESS;
    ULONG     UniLen = MAX_DEVICE_ID_LEN;


    if (!ARGUMENT_PRESENT(pszFilter)) {
        //
        // If the filter parameter is NULL, then no conversion is necessary,
        // just call the wide version
        //
        Status = CM_Get_Device_ID_List_Size_ExW(pulLen,
                                                NULL,
                                                ulFlags,
                                                hMachine);
    } else {
        //
        // if a filter string was passed in, convert to UNICODE before
        // passing on to the wide version
        //
        PWSTR pUniFilter = NULL;

        if (pSetupCaptureAndConvertAnsiArg(pszFilter, &pUniFilter) == NO_ERROR) {

            Status = CM_Get_Device_ID_List_Size_ExW(pulLen,
                                                    pUniFilter,
                                                    ulFlags,
                                                    hMachine);
            pSetupFree(pUniFilter);

        } else {
            Status = CR_INVALID_DATA;
        }
    }

    return Status;

} // CM_Get_Device_ID_List_Size_ExA