archive
/
windows-server-2003
mirror of https://github.com/selfrender/Windows-Server-2003
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Leaked source code of windows server 2003
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
4 Commits
1 Branch
0 Tags
1.5 GiB
 
 
 
 
 
 
Branch: master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
windows-server-2003/base/pnp/setupapi/devinfo.c

5939 lines
211 KiB
Raw Permalink Blame History

/*++
Copyright (c) Microsoft Corporation. All rights reserved.
Module Name:
devinfo.c
Abstract:
Device Installer routines dealing with device information sets
Author:
Lonny McMichael (lonnym) 10-May-1995
Revision History:
Jamie Hunter (JamieHun) July-19-2002
Reviewed "unsafe" functions
--*/
#include "precomp.h"
#pragma hdrstop
//
// Define the context structure used by the default device comparison
// callback (used by SetupDiRegisterDeviceInfo).
//
typedef struct _DEFAULT_DEVCMP_CONTEXT {
PCS_RESOURCE NewDevCsResource;
PCS_RESOURCE CurDevCsResource;
ULONG CsResourceSize; // applies to both buffers.
} DEFAULT_DEVCMP_CONTEXT, *PDEFAULT_DEVCMP_CONTEXT;
//
// Private routine prototypes.
//
DWORD
pSetupOpenAndAddNewDevInfoElem(
IN PDEVICE_INFO_SET DeviceInfoSet,
IN PCTSTR DeviceInstanceId,
IN BOOL AllowPhantom,
IN CONST GUID *ClassGuid, OPTIONAL
IN HWND hwndParent, OPTIONAL
OUT PDEVINFO_ELEM *DevInfoElem,
IN BOOL CheckIfAlreadyThere,
OUT PBOOL AlreadyPresent, OPTIONAL
IN BOOL OpenExistingOnly,
IN ULONG CmLocateFlags,
IN PDEVICE_INFO_SET ContainingDeviceInfoSet
);
DWORD
pSetupAddNewDeviceInfoElement(
IN PDEVICE_INFO_SET DeviceInfoSet,
IN DEVINST DevInst,
IN CONST GUID *ClassGuid,
IN PCTSTR Description, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD DiElemFlags,
IN PDEVICE_INFO_SET ContainingDeviceInfoSet,
OUT PDEVINFO_ELEM *DeviceInfoElement
);
DWORD
pSetupClassGuidFromDevInst(
IN DEVINST DevInst,
IN HMACHINE hMachine,
OUT LPGUID ClassGuid
);
DWORD
pSetupDupDevCompare(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA NewDeviceData,
IN PSP_DEVINFO_DATA ExistingDeviceData,
IN PVOID CompareContext
);
DWORD
pSetupAddDeviceInterfaceToDevInfoElem(
IN PDEVICE_INFO_SET DeviceInfoSet,
IN PDEVINFO_ELEM DevInfoElem,
IN CONST GUID *ClassGuid,
IN PTSTR DeviceInterfaceName,
IN BOOL IsActive,
IN BOOL IsDefault,
IN BOOL StoreTruncateNode,
IN BOOL OpenExistingOnly,
OUT PDEVICE_INTERFACE_NODE *DeviceInterfaceNode OPTIONAL
);
DWORD
_SetupDiOpenDeviceInterface(
IN HDEVINFO DeviceInfoSet,
IN PTSTR DevicePath,
IN DWORD OpenFlags,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData OPTIONAL
);
DWORD
pSetupGetDevInstNameAndStatusForDeviceInterface(
IN HKEY hKeyInterfaceClass,
IN PCTSTR DeviceInterfaceName,
OUT PTSTR OwningDevInstName, OPTIONAL
IN DWORD OwningDevInstNameSize,
OUT PBOOL IsActive, OPTIONAL
OUT PBOOL IsDefault OPTIONAL
);
BOOL
pSetupDiGetOrSetDeviceInfoContext(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
IN DWORD InContext,
OUT PDWORD OutContext OPTIONAL
);
HDEVINFO
WINAPI
SetupDiCreateDeviceInfoList(
IN CONST GUID *ClassGuid, OPTIONAL
IN HWND hwndParent OPTIONAL
)
/*++
Routine Description:
This API creates an empty device information set that will contain device
device information member elements. This set may be associated with an
optionally-specified class GUID.
Arguments:
ClassGuid - Optionally, supplies a pointer to the class GUID that is to be
associated with this set.
hwndParent - Optionally, supplies the window handle of the top-level window
to use for any UI related to installation of a class driver contained
in this set's global class driver list (if it has one).
Return Value:
If the function succeeds, the return value is a handle to an empty device
information set.
If the function fails, the return value is INVALID_HANDLE_VALUE. To get
extended error information, call GetLastError.
--*/
{
return SetupDiCreateDeviceInfoListEx(ClassGuid, hwndParent, NULL, NULL);
}
//
// ANSI version
//
HDEVINFO
WINAPI
SetupDiCreateDeviceInfoListExA(
IN CONST GUID *ClassGuid, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN PCSTR MachineName, OPTIONAL
IN PVOID Reserved
)
{
PCWSTR UnicodeMachineName;
DWORD rc;
HDEVINFO hDevInfo;
hDevInfo = INVALID_HANDLE_VALUE;
if(MachineName) {
rc = pSetupCaptureAndConvertAnsiArg(MachineName, &UnicodeMachineName);
} else {
UnicodeMachineName = NULL;
rc = NO_ERROR;
}
if(rc == NO_ERROR) {
hDevInfo = SetupDiCreateDeviceInfoListExW(ClassGuid,
hwndParent,
UnicodeMachineName,
Reserved
);
rc = GetLastError();
if(UnicodeMachineName) {
MyFree(UnicodeMachineName);
}
}
SetLastError(rc);
return hDevInfo;
}
HDEVINFO
WINAPI
SetupDiCreateDeviceInfoListEx(
IN CONST GUID *ClassGuid, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN PCTSTR MachineName, OPTIONAL
IN PVOID Reserved
)
/*++
Routine Description:
This API creates an empty device information set that will contain device
device information member elements. This set may be associated with an
optionally-specified class GUID.
Arguments:
ClassGuid - Optionally, supplies a pointer to the class GUID that is to be
associated with this set.
hwndParent - Optionally, supplies the window handle of the top-level window
to use for any UI related to installation of a class driver contained
in this set's global class driver list (if it has one).
MachineName - Optionally, supplies the name of the machine for which this
device information set is to be related. Only devices on that machine
may be opened/created. If this parameter is NULL, then the local machine
is used.
Reserved - Reserved for future use--must be NULL.
Return Value:
If the function succeeds, the return value is a handle to an empty device
information set.
If the function fails, the return value is INVALID_HANDLE_VALUE. To get
extended error information, call GetLastError.
--*/
{
PDEVICE_INFO_SET DeviceInfoSet;
DWORD Err = NO_ERROR;
CONFIGRET cr;
//
// Make sure the user didn't pass us anything in the Reserved parameter.
//
if(Reserved) {
SetLastError(ERROR_INVALID_PARAMETER);
return INVALID_HANDLE_VALUE;
}
if(DeviceInfoSet = AllocateDeviceInfoSet()) {
try {
//
// If the user specified the name of a remote machine, connect to
// that machine now.
//
if(MachineName) {
if(CR_SUCCESS != (cr = CM_Connect_Machine(MachineName, &(DeviceInfoSet->hMachine)))) {
//
// Make sure hMachine is still NULL, so we won't try to disconnect later.
//
DeviceInfoSet->hMachine = NULL;
Err = MapCrToSpError(cr, ERROR_INVALID_DATA);
goto clean0;
}
//
// Store the machine name in the string table, so it can be
// retrieved later via SetupDiGetDeviceInfoListDetail.
//
if(-1 == (DeviceInfoSet->MachineName = pStringTableAddString(DeviceInfoSet->StringTable,
(PTSTR)MachineName,
STRTAB_CASE_SENSITIVE,
NULL,
0))) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
}
if(ClassGuid) {
//
// If a class GUID was specified, then store it away in
// the device information set.
//
CopyMemory(&(DeviceInfoSet->ClassGuid),
ClassGuid,
sizeof(GUID)
);
DeviceInfoSet->HasClassGuid = TRUE;
}
DeviceInfoSet->InstallParamBlock.hwndParent = hwndParent;
clean0: ; // nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Reference the following variable so the compiler will respect statement ordering
// w.r.t. assignment.
//
DeviceInfoSet->hMachine = DeviceInfoSet->hMachine;
}
if(Err != NO_ERROR) {
DestroyDeviceInfoSet(NULL, DeviceInfoSet);
}
} else {
Err = ERROR_NOT_ENOUGH_MEMORY;
}
SetLastError(Err);
return (Err == NO_ERROR) ? (HDEVINFO)DeviceInfoSet
: (HDEVINFO)INVALID_HANDLE_VALUE;
}
BOOL
WINAPI
SetupDiGetDeviceInfoListClass(
IN HDEVINFO DeviceInfoSet,
OUT LPGUID ClassGuid
)
/*++
Routine Description:
This API retrieves the class GUID associated with a device information
set (if it has an associated class).
Arguments:
DeviceInfoSet - Supplies a handle to a device information set whose associated
class is being queried.
ClassGuid - Supplies a pointer to a variable that receives the GUID for the
associated class.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError. If the set has no associated class, then
GetLastError will return ERROR_NO_ASSOCIATED_CLASS.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
if(pDeviceInfoSet->HasClassGuid) {
//
// Copy the GUID to the user-supplied buffer.
//
CopyMemory(ClassGuid,
&(pDeviceInfoSet->ClassGuid),
sizeof(GUID)
);
} else {
Err = ERROR_NO_ASSOCIATED_CLASS;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return (Err == NO_ERROR);
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiGetDeviceInfoListDetailA(
IN HDEVINFO DeviceInfoSet,
OUT PSP_DEVINFO_LIST_DETAIL_DATA_A DeviceInfoSetDetailData
)
{
DWORD rc;
BOOL b;
SP_DEVINFO_LIST_DETAIL_DATA_W UnicodeDevInfoSetDetails;
UnicodeDevInfoSetDetails.cbSize = sizeof(SP_DEVINFO_LIST_DETAIL_DATA_W);
b = SetupDiGetDeviceInfoListDetailW(DeviceInfoSet, &UnicodeDevInfoSetDetails);
rc = GetLastError();
if(b) {
rc = pSetupDiDevInfoSetDetailDataUnicodeToAnsi(&UnicodeDevInfoSetDetails, DeviceInfoSetDetailData);
if(rc != NO_ERROR) {
b = FALSE;
}
}
SetLastError(rc);
return(b);
}
BOOL
WINAPI
SetupDiGetDeviceInfoListDetail(
IN HDEVINFO DeviceInfoSet,
OUT PSP_DEVINFO_LIST_DETAIL_DATA DeviceInfoSetDetailData
)
/*++
Routine Description:
This routine retrieves information about the specified device information set,
such as its associated class (if any), and the remote machine it was opened for
(if this is a remoted HDEVINFO). This API supercedes SetupDiGetDeviceInfoListClass.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set to retrieve
detailed information for.
DeviceInfoSetDetailData - Supplies the address of a structure that receives
information about the specified device information set. This structure is
defined as follows:
typedef struct _SP_DEVINFO_LIST_DETAIL_DATA {
DWORD cbSize;
GUID ClassGuid;
HANDLE RemoteMachineHandle;
TCHAR RemoteMachineName[SP_MAX_MACHINENAME_LENGTH];
} SP_DEVINFO_LIST_DETAIL_DATA, *PSP_DEVINFO_LIST_DETAIL_DATA;
where:
ClassGuid specifies the class associated with the device information
set, or GUID_NULL if there is no associated class.
RemoteMachineHandle is the ConfigMgr32 machine handle used to access
the remote machine, if this is a remoted HDEVINFO (i.e., a
MachineName was specified when the set was created via
SetupDiCreateDeviceInfoListEx or SetupDiGetClassDevsEx). All
DevInst handles stored in SP_DEVINFO_DATA structures for elements
of this set are relative to this handle, and must be used in
combination with this handle when calling any CM_*_Ex APIs.
If this is not a device information set for a remote machine, this
field will be NULL.
NOTE: DO NOT destroy this handle via CM_Disconnect_Machine. This
handle will be cleaned up when the device information set is destroyed
via SetupDiDestroyDeviceInfoList.
RemoteMachineName specifies the name used to connect to the remote
machine whose handle is stored in RemoteMachineHandle. If this is
not a device information set for a remote machine, this will be an
empty string.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
The cbSize field of the output structure must be set to
sizeof(SP_DEVINFO_LIST_DETAIL_DATA) or the call will fail with
ERROR_INVALID_USER_BUFFER.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PCTSTR MachineName;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
if(DeviceInfoSetDetailData->cbSize != sizeof(SP_DEVINFO_LIST_DETAIL_DATA)) {
Err = ERROR_INVALID_USER_BUFFER;
goto clean0;
}
//
// Store the set's associated class GUID, or GUID_NULL if there isn't one.
//
if(pDeviceInfoSet->HasClassGuid) {
CopyMemory(&(DeviceInfoSetDetailData->ClassGuid),
&(pDeviceInfoSet->ClassGuid),
sizeof(GUID)
);
} else {
CopyMemory(&(DeviceInfoSetDetailData->ClassGuid), &GUID_NULL, sizeof(GUID));
}
DeviceInfoSetDetailData->RemoteMachineHandle = pDeviceInfoSet->hMachine;
//
// If this is a remoted HDEVINFO, store the machine name in the caller's buffer,
// otherwise store an empty string.
//
if(pDeviceInfoSet->hMachine) {
MYASSERT(pDeviceInfoSet->MachineName != -1);
MachineName = pStringTableStringFromId(pDeviceInfoSet->StringTable, pDeviceInfoSet->MachineName);
MYVERIFY(SUCCEEDED(StringCchCopy(DeviceInfoSetDetailData->RemoteMachineName,
SIZECHARS(DeviceInfoSetDetailData->RemoteMachineName),
MachineName
)));
} else {
MYASSERT(pDeviceInfoSet->MachineName == -1);
*(DeviceInfoSetDetailData->RemoteMachineName) = TEXT('\0');
}
clean0: ; // nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return (Err == NO_ERROR);
}
BOOL
WINAPI
SetupDiDestroyDeviceInfoList(
IN HDEVINFO DeviceInfoSet
)
/*++
Routine Description:
This API destroys a device information set, freeing all associated memory.
Arguments:
DeviceInfoSet - Supplies a handle to a device information set to be destroyed.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
--*/
{
DWORD Err;
PDEVICE_INFO_SET pDeviceInfoSet;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
try {
Err = DestroyDeviceInfoSet(DeviceInfoSet, pDeviceInfoSet);
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_HANDLE;
}
SetLastError(Err);
return (Err == NO_ERROR);
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiCreateDeviceInfoA(
IN HDEVINFO DeviceInfoSet,
IN PCSTR DeviceName,
IN CONST GUID *ClassGuid,
IN PCSTR DeviceDescription, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD CreationFlags,
OUT PSP_DEVINFO_DATA DeviceInfoData OPTIONAL
)
{
PCWSTR deviceName,deviceDescription;
DWORD rc;
BOOL b;
b = FALSE;
rc = pSetupCaptureAndConvertAnsiArg(DeviceName,&deviceName);
if(rc == NO_ERROR) {
if(DeviceDescription) {
rc = pSetupCaptureAndConvertAnsiArg(DeviceDescription,&deviceDescription);
} else {
deviceDescription = NULL;
}
if(rc == NO_ERROR) {
b = SetupDiCreateDeviceInfoW(
DeviceInfoSet,
deviceName,
ClassGuid,
deviceDescription,
hwndParent,
CreationFlags,
DeviceInfoData
);
rc = GetLastError();
if(deviceDescription) {
MyFree(deviceDescription);
}
}
MyFree(deviceName);
} else {
//
// The DeviceName parameter was bad--return the same error the unicode API does.
//
rc = ERROR_INVALID_DEVINST_NAME;
}
SetLastError(rc);
return(b);
}
BOOL
WINAPI
SetupDiCreateDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN PCTSTR DeviceName,
IN CONST GUID *ClassGuid,
IN PCTSTR DeviceDescription, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD CreationFlags,
OUT PSP_DEVINFO_DATA DeviceInfoData OPTIONAL
)
/*++
Routine Description:
This API creates a new device information element, and adds it as a new member
to the specified set.
Arguments:
DeviceInfoSet - Supplies a handle to a device information set to which this
new device information element is to be added.
DeviceName - Supplies either a full device instance ID (e.g., Root\*PNP0500\0000)
or a Root-enumerated device ID, minus enumerator branch prefix and instance
ID suffix (e.g., *PNP0500). The latter may only be specified if the
DICD_GENERATE_ID flag is specified in the CreationFlags parameter.
ClassGuid - Supplies a pointer to the GUID for this device's class. If the
class is not yet known, this value should be GUID_NULL.
DeviceDescription - Optionally, supplies a textual description of the device.
hwndParent - Optionally, supplies the window handle of the top-level window
to use for any UI related to installing the device.
CreationFlags - Supplies flags controlling how the device information element
is to be created. May be a combination of the following values:
DICD_GENERATE_ID - If this flag is specified, then DeviceName contains only
a Root-enumerated device ID, and needs to have a unique
device instance key created for it. This unique device
instance key will be generated as:
Enum\Root\<DeviceName>\<InstanceID>
where <InstanceID> is a 4-digit, base-10 number that
is unique among all subkeys under Enum\Root\<DeviceName>.
The API, SetupDiGetDeviceInstanceId, may be called to
find out what ID was generated for this device information
element.
DICD_INHERIT_CLASSDRVS - If this flag is specified, then the resulting device
information element will inherit the class driver list (if any)
associated with the device information set itself. In addition,
if there is a selected driver for the device information set,
that same driver will be selected for the new device information
element.
DeviceInfoData - Optionaly, supplies a pointer to the variable that receives
a context structure initialized for this new device information element.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
If this device instance is being added to a set that has an associated class,
then the device class must be the same, or the call will fail, and GetLastError
will return ERROR_CLASS_MISMATCH.
If the specified device instance is the same as an existing device instance key in
the registry, the call will fail with ERROR_DEVINST_ALREADY_EXISTS. (This only
applies if DICD_GENERATE_ID is not specified.)
The specified class GUID will be written out to the ClassGUID device instance
value entry. If the class name can be retrieved (via SetupDiClassNameFromGuid),
then it will be written to the Class value entry as well.
If the new device information element was successfully created, but the
user-supplied DeviceInfoData buffer is invalid, this API will return FALSE, with
GetLastError returning ERROR_INVALID_USER_BUFFER. The device information element
_will_ have been added as a new member of the set, however.
Note that since new device information elements are always added at the end
of the existing list, the enumeration ordering is preserved, thus we don't
need to invalidate our enumeration hint.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err, StringLen;
PDEVINFO_ELEM DevInfoElem, PrevTailDevInfoElem;
DEVINST DevInst, RootDevInst;
CONFIGRET cr;
ULONG CmFlags;
TCHAR TempString[GUID_STRING_LEN];
PDRIVER_LIST_OBJECT CurDrvListObject;
//
// We use the TempString buffer both for the string representation of
// a Class GUID, and for the Class name. The following assert ensures
// that our assumptions about the relative lengths of these two strings
// continues to be valid.
//
MYASSERT(GUID_STRING_LEN >= MAX_CLASS_NAME_LEN);
if(CreationFlags & ~(DICD_GENERATE_ID | DICD_INHERIT_CLASSDRVS)) {
SetLastError(ERROR_INVALID_FLAGS);
return FALSE;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
DevInst = 0;
DevInfoElem = NULL;
try {
//
// Get a pointer to the current tail of the devinfo element list for this
// set, so that we can easily lop off the new node if we encounter an error
// after insertion.
//
PrevTailDevInfoElem = pDeviceInfoSet->DeviceInfoTail;
//
// Get a handle to the root device instance, to be used as the parent
// for the phantom device instance we're about to create.
//
if(CM_Locate_DevInst_Ex(&RootDevInst, NULL, CM_LOCATE_DEVINST_NORMAL,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
//
// We're really hosed if we can't get a handle to the root device
// instance!
//
Err = ERROR_INVALID_DATA;
goto clean0;
}
//
// Create a handle to a phantom device instance.
//
CmFlags = CM_CREATE_DEVINST_PHANTOM;
if(CreationFlags & DICD_GENERATE_ID) {
CmFlags |= CM_CREATE_DEVINST_GENERATE_ID;
}
if((cr = CM_Create_DevInst_Ex(&DevInst,
(DEVINSTID)DeviceName,
RootDevInst,
CmFlags,
pDeviceInfoSet->hMachine)) != CR_SUCCESS) {
//
// Make sure DevInst handle is still invalid, so we won't try to
// delete it later.
//
DevInst = 0;
Err = MapCrToSpError(cr, ERROR_INVALID_DATA);
goto clean0;
}
if(NO_ERROR != (Err = pSetupAddNewDeviceInfoElement(pDeviceInfoSet,
DevInst,
ClassGuid,
DeviceDescription,
hwndParent,
DIE_IS_PHANTOM,
pDeviceInfoSet,
&DevInfoElem))) {
//
// Make sure DevInfoElem is still NULL, so we won't try to free it later.
//
DevInfoElem = NULL;
goto clean0;
}
//
// Now, set the Class and ClassGUID properties for the new device instance.
//
pSetupStringFromGuid(ClassGuid, TempString, SIZECHARS(TempString));
CM_Set_DevInst_Registry_Property_Ex(DevInfoElem->DevInst,
CM_DRP_CLASSGUID,
(PVOID)TempString,
GUID_STRING_LEN * sizeof(TCHAR),
0,pDeviceInfoSet->hMachine);
if(!IsEqualGUID(ClassGuid, &GUID_NULL) &&
SetupDiClassNameFromGuid(ClassGuid,
TempString,
SIZECHARS(TempString),
&StringLen)) {
CM_Set_DevInst_Registry_Property_Ex(DevInfoElem->DevInst,
CM_DRP_CLASS,
(PVOID)TempString,
StringLen * sizeof(TCHAR),
0,pDeviceInfoSet->hMachine);
}
//
// If the caller wants the newly-created devinfo element to inherit the global
// class driver list, do that now.
//
if((CreationFlags & DICD_INHERIT_CLASSDRVS) && (pDeviceInfoSet->ClassDriverHead)) {
//
// Find the global class driver list in the devinfo set's list of driver lists.
//
CurDrvListObject = GetAssociatedDriverListObject(pDeviceInfoSet->ClassDrvListObjectList,
pDeviceInfoSet->ClassDriverHead,
NULL
);
MYASSERT(CurDrvListObject && (CurDrvListObject->RefCount > 0));
//
// We found the driver list object, now do the inheritance, and increment the refcount.
//
DevInfoElem->ClassDriverCount = pDeviceInfoSet->ClassDriverCount;
DevInfoElem->ClassDriverHead = pDeviceInfoSet->ClassDriverHead;
DevInfoElem->ClassDriverTail = pDeviceInfoSet->ClassDriverTail;
if(DevInfoElem->SelectedDriver = pDeviceInfoSet->SelectedClassDriver) {
DevInfoElem->SelectedDriverType = SPDIT_CLASSDRIVER;
}
DevInfoElem->InstallParamBlock.Flags |= CurDrvListObject->ListCreationFlags;
DevInfoElem->InstallParamBlock.FlagsEx |= CurDrvListObject->ListCreationFlagsEx;
DevInfoElem->InstallParamBlock.DriverPath = CurDrvListObject->ListCreationDriverPath;
CurDrvListObject->RefCount++;
}
clean0:
; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Reference the following variables so the compiler will respect our statement ordering
// w.r.t. assignment.
//
DevInst = DevInst;
DevInfoElem = DevInfoElem;
PrevTailDevInfoElem = PrevTailDevInfoElem;
}
if(Err == NO_ERROR) {
if(DeviceInfoData) {
//
// The user supplied a buffer to receive a SP_DEVINFO_DATA
// structure, so fill that in now.
//
try {
if(!(DevInfoDataFromDeviceInfoElement(pDeviceInfoSet,
DevInfoElem,
DeviceInfoData))) {
Err = ERROR_INVALID_USER_BUFFER;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_USER_BUFFER;
}
}
} else if(DevInst) {
//
// This should never fail.
//
cr = CM_Uninstall_DevInst(DevInst, 0);
MYASSERT(cr == CR_SUCCESS);
if(DevInfoElem) {
//
// An error occurred after we created the device information element--clean it up now.
//
try {
MYASSERT(!DevInfoElem->Next);
if(PrevTailDevInfoElem) {
MYASSERT(PrevTailDevInfoElem->Next == DevInfoElem);
PrevTailDevInfoElem->Next = NULL;
pDeviceInfoSet->DeviceInfoTail = PrevTailDevInfoElem;
} else {
pDeviceInfoSet->DeviceInfoHead = pDeviceInfoSet->DeviceInfoTail = NULL;
}
MYASSERT(pDeviceInfoSet->DeviceInfoCount > 0);
pDeviceInfoSet->DeviceInfoCount--;
MyFree(DevInfoElem);
} except(EXCEPTION_EXECUTE_HANDLER) {
; // nothing to do.
}
}
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiOpenDeviceInfoA(
IN HDEVINFO DeviceInfoSet,
IN PCSTR DeviceInstanceId,
IN HWND hwndParent, OPTIONAL
IN DWORD OpenFlags,
OUT PSP_DEVINFO_DATA DeviceInfoData OPTIONAL
)
{
PCWSTR deviceInstanceId;
DWORD rc;
BOOL b;
rc = pSetupCaptureAndConvertAnsiArg(DeviceInstanceId,&deviceInstanceId);
if(rc == NO_ERROR) {
b = SetupDiOpenDeviceInfoW(
DeviceInfoSet,
deviceInstanceId,
hwndParent,
OpenFlags,
DeviceInfoData
);
rc = GetLastError();
MyFree(deviceInstanceId);
} else {
b = FALSE;
}
SetLastError(rc);
return(b);
}
BOOL
WINAPI
SetupDiOpenDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN PCTSTR DeviceInstanceId,
IN HWND hwndParent, OPTIONAL
IN DWORD OpenFlags,
OUT PSP_DEVINFO_DATA DeviceInfoData OPTIONAL
)
/*++
Routine Description:
This API retrieves information about an existing device instance, and adds
it to the specified device information set. If a device information element
already exists for this device instance, the existing element is returned.
Arguments:
DeviceInfoSet - Supplies a handle to a device information set to which the
opened device information element is to be added.
DeviceInstanceId - Supplies the ID of the device instance. This is the
registry path (relative to the Enum branch) of the device instance key.
(E.g., Root\*PNP0500\0000)
hwndParent - Optionally, supplies the window handle of the top-level window
to use for any UI related to installing the device.
OpenFlags - Supplies flags controlling how the device information element
is to be opened. May be a combination of the following values:
DIOD_INHERIT_CLASSDRVS - If this flag is specified, then the resulting device
information element will inherit the class driver
list (if any) associated with the device information
set itself. In addition, if there is a selected
driver for the device information set, that same
driver will be selected for the new device information
element.
If the device information element was already present,
its class driver list (if any) will be replaced with
this new, inherited, list.
DIOD_CANCEL_REMOVE - If this flag is set, a device that was marked for removal
will be have its pending removal cancelled.
DeviceInfoData - Optionally, supplies a pointer to the variable that receives
a context structure initialized for the opened device information element.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
If this device instance is being added to a set that has an associated class,
then the device class must be the same, or the call will fail, and GetLastError
will return ERROR_CLASS_MISMATCH.
If the new device information element was successfully opened, but the
user-supplied DeviceInfoData buffer is invalid, this API will return FALSE,
with GetLastError returning ERROR_INVALID_USER_BUFFER. The device information
element _will_ have been added as a new member of the set, however.
Note that since new device information elements are always added at the end
of the existing list, the enumeration ordering is preserved, thus we don't
need to invalidate our enumeration hint.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem;
PDRIVER_LIST_OBJECT CurDrvListObject;
BOOL AlreadyPresent;
if(OpenFlags & ~(DIOD_INHERIT_CLASSDRVS | DIOD_CANCEL_REMOVE)) {
SetLastError(ERROR_INVALID_FLAGS);
return FALSE;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
Err = pSetupOpenAndAddNewDevInfoElem(pDeviceInfoSet,
DeviceInstanceId,
TRUE,
NULL,
hwndParent,
&DevInfoElem,
TRUE,
&AlreadyPresent,
FALSE,
((OpenFlags & DIOD_CANCEL_REMOVE)
? CM_LOCATE_DEVNODE_CANCELREMOVE : 0),
pDeviceInfoSet
);
if(Err != NO_ERROR) {
goto clean0;
}
//
// If the caller wants the newly-opened devinfo element to inherit the global
// class driver list, do that now.
//
if(OpenFlags & DIOD_INHERIT_CLASSDRVS) {
//
// If this devinfo element already existed, then it may already have a class
// driver list. Destroy that list before inheriting from the global class
// driver list.
//
if(AlreadyPresent) {
//
// If the selected driver is a class driver, then reset the selection.
//
if(DevInfoElem->SelectedDriverType == SPDIT_CLASSDRIVER) {
DevInfoElem->SelectedDriverType = SPDIT_NODRIVER;
DevInfoElem->SelectedDriver = NULL;
}
//
// Destroy the existing class driver list for this device.
//
DereferenceClassDriverList(pDeviceInfoSet, DevInfoElem->ClassDriverHead);
DevInfoElem->ClassDriverCount = 0;
DevInfoElem->ClassDriverHead = DevInfoElem->ClassDriverTail = NULL;
DevInfoElem->InstallParamBlock.Flags &= ~(DI_DIDCLASS | DI_MULTMFGS);
DevInfoElem->InstallParamBlock.FlagsEx &= ~DI_FLAGSEX_DIDINFOLIST;
}
if(pDeviceInfoSet->ClassDriverHead) {
//
// Find the global class driver list in the devinfo set's list of driver lists.
//
CurDrvListObject = GetAssociatedDriverListObject(pDeviceInfoSet->ClassDrvListObjectList,
pDeviceInfoSet->ClassDriverHead,
NULL
);
MYASSERT(CurDrvListObject && (CurDrvListObject->RefCount > 0));
//
// We found the driver list object, now increment its refcount, and do the
// inheritance.
//
CurDrvListObject->RefCount++;
DevInfoElem->ClassDriverCount = pDeviceInfoSet->ClassDriverCount;
DevInfoElem->ClassDriverHead = pDeviceInfoSet->ClassDriverHead;
DevInfoElem->ClassDriverTail = pDeviceInfoSet->ClassDriverTail;
if(pDeviceInfoSet->SelectedClassDriver) {
DevInfoElem->SelectedDriver = pDeviceInfoSet->SelectedClassDriver;
DevInfoElem->SelectedDriverType = SPDIT_CLASSDRIVER;
}
DevInfoElem->InstallParamBlock.Flags |= CurDrvListObject->ListCreationFlags;
DevInfoElem->InstallParamBlock.FlagsEx |= CurDrvListObject->ListCreationFlagsEx;
DevInfoElem->InstallParamBlock.DriverPath = CurDrvListObject->ListCreationDriverPath;
}
}
clean0: ; // nothing to do
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
if((Err == NO_ERROR) && DeviceInfoData) {
//
// The user supplied a buffer to receive a SP_DEVINFO_DATA
// structure, so fill that in now.
//
try {
if(!(DevInfoDataFromDeviceInfoElement(pDeviceInfoSet,
DevInfoElem,
DeviceInfoData))) {
Err = ERROR_INVALID_USER_BUFFER;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_USER_BUFFER;
}
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
//
// ANSI version
//
HDEVINFO
WINAPI
SetupDiGetClassDevsA(
IN CONST GUID *ClassGuid, OPTIONAL
IN PCSTR Enumerator, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD Flags
)
{
PCWSTR enumerator;
DWORD rc;
HDEVINFO h;
if(Enumerator) {
rc = pSetupCaptureAndConvertAnsiArg(Enumerator,&enumerator);
if(rc != NO_ERROR) {
SetLastError(rc);
return INVALID_HANDLE_VALUE;
}
} else {
enumerator = NULL;
}
h = SetupDiGetClassDevsExW(ClassGuid,
enumerator,
hwndParent,
Flags,
NULL,
NULL,
NULL
);
rc = GetLastError();
if(enumerator) {
MyFree(enumerator);
}
SetLastError(rc);
return h;
}
HDEVINFO
WINAPI
SetupDiGetClassDevs(
IN CONST GUID *ClassGuid, OPTIONAL
IN PCTSTR Enumerator, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD Flags
)
/*++
Routine Description:
See SetupDiGetClassDevsEx for details.
--*/
{
return SetupDiGetClassDevsEx(ClassGuid,
Enumerator,
hwndParent,
Flags,
NULL,
NULL,
NULL
);
}
//
// ANSI version
//
HDEVINFO
WINAPI
SetupDiGetClassDevsExA(
IN CONST GUID *ClassGuid, OPTIONAL
IN PCSTR Enumerator, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD Flags,
IN HDEVINFO DeviceInfoSet, OPTIONAL
IN PCSTR MachineName, OPTIONAL
IN PVOID Reserved
)
{
PCWSTR UnicodeEnumerator, UnicodeMachineName;
DWORD rc;
HDEVINFO h;
h = INVALID_HANDLE_VALUE;
if(Enumerator) {
rc = pSetupCaptureAndConvertAnsiArg(Enumerator, &UnicodeEnumerator);
if(rc != NO_ERROR) {
goto clean0;
}
} else {
UnicodeEnumerator = NULL;
}
if(MachineName) {
rc = pSetupCaptureAndConvertAnsiArg(MachineName,&UnicodeMachineName);
if(rc != NO_ERROR) {
goto clean1;
}
} else {
UnicodeMachineName = NULL;
}
h = SetupDiGetClassDevsExW(ClassGuid,
UnicodeEnumerator,
hwndParent,
Flags,
DeviceInfoSet,
UnicodeMachineName,
Reserved
);
rc = GetLastError();
if(UnicodeMachineName) {
MyFree(UnicodeMachineName);
}
clean1:
if(UnicodeEnumerator) {
MyFree(UnicodeEnumerator);
}
clean0:
SetLastError(rc);
return h;
}
HDEVINFO
WINAPI
SetupDiGetClassDevsEx(
IN CONST GUID *ClassGuid, OPTIONAL
IN PCTSTR Enumerator, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD Flags,
IN HDEVINFO DeviceInfoSet, OPTIONAL
IN PCTSTR MachineName, OPTIONAL
IN PVOID Reserved
)
/*++
Routine Description:
This routine returns a device information set containing all installed
devices of the specified class.
Arguments:
ClassGuid - Optionally, supplies the address of the class GUID to use
when creating the list of devices. If the DIGCF_ALLCLASSES flag is
set, then this parameter is ignored, and the resulting list will
contain all classes of devices (i.e., every installed device).
If the DIGCF_DEVICEINTERFACE flag _is not_ set, then this class GUID
represents a setup class.
If the DIGCF_DEVICEINTERFACE flag _is_ set, then this class GUID
represents an interface class.
Enumerator - Optional parameter that filters the members of the returned
device information set based on their enumerator (i.e., provider).
If the DIGCF_DEVICEINTERFACE flag _is not_ set in the Flags parameter,
then this string represents the name of the key under the Enum branch
containing devices instances for which information is to be retrieved.
If this parameter is not specified, then device information will be
retrieved for all device instances in the entire Enum tree.
If the DIGCF_DEVICEINTERFACE flag _is_ set, then this string represents
the PnP name of a particular device for which interfaces are to be
retrieved. In this case, the resulting device information set will
consist of a single device information element--the device whose name
was specified as the enumerator. The device interfaces provided by this
PnP device can then be enumerated via SetupDiEnumDeviceInterface.
hwndParent - Optionally, supplies the handle of the top-level window to be
used for any UI relating to the members of this set.
Flags - Supplies control options used in building the device information set.
May be a combination of the following values:
DIGCF_PRESENT - Return only devices that are currently present.
DIGCF_ALLCLASSES - Return a list of installed devices for all classes.
If set, this flag will cause ClassGuid to be ignored.
DIGCF_PROFILE - Return only devices that are a part of the current
hardware profile.
DIGCF_DEVICEINTERFACE - Return a list of all devices that expose interfaces
of the class specified by ClassGUID (NOTE: in this
context, ClassGuid is an interface class, _not_ a
setup class). The device interfaces exposed by the
members of the resulting set may be enumerated via
SetupDiEnumDeviceInterface.
DIGCF_DEFAULT - When used with DIGCF_DEVICEINTERFACE, this flag
results in a list that contains only one device
information element. Enumerating that device will
return exactly one device interface--the one that has
been marked as the system default device interface for
that particular interface class. If there is no default
device interface for the specified class, the API will
fail, and GetLastError will return
ERROR_NO_DEFAULT_DEVICE_INTERFACE.
DeviceInfoSet - Optionally, supplies the handle of an existing device
information set into which these new device information elements (and,
if DIGCF_DEVICEINTERFACE is specified, device interfaces) will be added.
If this parameter is specified, then this same HDEVINFO will be returned
upon success, with the retrieved device information/device interface
elements added. If this parameter is not specified, then a new device
information set will be created, and its handle returned.
NOTE: if this parameter is specified, then the associated class of this
device information set (if any) must match the ClassGuid specified, if
that class GUID is a setup class (i.e., the DIGCF_DEVICEINTERFACE flag
isn't set). If the DIGCF_DEVICEINTERFACE flag is set, then the device
interfaces retrieved will be filtered based on whether or not their
corresponding device's setup class matches that of the device
information set. This trick can be used, for example, to retrieve a
list of device interfaces of a particular interface class, but only if
those interfaces are exposed by devices of a particular setup class.
E.g.,
1. Create a device information set (via SetupDiCreateDeviceInfoList)
whose associated setup class is "Volume".
2. Call SetupDiGetClassDevsEx to retrieve a list of all device
interfaces of interface class "mounted device", passing in the
HDEVINFO retrieved in step 1.
The result of the above steps would be a device information set
containing all device interfaces of (interface) class "mounted device"
that are exposed by devnodes of (setup) class "Volume".
Note that retrieval of new device information elements into an existing
HDEVINFO set doesn't invalidate our devinfo enumeration hint, since new
devinfo elements are always added onto the end of the list.
MachineName - Optionally, supplies the name of a remote machine for which a
device information set is to be retrieved. If this parameter is NULL,
then the local machine is used.
Reserved - Reserved for future use--must be NULL.
Return Value:
If the function succeeds, the return value is a handle to a device
information set containing all installed devices matching the specified
parameters.
If the function fails, the return value is INVALID_HANDLE_VALUE. To get
extended error information, call GetLastError.
--*/
{
HDEVINFO hDevInfo;
PDEVICE_INFO_SET pDeviceInfoSet;
PDEVINFO_ELEM DevInfoElem;
DWORD Err;
CONFIGRET cr;
PTCHAR DevIdBuffer;
ULONG DevIdBufferLen, CSConfigFlags;
PTSTR CurDevId, DeviceInstanceToOpen;
HKEY hKeyDevClassRoot, hKeyCurDevClass;
TCHAR InterfaceGuidString[GUID_STRING_LEN];
BOOL GetInterfaceList, GetNextInterfaceClass;
DWORD InterfaceClassKeyIndex;
FILETIME LastWriteTime;
GUID GuidBuffer;
TCHAR DeviceInstanceId[MAX_DEVICE_ID_LEN];
DWORD RegDataType, DataBufferSize;
BOOL DevInfoAlreadyPresent, IsActive, IsDefault;
SP_DEVINFO_DATA DeviceInfoData;
CONST GUID * ExistingClassGuid;
//
// Make sure the user didn't pass us anything in the Reserved parameter.
//
if(Reserved) {
SetLastError(ERROR_INVALID_PARAMETER);
return INVALID_HANDLE_VALUE;
}
//
// Unless the caller wants a list of all classes, they'd better supply a class GUID.
//
if(!(Flags & DIGCF_ALLCLASSES) && !ClassGuid) {
SetLastError(ERROR_INVALID_PARAMETER);
return INVALID_HANDLE_VALUE;
}
//
// DIGCF_DEFAULT can only be used in conjunction with DIGCF_DEVICEINTERFACE.
//
if((Flags & (DIGCF_DEFAULT | DIGCF_DEVICEINTERFACE)) == DIGCF_DEFAULT) {
SetLastError(ERROR_INVALID_FLAGS);
return INVALID_HANDLE_VALUE;
}
if(!DeviceInfoSet || (DeviceInfoSet == INVALID_HANDLE_VALUE)) {
//
// The caller didn't supply us with a device information set in which
// to add our newly-retrieved elements, so we need to create our own.
//
if((hDevInfo = SetupDiCreateDeviceInfoListEx((Flags & (DIGCF_ALLCLASSES | DIGCF_DEVICEINTERFACE))
? NULL
: ClassGuid,
hwndParent,
MachineName,
NULL)) == INVALID_HANDLE_VALUE) {
//
// Last error already set.
//
MYASSERT(GetLastError());
return INVALID_HANDLE_VALUE;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(hDevInfo))) {
//
// this should not happen
//
MYASSERT(pDeviceInfoSet);
SetLastError(ERROR_INVALID_HANDLE);
return INVALID_HANDLE_VALUE;
}
} else {
//
// The caller wants us to use an existing device information set. Make
// a copy of it, and work with that one, so that if something fails, we
// haven't messed up the original one.
//
// NOTE: DO NOT do anything with the DeviceInfoSet after this point,
// as doing so will get the original out-of-sync with the current copy
// we're working with.
//
hDevInfo = NULL;
pDeviceInfoSet = CloneDeviceInfoSet(DeviceInfoSet);
if(!pDeviceInfoSet) {
SetLastError(ERROR_INVALID_PARAMETER);
return INVALID_HANDLE_VALUE;
}
}
Err = NO_ERROR;
DevIdBuffer = NULL;
hKeyDevClassRoot = hKeyCurDevClass = INVALID_HANDLE_VALUE;
try {
//
// If the caller supplied us with a previously-existing devinfo set in
// which to add new elements, we need to make sure that the setup class
// GUID associated with this devinfo set (if any) matches the setup
// class GUID that the caller supplied.
//
if(hDevInfo) {
//
// We always want the ExistingClassGuid pointer to be NULL when we
// haven't been passed in a previously-existing device information
// set.
//
ExistingClassGuid = NULL;
} else {
if(pDeviceInfoSet->HasClassGuid) {
//
// Remember the devinfo set's associated setup class GUID, to
// be used later in filtering device interfaces based on the
// setup class of their underlying devnode.
//
ExistingClassGuid = &(pDeviceInfoSet->ClassGuid);
if(ClassGuid && !(Flags & (DIGCF_ALLCLASSES | DIGCF_DEVICEINTERFACE))) {
if(!IsEqualGUID(ExistingClassGuid, ClassGuid)) {
Err = ERROR_CLASS_MISMATCH;
goto clean0;
}
}
} else {
//
// The caller-supplied devinfo set had no associated setup
// class. Remember that fact, so that we won't try to filter
// device interfaces based on the underlying devices' setup
// class.
//
ExistingClassGuid = NULL;
}
}
if(GetInterfaceList = (Flags & DIGCF_DEVICEINTERFACE)) { // yes, we want an assignment here.
//
// Open the root of the DeviceClasses registry branch
//
hKeyDevClassRoot = SetupDiOpenClassRegKeyEx(NULL,
KEY_READ,
DIOCR_INTERFACE,
MachineName,
NULL
);
if(hKeyDevClassRoot == INVALID_HANDLE_VALUE) {
Err = GetLastError();
goto clean0;
}
if(Flags & DIGCF_ALLCLASSES) {
InterfaceClassKeyIndex = 0;
ClassGuid = &GuidBuffer;
}
if(Flags & DIGCF_PRESENT) {
//
// Since we're only going to be retrieving a list of device
// interfaces that are currently 'active', we can set the
// 'IsActive' flag to always be TRUE.
//
IsActive = TRUE;
}
}
//
// As an optimization, start out with a 16K (character) buffer, in the hopes of avoiding
// two scans through the hardware tree (once to get the size, and again to get the data).
//
DevIdBufferLen = 16384;
do {
if(GetInterfaceList) {
if(Flags & DIGCF_ALLCLASSES) {
//
// We have to enumerate through all device interface classes, and retrieve
// a list of device interfaces for each one.
//
DataBufferSize = SIZECHARS(InterfaceGuidString);
switch(RegEnumKeyEx(hKeyDevClassRoot,
InterfaceClassKeyIndex,
InterfaceGuidString,
&DataBufferSize,
NULL,
NULL,
NULL,
&LastWriteTime)) {
case ERROR_SUCCESS :
GetNextInterfaceClass = TRUE;
InterfaceClassKeyIndex++;
break;
case ERROR_NO_MORE_ITEMS :
//
// We've processed all of the interface class GUIDs--we're done.
//
GetNextInterfaceClass = FALSE;
continue;
default :
//
// Some other error occurred. Skip this subkey, and continue
// with the next one.
//
GetNextInterfaceClass = TRUE;
InterfaceClassKeyIndex++;
continue;
}
//
// Convert the GUID string retrieved above into its binary form, for use
// below.
//
if(pSetupGuidFromString(InterfaceGuidString, &GuidBuffer) != NO_ERROR) {
//
// The subkey we enumerated is not a valid GUID string--skip this
// subkey, and continue on with the next one.
//
continue;
}
} else {
//
// We're just retrieving devices for a single interface class (which the
// caller specified). All we need to do is initialize the GUID string
// buffer with the textual form of the GUID.
//
pSetupStringFromGuid(ClassGuid,
InterfaceGuidString,
SIZECHARS(InterfaceGuidString)
);
//
// We only need to go through this list once.
//
GetNextInterfaceClass = FALSE;
}
//
// We'll be using the same character buffer to store each device instance ID
// we're opening below.
//
DeviceInstanceToOpen = DeviceInstanceId;
} else {
//
// We're not retrieving a list of device interfaces, so we'll never go through
// this loop more than once.
//
GetNextInterfaceClass = FALSE;
}
//
// Retrieve a list of device names.
//
while(TRUE) {
if(!DevIdBuffer) {
if(!(DevIdBuffer = MyMalloc(DevIdBufferLen * sizeof(TCHAR)))) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
}
if(GetInterfaceList) {
cr = CM_Get_Device_Interface_List_Ex((LPGUID)ClassGuid,
(DEVINSTID)Enumerator,
DevIdBuffer,
DevIdBufferLen,
(Flags & DIGCF_PRESENT)
? CM_GET_DEVICE_INTERFACE_LIST_PRESENT
: CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES,
pDeviceInfoSet->hMachine
);
} else {
cr = CM_Get_Device_ID_List_Ex(Enumerator,
DevIdBuffer,
DevIdBufferLen,
Enumerator ? CM_GETIDLIST_FILTER_ENUMERATOR
: CM_GETIDLIST_FILTER_NONE,
pDeviceInfoSet->hMachine
);
}
if(cr == CR_SUCCESS) {
//
// Device list successfully retrieved!
//
break;
} else {
//
// Free the current buffer before determining what error occurred.
//
MyFree(DevIdBuffer);
DevIdBuffer = NULL;
if(cr == CR_BUFFER_SMALL) {
//
// OK, so our buffer wasn't big enough--just how big
// does it need to be?
//
if(GetInterfaceList) {
if(CM_Get_Device_Interface_List_Size_Ex(&DevIdBufferLen,
(LPGUID)ClassGuid,
(DEVINSTID)Enumerator,
(Flags & DIGCF_PRESENT)
? CM_GET_DEVICE_INTERFACE_LIST_PRESENT
: CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
//
// Couldn't retrieve the list size--this should
// never happen.
//
Err = ERROR_INVALID_DATA;
goto clean0;
}
} else {
if(CM_Get_Device_ID_List_Size_Ex(&DevIdBufferLen,
Enumerator,
Enumerator ? CM_GETIDLIST_FILTER_ENUMERATOR
: CM_GETIDLIST_FILTER_NONE,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
//
// Couldn't retrieve the list size--this should
// never happen.
//
Err = ERROR_INVALID_DATA;
goto clean0;
}
}
} else {
//
// An error occurred, and it wasn't because we supplied
// too small a buffer.
//
Err = ERROR_INVALID_DATA;
goto clean0;
}
}
}
//
// We have now retrieved a list of all the specified devices. If
// these are device interfaces, we need to open the key for this
// interface class underneath the DeviceClasses key.
//
if(GetInterfaceList) {
if(RegOpenKeyEx(hKeyDevClassRoot,
InterfaceGuidString,
0,
KEY_READ,
&hKeyCurDevClass) != ERROR_SUCCESS) {
//
// Make sure hKeyCurDevClass is still set to
// INVALID_HANDLE_VALUE, so that we'll know not to close it.
//
hKeyCurDevClass = INVALID_HANDLE_VALUE;
//
// Skip this interface class.
//
continue;
}
}
//
// Now create device information elements from the members of this
// list.
//
for(CurDevId = DevIdBuffer;
*CurDevId;
CurDevId += lstrlen(CurDevId) + 1) {
//
// If this is a device interface, we must retrieve the
// associated device instance name.
//
if(GetInterfaceList) {
if(NO_ERROR != pSetupGetDevInstNameAndStatusForDeviceInterface(
hKeyCurDevClass,
CurDevId,
DeviceInstanceId,
SIZECHARS(DeviceInstanceId),
(Flags & DIGCF_PRESENT) ? NULL : &IsActive,
&IsDefault)) {
//
// Couldn't retrieve the name of the owning device
// instance--skip this device interface.
//
continue;
}
if ((Flags & DIGCF_DEFAULT) && !IsDefault) {
//
// The caller only wants the default device interface.
// Since CM_Get_Device_Interface_List places the default
// device interface first in the list (if there is one),
// and we stop searching the list when we find it, we
// know that if we get here, there is no default device
// interface for this interface class.
//
Err = ERROR_NO_DEFAULT_DEVICE_INTERFACE;
goto clean0;
}
} else {
DeviceInstanceToOpen = CurDevId;
}
if(Flags & DIGCF_PROFILE) {
//
// Verify that this device instance is part of the current
// hardware profile.
//
if(CM_Get_HW_Prof_Flags_Ex(DeviceInstanceToOpen,
0,
&CSConfigFlags,
0,
pDeviceInfoSet->hMachine) == CR_SUCCESS) {
if(CSConfigFlags & CSCONFIGFLAG_DO_NOT_CREATE) {
continue;
}
}
}
//
// Note the last parameter in the following call to
// pSetupOpenAndAddNewDevInfoElem--in the case where we're
// adding to an existing caller-supplied HDEVINFO set (i.e.,
// hDevInfo is NULL), we cast the HDEVINFO to a DEVICE_INFO_SET
// pointer, since that's what ends up getting stored in the
// ContainingDeviceInfoSet field of a devinfo element structure.
// That field is used for quick validation that a caller-
// supplied device information element is valid.
//
// If we ever decide to change the internal implementation of
// how an HDEVINFO translates into its underlying
// DEVICE_INFO_SET, then we'll need to update the code below
// accordingly. (See also the comments under
// AccessDeviceInfoSet, CloneDeviceInfoSet, and
// RollbackDeviceInfoSet.)
//
Err = pSetupOpenAndAddNewDevInfoElem(pDeviceInfoSet,
DeviceInstanceToOpen,
!(Flags & DIGCF_PRESENT),
((Flags & (DIGCF_ALLCLASSES | DIGCF_DEVICEINTERFACE))
? ExistingClassGuid
: ClassGuid),
hwndParent,
&DevInfoElem,
(GetInterfaceList || !hDevInfo),
&DevInfoAlreadyPresent,
FALSE,
0,
(hDevInfo ? pDeviceInfoSet : (PDEVICE_INFO_SET)DeviceInfoSet)
);
if(Err != NO_ERROR) {
if(Err == ERROR_NOT_ENOUGH_MEMORY) {
goto clean0;
}
Err = NO_ERROR;
continue;
}
if(GetInterfaceList) {
//
// Now that we've successfully opened up the device instance that 'owns'
// this device interface, add a new device interface node onto this
// devinfo element's list.
//
if(NO_ERROR != (Err = pSetupAddDeviceInterfaceToDevInfoElem(pDeviceInfoSet,
DevInfoElem,
ClassGuid,
CurDevId,
IsActive,
IsDefault,
!hDevInfo,
FALSE,
NULL))) {
//
// The only error we should be getting back from this routine is
// out-of-memory, which is always a fatal error.
//
goto clean0;
}
if ((Flags & DIGCF_DEFAULT) && IsDefault) {
//
// The caller only wants the default device interface,
// and this is it.
//
if ((Flags & DIGCF_PRESENT) && !IsActive) {
//
// The caller doesn't want to know about a
// non-present default device interface.
//
Err = ERROR_NO_DEFAULT_DEVICE_INTERFACE;
}
RegCloseKey(hKeyCurDevClass);
hKeyCurDevClass = INVALID_HANDLE_VALUE;
goto clean0;
}
}
}
//
// If we're working with device interfaces, we need to close the interface
// class key we opened above.
//
if(GetInterfaceList) {
RegCloseKey(hKeyCurDevClass);
hKeyCurDevClass = INVALID_HANDLE_VALUE;
}
} while(GetNextInterfaceClass);
clean0:
; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
if(hKeyCurDevClass != INVALID_HANDLE_VALUE) {
RegCloseKey(hKeyCurDevClass);
}
//
// Access the following variables, so the compiler will respect
// the statement ordering in the try clause.
//
DevIdBuffer = DevIdBuffer;
hKeyDevClassRoot = hKeyDevClassRoot;
}
if(DevIdBuffer) {
MyFree(DevIdBuffer);
}
if(hKeyDevClassRoot != INVALID_HANDLE_VALUE) {
RegCloseKey(hKeyDevClassRoot);
}
if(Err != NO_ERROR) {
if(hDevInfo) {
DestroyDeviceInfoSet(hDevInfo, pDeviceInfoSet);
} else {
if(!(pDeviceInfoSet = RollbackDeviceInfoSet(DeviceInfoSet, pDeviceInfoSet))) {
MYASSERT(pDeviceInfoSet);
} else {
UnlockDeviceInfoSet(pDeviceInfoSet);
}
}
SetLastError(Err);
hDevInfo = INVALID_HANDLE_VALUE;
} else {
if(!hDevInfo) {
//
// We retrieved additional elements into an existing device
// information set. Replace the existing device information set
// with the new one (i.e., into the same handle), and return the
// same HDEVINFO handle that the caller passed in as the
// DeviceInfoSet parameter.
//
pDeviceInfoSet = CommitDeviceInfoSet(DeviceInfoSet, pDeviceInfoSet);
MYASSERT(pDeviceInfoSet);
//
// Set hDevInfo to be the same as the DeviceInfoSet handle we were
// passed in, so that we can return it to the caller.
//
hDevInfo = DeviceInfoSet;
MYASSERT(hDevInfo);
}
if (pDeviceInfoSet) {
UnlockDeviceInfoSet(pDeviceInfoSet);
}
MYASSERT(hDevInfo != INVALID_HANDLE_VALUE);
}
return hDevInfo;
}
BOOL
WINAPI
SetupDiSetDeviceInterfaceDefault(
IN HDEVINFO DeviceInfoSet,
IN OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
IN DWORD Flags,
IN PVOID Reserved
)
/*++
Routine Description:
This routine sets the specified device interface as the default device
interface for its class.
Arguments:
DeviceInfoSet - Points to the device information set containing the device
interface for which to set as the default device interface. This handle
is typically returned by SetupDiGetClassDevs.
DeviceInterfaceData - Points to a structure that identifies the device
interface within the device information set. This pointer is typically
returned by SetupDiEnumDeviceInterfaces. If successful, this routine
will update the information contained in this structure.
Flags - Not used, must be zero.
Reserved - Reserved for future use, must be NULL.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
The caller must have the appropriate permission to set the default device
interface.
--*/
{
DWORD Err;
PDEVICE_INFO_SET pDeviceInfoSet;
PDEVINFO_ELEM DevInfoElem;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode;
PCTSTR MachineName, DeviceInterfaceName;
HKEY hKeyInterfaceClass = INVALID_HANDLE_VALUE;
BOOL IsActive, IsDefault;
//
// Make sure the user didn't pass us anything in the Reserved parameter.
//
if(Reserved) {
SetLastError(ERROR_INVALID_PARAMETER);
return FALSE;
}
if(Flags & ~(0x0)) {
SetLastError(ERROR_INVALID_FLAGS);
return FALSE;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// First, find the devinfo element that owns this device interface (for validation).
//
if(!(DevInfoElem = FindDevInfoElemForDeviceInterface(pDeviceInfoSet, DeviceInterfaceData))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// Retrieve the name of the machine associated with this DeviceInfoSet.
//
if(pDeviceInfoSet->hMachine) {
MYASSERT(pDeviceInfoSet->MachineName != -1);
MachineName = pStringTableStringFromId(pDeviceInfoSet->StringTable,
pDeviceInfoSet->MachineName);
} else {
MachineName = NULL;
}
//
// The Reserved field contains a pointer to the underlying device interface node.
//
DeviceInterfaceNode = (PDEVICE_INTERFACE_NODE)(DeviceInterfaceData->Reserved);
//
// Retrieve the device path (symbolic link name) for this device interface.
//
DeviceInterfaceName = pStringTableStringFromId(pDeviceInfoSet->StringTable,
DeviceInterfaceNode->SymLinkName);
//
// Open this interface class key under the DeviceClasses registry branch.
//
hKeyInterfaceClass = SetupDiOpenClassRegKeyEx(&DeviceInterfaceData->InterfaceClassGuid,
KEY_READ | KEY_WRITE,
DIOCR_INTERFACE,
MachineName,
NULL);
if(hKeyInterfaceClass == INVALID_HANDLE_VALUE) {
Err = GetLastError();
goto clean0;
}
//
// Get the current status of this device interface.
//
Err = pSetupGetDevInstNameAndStatusForDeviceInterface(hKeyInterfaceClass,
DeviceInterfaceName,
NULL,
0,
&IsActive,
&IsDefault);
if (Err != NO_ERROR) {
goto clean0;
}
//
// If this interface is already the default, then we're done.
//
if (IsDefault) {
goto clean1;
}
//
// Set the "Default" value under this interface class key to this device
// interface.
//
Err = RegSetValueEx(hKeyInterfaceClass,
pszDefault,
0,
REG_SZ,
(PBYTE)DeviceInterfaceName,
(lstrlen(DeviceInterfaceName) + 1) * sizeof(TCHAR));
if (Err != NO_ERROR) {
goto clean0;
}
//
// This interface was successfully set as the default device interface
// for this interface class.
//
IsDefault = TRUE;
clean1:
//
// Update the flags for this interface.
//
DeviceInterfaceNode->Flags = (DeviceInterfaceNode->Flags & ~SPINT_ACTIVE) | (IsActive ? SPINT_ACTIVE : 0);
DeviceInterfaceNode->Flags = (DeviceInterfaceNode->Flags & ~SPINT_DEFAULT) | (IsDefault ? SPINT_DEFAULT : 0);
//
// Finally, update the flags in the caller-supplied buffer to indicate the new status
// of this device interface.
//
DeviceInterfaceData->Flags = DeviceInterfaceNode->Flags;
clean0:
if(hKeyInterfaceClass != INVALID_HANDLE_VALUE) {
RegCloseKey(hKeyInterfaceClass);
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return (Err == NO_ERROR);
}
DWORD
pSetupAddNewDeviceInfoElement(
IN PDEVICE_INFO_SET pDeviceInfoSet,
IN DEVINST DevInst,
IN CONST GUID *ClassGuid,
IN PCTSTR Description, OPTIONAL
IN HWND hwndParent, OPTIONAL
IN DWORD DiElemFlags,
IN PDEVICE_INFO_SET ContainingDeviceInfoSet,
OUT PDEVINFO_ELEM *DeviceInfoElement
)
/*++
Routine Description:
This routine creates a new device information element based on the
supplied information, and adds it to the specified device information set.
ASSUMES THAT THE CALLING ROUTINE HAS ALREADY ACQUIRED THE LOCK!
Arguments:
pDeviceInfoSet - Device information set to add this new element to.
DevInst - Supplies the device instance handle of the element to be added.
ClassGuid - Class GUID of the element to be added.
Description - Optionally, supplies the description of the element to
be added.
hwndParent - Optionally, supplies the handle to the top level window for
UI relating to this element.
DiElemFlags - Specifies flags pertaining to the device information element
being created.
ContainingDeviceInfoSet - Supplies a pointer to the device information set
structure with which this element is to be associated. This may be
different from the pDeviceInfoSet parameter if we're working against a
cloned devinfo set (i.e., to facilitate rollback).
DeviceInfoElement - Supplies the address of the variable that receives a
pointer to the newly-allocated device information element.
Return Value:
If the function succeeds, the return value is NO_ERROR, otherwise the
ERROR_* code is returned.
Remarks:
Since the new element is added onto the end of the existing list, our
enumeration hint isn't invalidated.
--*/
{
DWORD Err = NO_ERROR;
TCHAR TempString[LINE_LEN];
*DeviceInfoElement = NULL;
try {
//
// If there is a class associated with this device information set,
// verify that it is the same as that of the new element.
//
if(pDeviceInfoSet->HasClassGuid &&
!IsEqualGUID(&(pDeviceInfoSet->ClassGuid), ClassGuid)) {
Err = ERROR_CLASS_MISMATCH;
goto clean0;
}
//
// Allocate storage for the element.
//
if(!(*DeviceInfoElement = MyMalloc(sizeof(DEVINFO_ELEM)))) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
ZeroMemory(*DeviceInfoElement, sizeof(DEVINFO_ELEM));
//
// Store the address of the containing devinfo set in the structure
// for this element. This is used for efficient validation of a
// caller-supplied SP_DEVINFO_DATA.
//
(*DeviceInfoElement)->ContainingDeviceInfoSet = ContainingDeviceInfoSet;
//
// Initialize the element with the specified information
//
CopyMemory(&((*DeviceInfoElement)->ClassGuid),
ClassGuid,
sizeof(GUID)
);
(*DeviceInfoElement)->InstallParamBlock.hwndParent = hwndParent;
if(Description) {
//
// Set the device instance's DeviceDesc property to the specified
// description.
//
CM_Set_DevInst_Registry_Property_Ex(DevInst,
CM_DRP_DEVICEDESC,
Description,
(lstrlen(Description) + 1) * sizeof(TCHAR),
0,
pDeviceInfoSet->hMachine);
//
// Store two versions of the description--one case-sensitive (for display)
// and the other case-insensitive (for fast lookup).
//
MYVERIFY(SUCCEEDED(StringCchCopy(TempString, SIZECHARS(TempString), Description)));
if((((*DeviceInfoElement)->DeviceDescriptionDisplayName =
pStringTableAddString(pDeviceInfoSet->StringTable,
TempString,
STRTAB_CASE_SENSITIVE,
NULL,0)) == -1) ||
(((*DeviceInfoElement)->DeviceDescription =
pStringTableAddString(pDeviceInfoSet->StringTable,
TempString,
STRTAB_CASE_INSENSITIVE | STRTAB_BUFFER_WRITEABLE,
NULL,0)) == -1)) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
} else {
(*DeviceInfoElement)->DeviceDescription =
(*DeviceInfoElement)->DeviceDescriptionDisplayName = -1;
}
(*DeviceInfoElement)->DevInst = DevInst;
(*DeviceInfoElement)->DiElemFlags = DiElemFlags;
(*DeviceInfoElement)->InstallParamBlock.DriverPath = -1;
(*DeviceInfoElement)->InstallParamBlock.CoInstallerCount = -1;
//
// If we're in GUI-mode setup on Windows NT, we'll automatically set
// the DI_FLAGSEX_IN_SYSTEM_SETUP flag in the devinstall parameter
// block for this devinfo element.
//
if(GuiSetupInProgress) {
(*DeviceInfoElement)->InstallParamBlock.FlagsEx |= DI_FLAGSEX_IN_SYSTEM_SETUP;
}
//
// If we're in non-interactive mode, set the "be quiet" bits.
//
if(GlobalSetupFlags & (PSPGF_NONINTERACTIVE|PSPGF_UNATTENDED_SETUP)) {
(*DeviceInfoElement)->InstallParamBlock.Flags |= DI_QUIETINSTALL;
(*DeviceInfoElement)->InstallParamBlock.FlagsEx |= DI_FLAGSEX_NOUIONQUERYREMOVE;
}
//
// Initialize our enumeration 'hints'
//
(*DeviceInfoElement)->ClassDriverEnumHintIndex = INVALID_ENUM_INDEX;
(*DeviceInfoElement)->CompatDriverEnumHintIndex = INVALID_ENUM_INDEX;
//
// Create a log context separate from the parent.
//
if(NO_ERROR != CreateLogContext(NULL,
FALSE,
&((*DeviceInfoElement)->InstallParamBlock.LogContext))) {
//
// If it failed, we will inherit the log context, since it's better
// than nothing. In theory, this should never happen, or if it
// does, other things will fail too...
//
Err = InheritLogContext(
pDeviceInfoSet->InstallParamBlock.LogContext,
&(*DeviceInfoElement)->InstallParamBlock.LogContext
);
if(Err != NO_ERROR) {
//
// If we can't get a log context at all, then we gotta bail...
//
goto clean0;
}
}
//
// Now, insert the new element at the end of the device
// information set's list of elements.
//
if(pDeviceInfoSet->DeviceInfoHead) {
pDeviceInfoSet->DeviceInfoTail->Next = *DeviceInfoElement;
pDeviceInfoSet->DeviceInfoTail = *DeviceInfoElement;
} else {
pDeviceInfoSet->DeviceInfoHead =
pDeviceInfoSet->DeviceInfoTail = *DeviceInfoElement;
}
pDeviceInfoSet->DeviceInfoCount++;
clean0:
; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
if((Err != NO_ERROR) && *DeviceInfoElement) {
MyFree(*DeviceInfoElement);
*DeviceInfoElement = NULL;
}
return Err;
}
DWORD
pSetupClassGuidFromDevInst(
IN DEVINST DevInst,
IN HMACHINE hMachine,
OUT LPGUID ClassGuid
)
/*++
Routine Description:
This routine attempts to retrieve the class GUID for the specified device
instance from its device registry key. If it cannot retrieve one, it
returns GUID_NULL.
Arguments:
DevInst - Supplies the handle of the device instance whose class GUID is
to be retrieved.
hMachine - Machine context to operate in
ClassGuid - Supplies the address of the variable that receives the class
GUID, or GUID_NULL if no class GUID can be retrieved.
Return Value:
If the function succeeds, the return value is NO_ERROR.
If the function fails, an ERROR_* code is returned. (Presently, the only
failure condition returned is ERROR_NOT_ENOUGH_MEMORY.)
--*/
{
DWORD NumGuids;
TCHAR TempString[GUID_STRING_LEN];
DWORD StringSize;
StringSize = sizeof(TempString);
if(CM_Get_DevInst_Registry_Property_Ex(DevInst,
CM_DRP_CLASSGUID,
NULL,
TempString,
&StringSize,
0,
hMachine) == CR_SUCCESS) {
//
// We retrieved the class GUID (in string form) for this device
// instance--now, convert it into its binary representation.
//
return pSetupGuidFromString(TempString, ClassGuid);
}
//
// We couldn't retrieve a ClassGUID--let's see if there's a Class name we can
// work with.
//
StringSize = sizeof(TempString);
if(CM_Get_DevInst_Registry_Property_Ex(DevInst,
CM_DRP_CLASS,
NULL,
TempString,
&StringSize,
0,
hMachine) == CR_SUCCESS) {
//
// OK, we found out the class name. Now see if we can find a
// single class GUID to match it.
//
if(SetupDiClassGuidsFromName(TempString, ClassGuid, 1, &NumGuids) && NumGuids) {
//
// We found exactly one, so we're happy.
//
return NO_ERROR;
}
}
//
// We have no idea what class of device this is, so use GUID_NULL.
//
CopyMemory(ClassGuid, &GUID_NULL, sizeof(GUID));
return NO_ERROR;
}
BOOL
WINAPI
SetupDiDeleteDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData
)
/*++
Routine Description:
This routine deletes a member from the specified device information set.
THIS DOES NOT DELETE ACTUAL DEVICES!
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
the device information element to be deleted.
DeviceInfoData - Supplies a pointer to the SP_DEVINFO_DATA structure for
the device information element to be deleted.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
If the specified device information element is explicitly in use by a wizard
page, then the call will fail, and GetLastError will return
ERROR_DEVINFO_DATA_LOCKED. This will happen if a handle to a wizard page was
retrieved via SetupDiGetWizardPage, and this element was specified, along with
the DIWP_FLAG_USE_DEVINFO_DATA flag. In order to be able to delete this element,
the wizard HPROPSHEETPAGE handle must be closed (either explicitly, or after a
call to PropertySheet() completes).
Since we don't track where this devinfo element lives in relation to our
current enumeration hint, we just invalidate the hint, so that next
enumeration must scan from the beginning of the list.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM ElemToDelete, PrevElem, NextElem;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// Get a pointer to the element we are to delete.
//
ElemToDelete = FindAssociatedDevInfoElem(pDeviceInfoSet,
DeviceInfoData,
&PrevElem
);
if(ElemToDelete) {
//
// Make sure that this element isn't currently locked by
// a wizard page.
//
if(ElemToDelete->DiElemFlags & DIE_IS_LOCKED) {
Err = ERROR_DEVINFO_DATA_LOCKED;
goto clean0;
}
NextElem = ElemToDelete->Next;
//
// Destroy the devinfo element. We need to do this before
// altering the list, because we will be calling the class
// installer with DIF_DESTROYPRIVATEDATA, and it needs to
// be able to access this element (obviously).
//
DestroyDeviceInfoElement(DeviceInfoSet, pDeviceInfoSet, ElemToDelete);
//
// Now remove the element from the list.
//
if(PrevElem) {
PrevElem->Next = NextElem;
} else {
pDeviceInfoSet->DeviceInfoHead = NextElem;
}
if(!NextElem) {
pDeviceInfoSet->DeviceInfoTail = PrevElem;
}
MYASSERT(pDeviceInfoSet->DeviceInfoCount > 0);
pDeviceInfoSet->DeviceInfoCount--;
//
// If this element was the currently selected device for this
// set, then reset the device selection.
//
if(pDeviceInfoSet->SelectedDevInfoElem == ElemToDelete) {
pDeviceInfoSet->SelectedDevInfoElem = NULL;
}
//
// Invalidate our enumeration hint for this devinfo element list.
//
pDeviceInfoSet->DeviceInfoEnumHint = NULL;
pDeviceInfoSet->DeviceInfoEnumHintIndex = INVALID_ENUM_INDEX;
} else {
Err = ERROR_INVALID_PARAMETER;
}
clean0: ; // nothing to do
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
BOOL
WINAPI
SetupDiEnumDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN DWORD MemberIndex,
OUT PSP_DEVINFO_DATA DeviceInfoData
)
/*++
Routine Description:
This API enumerates the members of the specified device information set.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set whose members
are to be enumerated.
MemberIndex - Supplies the zero-based index of the device information member
to be retreived.
DeviceInfoData - Supplies a pointer to a SP_DEVINFO_DATA structure that will
receive information about this member.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
To enumerate device information members, an application should initially call
the SetupDiEnumDeviceInfo function with the MemberIndex parameter set to zero.
The application should then increment MemberIndex and call the
SetupDiEnumDeviceInfo function until there are no more values (i.e., the
function fails, and GetLastError returns ERROR_NO_MORE_ITEMS).
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err, i;
PDEVINFO_ELEM DevInfoElem;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
if(MemberIndex >= pDeviceInfoSet->DeviceInfoCount) {
Err = ERROR_NO_MORE_ITEMS;
goto clean0;
}
//
// Find the element corresponding to the specified index (using our
// enumeration hint optimization, if possible)
//
if(pDeviceInfoSet->DeviceInfoEnumHintIndex <= MemberIndex) {
MYASSERT(pDeviceInfoSet->DeviceInfoEnumHint);
DevInfoElem = pDeviceInfoSet->DeviceInfoEnumHint;
i = pDeviceInfoSet->DeviceInfoEnumHintIndex;
} else {
DevInfoElem = pDeviceInfoSet->DeviceInfoHead;
i = 0;
}
for(; i < MemberIndex; i++) {
DevInfoElem = DevInfoElem->Next;
}
if(!(DevInfoDataFromDeviceInfoElement(pDeviceInfoSet,
DevInfoElem,
DeviceInfoData))) {
Err = ERROR_INVALID_USER_BUFFER;
}
//
// Remember this element as our new enumeration hint.
//
pDeviceInfoSet->DeviceInfoEnumHintIndex = MemberIndex;
pDeviceInfoSet->DeviceInfoEnumHint = DevInfoElem;
clean0:
; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
BOOL
WINAPI
SetupDiRegisterDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN OUT PSP_DEVINFO_DATA DeviceInfoData,
IN DWORD Flags,
IN PSP_DETSIG_CMPPROC CompareProc, OPTIONAL
IN PVOID CompareContext, OPTIONAL
OUT PSP_DEVINFO_DATA DupDeviceInfoData OPTIONAL
)
/*++
Routine Description:
This API registers a device instance with the Plug & Play Manager.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set that contains
the device information element for this device instance.
DeviceInfoData - Supplies a pointer to the SP_DEVINFO_DATA structure for the
device instance being registered. This is an IN OUT parameter, since the
DevInst field of the structure may be updated with a new handle value upon
return.
Flags - Controls how the device is to be registered. May be a combination of
the following values:
SPRDI_FIND_DUPS - Search for a previously-existing device instance
corresponding to this device information. If this
flag is not specified, the device instance will be
registered, regardless of whether a device instance
already exists for it.
CompareProc - Optionally, supplies a comparison callback function to be used in
duplicate detection. If specified, the function will be called for each
device instance that is of the same class as the device instance being
registered. The prototype of the callback function is as follows:
typedef DWORD (CALLBACK* PSP_DETSIG_CMPPROC)(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA NewDeviceData,
IN PSP_DEVINFO_DATA ExistingDeviceData,
IN PVOID CompareContext OPTIONAL
);
The compare function must return ERROR_DUPLICATE_FOUND if it finds the two
devices to be duplicates of each other, and NO_ERROR otherwise. If some
other error (e.g., out-of-memory) is encountered, the callback should return
the appropriate ERROR_* code indicating the failure that occurred.
If a CompareProc is not supplied, and duplicate detection is requested, then a
default comparison behavior will be used. (See pSetupDupDevCompare for details.)
CompareContext - Optionally, supplies the address of a caller-supplied context
buffer that will be passed into the compare callback routine. This parameter
is ignored if CompareProc is not supplied.
DupDeviceInfoData - Optionally, supplies a pointer to a device information
element that will be initialized for the duplicate device instance, if any,
discovered as a result of attempting to register this device. This will
be filled in if the function returns FALSE, and GetLastError returns
ERROR_DUPLICATE_FOUND. This device information element will be added as
a member of the specified DeviceInfoSet (if it wasn't already a member).
If DupDeviceInfoData is not supplied, then the duplicate WILL NOT be added
to the device information set.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
After registering a device information element, the caller should refresh any
stored copies of the devinst handle associated with this device, as the handle
value may have changed during registration. The caller need not re-retrieve
the SP_DEVINFO_DATA structure, because the devinst field of the DeviceInfoData
structure will be updated to reflect the current handle value.
This API may invalidate our devinfo element enumeration hint.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem, CurDevInfoElem;
CONFIGRET cr;
ULONG DevIdBufferLen, ulStatus, ulProblem;
PTCHAR DevIdBuffer = NULL;
PTSTR CurDevId;
DEVINST ParentDevInst;
BOOL AlreadyPresent;
SP_DEVINFO_DATA CurDevInfoData;
TCHAR DeviceInstanceId[MAX_DEVICE_ID_LEN];
DEFAULT_DEVCMP_CONTEXT DevCmpContext;
LOG_CONF NewDevLogConfig;
RES_DES NewDevResDes;
if(Flags & ~SPRDI_FIND_DUPS) {
SetLastError(ERROR_INVALID_FLAGS);
return FALSE;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
//
// Initialize the following variables so we'll know whether we need to free any of their
// associated resources.
//
ZeroMemory(&DevCmpContext, sizeof(DevCmpContext));
NewDevLogConfig = (LOG_CONF)NULL;
NewDevResDes = (RES_DES)NULL;
try {
DevInfoElem = FindAssociatedDevInfoElem(pDeviceInfoSet,
DeviceInfoData,
NULL
);
if(!DevInfoElem) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
} else if(DevInfoElem->DiElemFlags & DIE_IS_REGISTERED) {
//
// Nothing to do--it's already been registered.
//
goto clean0;
}
//
// If the caller requested duplicate detection then retrieve
// all device instances of this class, and compare each one
// with the device instance being registered.
//
if(Flags & SPRDI_FIND_DUPS) {
do {
if(CM_Get_Device_ID_List_Size_Ex(&DevIdBufferLen, NULL, CM_GETIDLIST_FILTER_NONE,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
Err = ERROR_INVALID_DATA;
goto clean0;
} else if(!DevIdBufferLen) {
break;
}
if(!(DevIdBuffer = MyMalloc(DevIdBufferLen * sizeof(TCHAR)))) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
cr = CM_Get_Device_ID_List_Ex(NULL,
DevIdBuffer,
DevIdBufferLen,
CM_GETIDLIST_FILTER_NONE,
pDeviceInfoSet->hMachine);
if(cr == CR_BUFFER_SMALL) {
//
// This will only happen if a device instance was added between
// the time that we calculated the size, and when we attempted
// to retrieve the list. In this case, we'll simply retrieve
// the size again, and re-attempt to retrieve the list.
//
MyFree(DevIdBuffer);
DevIdBuffer = NULL;
} else if(cr != CR_SUCCESS) {
Err = ERROR_INVALID_DATA;
goto clean0;
}
} while(cr == CR_BUFFER_SMALL);
if(!DevIdBufferLen) {
goto NoDups;
}
//
// Initialize the structure to be used during duplicate comparison callback.
//
CurDevInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
//
// We have retrieved a list of every device instance in the system--now
// do the comparison for each one that matches the class of the device
// being registered.
//
if(!CompareProc) {
//
// We are supposed to do the comparisons, so set up to do our default comparison.
//
if((cr = CM_Get_First_Log_Conf_Ex(&NewDevLogConfig,
DevInfoElem->DevInst,
BOOT_LOG_CONF,
pDeviceInfoSet->hMachine)) != CR_SUCCESS) {
//
// Ensure that our NewDevLogConfig handle is still NULL, so we won't try
// to free it.
//
NewDevLogConfig = (LOG_CONF)NULL;
if(cr == CR_INVALID_DEVINST) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
} else {
//
// The only value we should get here is CR_NO_MORE_LOG_CONF.
// In this case, there is no comparison data, so we assume there is
// no possibility of duplication.
//
goto NoDups;
}
}
if(CM_Get_Next_Res_Des_Ex(&NewDevResDes,
NewDevLogConfig,
ResType_ClassSpecific,
NULL,
0,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
//
// Ensure that our NewDevResDes is still NULL, so we won't try to free it.
//
NewDevResDes = (RES_DES)NULL;
//
// Since we can't retrieve the ResDes handle, assume there are no duplicates.
//
goto NoDups;
}
//
// Now retrieve the actual data for the ResDes.
//
do {
if((CM_Get_Res_Des_Data_Size_Ex(&DevCmpContext.CsResourceSize,
NewDevResDes,
0,
pDeviceInfoSet->hMachine) != CR_SUCCESS) ||
!DevCmpContext.CsResourceSize) {
//
// Can't find out the size of the data, or there is none--assume no dups.
//
goto NoDups;
}
if(DevCmpContext.NewDevCsResource = MyMalloc(DevCmpContext.CsResourceSize)) {
if((cr = CM_Get_Res_Des_Data_Ex(NewDevResDes,
DevCmpContext.NewDevCsResource,
DevCmpContext.CsResourceSize,
0,
pDeviceInfoSet->hMachine)) != CR_SUCCESS) {
if(cr == CR_BUFFER_SMALL) {
//
// Then someone increased the size of the resource data before we
// got a chance to read it. Free our buffer and try again.
//
MyFree(DevCmpContext.NewDevCsResource);
DevCmpContext.NewDevCsResource = NULL;
} else {
//
// Some other error occurred (highly unlikely). Assume no dups.
//
goto NoDups;
}
}
} else {
//
// not enough memory--this is bad enough for us to abort.
//
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
} while(cr != CR_SUCCESS);
//
// We have successfully retrieved the class-specific resource data for the new
// device's boot LogConfig. Now allocate a buffer of the same size to store the
// corresponding resource data for each device instance we're comparing against.
// We don't have to worry about devices whose resource data is larger, because
// CM_Get_Res_Des_Data_Ex will do a partial fill to a buffer that's not large enough
// to contain the entire structure. Since our default comparison only compares
// the PnP detect signature (i.e., it ignores the legacy data at the very end of
// the buffer, we're guaranteed that we have enough data to make the determination.
//
if(!(DevCmpContext.CurDevCsResource = MyMalloc(DevCmpContext.CsResourceSize))) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
CompareProc = pSetupDupDevCompare;
CompareContext = &DevCmpContext;
}
for(CurDevId = DevIdBuffer;
*CurDevId;
CurDevId += lstrlen(CurDevId) + 1) {
Err = pSetupOpenAndAddNewDevInfoElem(pDeviceInfoSet,
CurDevId,
TRUE,
&(DevInfoElem->ClassGuid),
pDeviceInfoSet->InstallParamBlock.hwndParent,
&CurDevInfoElem,
TRUE,
&AlreadyPresent,
FALSE,
0,
pDeviceInfoSet
);
if(Err == ERROR_NOT_ENOUGH_MEMORY) {
//
// Out-of-memory error is the only one bad enough to get us to abort.
//
goto clean0;
} else if(Err != NO_ERROR) {
//
// Just ignore this device instance, and move on to the next.
//
Err = NO_ERROR;
continue;
}
DevInfoDataFromDeviceInfoElement(pDeviceInfoSet, CurDevInfoElem, &CurDevInfoData);
//
// We now have the possible duplicate in our set. Call the comparison callback
// routine.
//
Err = CompareProc(DeviceInfoSet, DeviceInfoData, &CurDevInfoData, CompareContext);
//
// If the device instance was created temporarily for the comparison, then it
// may need to be destroyed. It should be destroyed if it wasn't a duplicate,
// or if the duplicate output parameter wasn't supplied.
//
if(!AlreadyPresent) {
if((Err != ERROR_DUPLICATE_FOUND) || !DupDeviceInfoData) {
SetupDiDeleteDeviceInfo(DeviceInfoSet, &CurDevInfoData);
}
}
if(Err != NO_ERROR) {
goto clean0;
}
}
}
NoDups:
//
// To turn this phantom device instance into a 'live' device instance, we simply call
// CM_Create_DevInst_Ex, which does the right thing (without reenumerating the whole
// hardware tree!).
//
if(CM_Get_Device_ID_Ex(DevInfoElem->DevInst,
DeviceInstanceId,
SIZECHARS(DeviceInstanceId),
0,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
//
// This should never happen!
//
Err = ERROR_NO_SUCH_DEVINST;
} else if(CM_Get_Parent_Ex(&ParentDevInst, DevInfoElem->DevInst, 0,pDeviceInfoSet->hMachine) != CR_SUCCESS) {
//
// This should never happen!
//
Err = ERROR_NO_SUCH_DEVINST;
} else if(CM_Create_DevInst_Ex(&(DevInfoElem->DevInst),
DeviceInstanceId,
ParentDevInst,
CM_CREATE_DEVINST_NORMAL |
CM_CREATE_DEVINST_DO_NOT_INSTALL,
pDeviceInfoSet->hMachine) == CR_SUCCESS) {
//
// Device is no longer a phantom!
//
DevInfoElem->DiElemFlags &= ~DIE_IS_PHANTOM;
} else {
//
// This should never happen!
//
Err = ERROR_NO_SUCH_DEVINST;
goto clean0;
}
DevInfoElem->DiElemFlags |= DIE_IS_REGISTERED;
clean0:
; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Access the following variables so the compiler will respect our statement
// ordering in the try clause.
//
DevIdBuffer = DevIdBuffer;
DevCmpContext.NewDevCsResource = DevCmpContext.NewDevCsResource;
DevCmpContext.CurDevCsResource = DevCmpContext.CurDevCsResource;
NewDevLogConfig = NewDevLogConfig;
NewDevResDes = NewDevResDes;
}
if(DevIdBuffer) {
MyFree(DevIdBuffer);
}
if(DevCmpContext.NewDevCsResource) {
MyFree(DevCmpContext.NewDevCsResource);
}
if(DevCmpContext.CurDevCsResource) {
MyFree(DevCmpContext.CurDevCsResource);
}
if(NewDevResDes) {
CM_Free_Res_Des_Handle(NewDevResDes);
}
if(NewDevLogConfig) {
CM_Free_Log_Conf_Handle(NewDevLogConfig);
}
if((Err == ERROR_DUPLICATE_FOUND) && DupDeviceInfoData) {
//
// The user supplied a buffer to receive the SP_DEVINFO_DATA
// structure for the duplicate.
//
try {
if(!(DevInfoDataFromDeviceInfoElement(pDeviceInfoSet,
CurDevInfoElem,
DupDeviceInfoData))) {
Err = ERROR_INVALID_USER_BUFFER;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_USER_BUFFER;
}
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
DWORD
pSetupOpenAndAddNewDevInfoElem(
IN PDEVICE_INFO_SET pDeviceInfoSet,
IN PCTSTR DeviceInstanceId,
IN BOOL AllowPhantom,
IN CONST GUID *ClassGuid, OPTIONAL
IN HWND hwndParent, OPTIONAL
OUT PDEVINFO_ELEM *DevInfoElem,
IN BOOL CheckIfAlreadyPresent,
OUT PBOOL AlreadyPresent, OPTIONAL
IN BOOL OpenExistingOnly,
IN ULONG CmLocateFlags,
IN PDEVICE_INFO_SET ContainingDeviceInfoSet
)
/*++
Routine Description:
This routine opens a DEVINST handle to an existing device instance, and
creates a new device information element for it. This element is added
to the specified device information set.
ASSUMES THAT THE CALLING ROUTINE HAS ALREADY ACQUIRED THE LOCK!
Arguments:
DeviceInfoSet - Device information set to add the new element to.
DeviceInstanceId - Supplies the name of the device instance to be opened.
AllowPhantom - Specifies whether or not phantom device instances should be
allowed. If this flag is not set, and the specified device instance is
not currently active, then the routine will fail with ERROR_NO_SUCH_DEVINST.
ClassGuid - Optionally, supplies the class that the specified device instance
must be in order to be added to the set. If the device instance is found
to be of some class other than the one specified, then the call will fail with
ERROR_CLASS_MISMATCH. If this parameter is not specified, then the only check
that will be done on the device's class is to make sure that it matches the
class of the set (if the set has an associated class).
hwndParent - Optionally, supplies the handle to the top level window for
UI relating to this element.
DevInfoElem - Optionally, supplies the address of the variable that
receives a pointer to the newly-allocated device information element.
CheckIfAlreadyPresent - Specifies whether this routine should check to see whether
the device instance is already in the specified devinfo set.
AlreadyPresent - Optionally, supplies the address of a boolean variable
that is set to indicate whether or not the specified device instance
was already in the device information set. If CheckIfAlreadyThere is FALSE,
then this parameter is ignored.
OpenExistingOnly - If this flag is non-zero, then only succeed if the device
information element is already in the set. If this flag is TRUE, then
the CheckIfAlreadyPresent flag must also be TRUE.
CmLocateFlags - Supplies additional flags to be passed to CM_Locate_DevInst.
ContainingDeviceInfoSet - Supplies a pointer to the device information set
structure with which this element is to be associated. This may be
different from the pDeviceInfoSet parameter if we're working against a
cloned devinfo set (i.e., to facilitate rollback).
Return Value:
If the function succeeds, the return value is NO_ERROR, otherwise the
ERROR_* code is returned.
Remarks:
Note that since new device information elements are always added at the end
of the existing list, the enumeration ordering is preserved, thus we don't
need to invalidate our enumeration hint.
--*/
{
CONFIGRET cr;
DEVINST DevInst;
DWORD Err, DiElemFlags;
GUID GuidBuffer;
if((cr = CM_Locate_DevInst_Ex(&DevInst,
(DEVINSTID)DeviceInstanceId,
CM_LOCATE_DEVINST_NORMAL | CmLocateFlags,
pDeviceInfoSet->hMachine)) == CR_SUCCESS) {
DiElemFlags = DIE_IS_REGISTERED;
} else {
if(cr == CR_INVALID_DEVICE_ID) {
return ERROR_INVALID_DEVINST_NAME;
} else if(!AllowPhantom) {
return ERROR_NO_SUCH_DEVINST;
}
//
// It could be that the device instance is present in the registry, but
// not currently 'live'. If this is the case, we'll be able to get a
// handle to it by locating it as a phantom device instance.
//
if(CM_Locate_DevInst_Ex(&DevInst,
(DEVINSTID)DeviceInstanceId,
CM_LOCATE_DEVINST_PHANTOM | CmLocateFlags,
pDeviceInfoSet->hMachine) != CR_SUCCESS) {
return ERROR_NO_SUCH_DEVINST;
}
DiElemFlags = DIE_IS_REGISTERED | DIE_IS_PHANTOM;
}
//
// If requested, search through the current list of device information elements
// to see if this element already exists.
//
if(CheckIfAlreadyPresent) {
if(*DevInfoElem = FindDevInfoByDevInst(pDeviceInfoSet, DevInst, NULL)) {
//
// Make sure that this device instance is of the proper class, if a class GUID
// filter was supplied.
//
if(ClassGuid && !IsEqualGUID(ClassGuid, &((*DevInfoElem)->ClassGuid))) {
return ERROR_CLASS_MISMATCH;
}
if(AlreadyPresent) {
*AlreadyPresent = TRUE;
}
return NO_ERROR;
} else if(AlreadyPresent) {
*AlreadyPresent = FALSE;
if(OpenExistingOnly) {
//
// The requested device information element isn't in the set,
// so we must fail the call.
//
return ERROR_NO_SUCH_DEVICE_INTERFACE;
}
}
}
//
// Retrieve the class GUID for this device instance.
//
if((Err = pSetupClassGuidFromDevInst(DevInst, pDeviceInfoSet->hMachine,&GuidBuffer)) != NO_ERROR) {
return Err;
}
//
// If a class GUID filter was specified, then make sure that it matches the
// class GUID for this device instance.
//
if(ClassGuid && !IsEqualGUID(ClassGuid, &GuidBuffer)) {
return ERROR_CLASS_MISMATCH;
}
return pSetupAddNewDeviceInfoElement(pDeviceInfoSet,
DevInst,
&GuidBuffer,
NULL,
hwndParent,
DiElemFlags,
ContainingDeviceInfoSet,
DevInfoElem
);
}
DWORD
pSetupDupDevCompare(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA NewDeviceData,
IN PSP_DEVINFO_DATA ExistingDeviceData,
IN PVOID CompareContext
)
/*++
Routine Description:
This routine is the default comparison routine for SetupDiRegisterDeviceInfo.
It is used to determine whether the new device (i.e., the one being registered) is
a duplicate of an existing device.
The current algorithm for duplicate detection is as follows:
Compare the BOOT_LOG_CONF logical configurations for the two devices. Two
resource types are used in this comparison--ResType_IO and ResType_ClassSpecific.
The IO ranges, if any, for the two devices will be compared to see if they're
identical. Also, if the devices have a class-specific resource, then the
CSD_ClassGuid, and the Plug&Play detect signature in CSD_Signature will be
binary-compared.
(lonnym): presently, the LogConfig only supports the class-specific resource,
so I/O resource comparison is not done.
Arguments:
DeviceInfoSet - Supplies the handle of the device information set containing both devices
being compared.
NewDeviceData - Supplies the address of the SP_DEVINFO_DATA for the device being registered.
ExistingDeviceData - Supplies the address of the SP_DEVINFO_DATA for the existing device with
which the new device is being compared.
CompareContext - Supplies the address of a context buffer used during the comparison. This
buffer is actually a DEFAULT_DEVCMP_CONTEXT structure, defined as follows:
typedef struct _DEFAULT_DEVCMP_CONTEXT {
PCS_RESOURCE NewDevCsResource;
PCS_RESOURCE CurDevCsResource;
ULONG CsResourceSize;
} DEFAULT_DEVCMP_CONTEXT, *PDEFAULT_DEVCMP_CONTEXT;
NewDevCsResource points to the class-specific resource buffer for the new device.
CurDevCsResource points to a working buffer that should be used to retrieve the
class-specific resource for the existing device.
CsResourceSize supplies the size in bytes of these two buffers (they're both the
same size).
Return Value:
If the two devices are not duplicates of each other, the return value is NO_ERROR.
If the two devices are duplicates of each other, the return value is ERROR_DUPLICATE_FOUND.
--*/
{
LOG_CONF ExistingDeviceLogConfig;
RES_DES ExistingDeviceResDes;
CONFIGRET cr;
PDEFAULT_DEVCMP_CONTEXT DevCmpContext;
PCS_DES NewCsDes, ExistingCsDes;
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
HMACHINE hMachine;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
hMachine = pDeviceInfoSet->hMachine;
UnlockDeviceInfoSet(pDeviceInfoSet);
//
// First, retrieve the boot LogConfig for the existing device.
//
if(CM_Get_First_Log_Conf_Ex(&ExistingDeviceLogConfig,
ExistingDeviceData->DevInst,
BOOT_LOG_CONF,
hMachine) != CR_SUCCESS) {
//
// Couldn't get the boot LogConfig--assume this device isn't a duplicate.
//
return NO_ERROR;
}
//
// Assume there are no duplicates.
//
Err = NO_ERROR;
//
// Now, retrieve the the ResDes handle for the class-specific resource.
//
if(CM_Get_Next_Res_Des_Ex(&ExistingDeviceResDes,
ExistingDeviceLogConfig,
ResType_ClassSpecific,
NULL,
0,
hMachine) != CR_SUCCESS) {
//
// Couldn't get the class-specific ResDes handle--assume this device isn't a duplicate
//
goto clean0;
}
//
// Now, retrieve the actual data associated with this ResDes. Note that we don't care if
// we get a CR_BUFFER_SMALL error, because we are guaranteed that we got back at least the
// amount of data that we have for the new device. That's all we need to do our comparison.
//
DevCmpContext = (PDEFAULT_DEVCMP_CONTEXT)CompareContext;
cr = CM_Get_Res_Des_Data_Ex(ExistingDeviceResDes,
DevCmpContext->CurDevCsResource,
DevCmpContext->CsResourceSize,
0,
hMachine);
if((cr == CR_SUCCESS) || (cr == CR_BUFFER_SMALL)) {
//
// We got _at least_ enough of the buffer to do the comparison.
//
NewCsDes = &(DevCmpContext->NewDevCsResource->CS_Header);
ExistingCsDes = &(DevCmpContext->CurDevCsResource->CS_Header);
//
// First, see if the Plug&Play detect signatures are both the same size.
//
if(NewCsDes->CSD_SignatureLength == ExistingCsDes->CSD_SignatureLength) {
//
// See if the class GUIDs are the same.
//
if(IsEqualGUID(&(NewCsDes->CSD_ClassGuid), &(ExistingCsDes->CSD_ClassGuid))) {
//
// Finally, see if the PnP detect signatures are identical
//
if(!memcmp(NewCsDes->CSD_Signature,
ExistingCsDes->CSD_Signature,
NewCsDes->CSD_SignatureLength)) {
//
// We have ourselves a duplicate!
//
Err = ERROR_DUPLICATE_FOUND;
}
}
}
}
CM_Free_Res_Des_Handle(ExistingDeviceResDes);
clean0:
CM_Free_Log_Conf_Handle(ExistingDeviceLogConfig);
return Err;
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiGetDeviceInstanceIdA(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
OUT PSTR DeviceInstanceId,
IN DWORD DeviceInstanceIdSize,
OUT PDWORD RequiredSize OPTIONAL
)
{
WCHAR deviceInstanceId[MAX_DEVICE_ID_LEN];
PSTR deviceInstanceIdA;
DWORD AnsiLength;
BOOL b;
DWORD rc;
DWORD requiredSize;
b = SetupDiGetDeviceInstanceIdW(
DeviceInfoSet,
DeviceInfoData,
deviceInstanceId,
MAX_DEVICE_ID_LEN,
&requiredSize
);
if(!b) {
return(FALSE);
}
rc = GetLastError();
if(deviceInstanceIdA = pSetupUnicodeToAnsi(deviceInstanceId)) {
AnsiLength = lstrlenA(deviceInstanceIdA) + 1;
if(RequiredSize) {
try {
*RequiredSize = AnsiLength;
} except(EXCEPTION_EXECUTE_HANDLER) {
rc = ERROR_INVALID_PARAMETER;
b = FALSE;
}
}
if(DeviceInstanceIdSize >= AnsiLength) {
if (FAILED(StringCchCopyA(DeviceInstanceId, DeviceInstanceIdSize, deviceInstanceIdA))) {
//
// caller's buffer invalid
//
rc = ERROR_INVALID_USER_BUFFER;
b = FALSE;
}
} else {
rc = ERROR_INSUFFICIENT_BUFFER;
b = FALSE;
}
MyFree(deviceInstanceIdA);
} else {
rc = ERROR_NOT_ENOUGH_MEMORY;
b = FALSE;
}
SetLastError(rc);
return(b);
}
BOOL
WINAPI
SetupDiGetDeviceInstanceId(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
OUT PTSTR DeviceInstanceId,
IN DWORD DeviceInstanceIdSize,
OUT PDWORD RequiredSize OPTIONAL
)
/*++
Routine Description:
This routine retrieves the device instance ID associated with a device
information element.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
the device information element whose ID is to be retrieved.
DeviceInfoData - Supplies a pointer to the SP_DEVINFO_DATA structure for
the device information element whose ID is to be retrieved.
DeviceInstanceId - Supplies the address of a character buffer that will
receive the ID for the specified device information element.
DeviceInstanceIdSize - Supplies the size, in characters, of the DeviceInstanceId
buffer.
RequiredSize - Optionally, supplies the address of a variable that receives the
number of characters required to store the device instance ID.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem;
CONFIGRET cr;
ULONG ulLen;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// Get a pointer to the element whose ID we are to retrieve.
//
if(!(DevInfoElem = FindAssociatedDevInfoElem(pDeviceInfoSet,
DeviceInfoData,
NULL))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// Find out how large the buffer needs to be. We always have to
// make this call first, because CM_Get_Device_ID_Ex doesn't return
// a CR_BUFFER_SMALL error if there isn't room for the terminating
// NULL.
//
if((cr = CM_Get_Device_ID_Size_Ex(&ulLen,
DevInfoElem->DevInst,
0,
pDeviceInfoSet->hMachine)) == CR_SUCCESS) {
//
// The size returned from CM_Get_Device_ID_Size doesn't include
// the terminating NULL.
//
ulLen++;
} else {
Err = (cr == CR_INVALID_DEVINST) ? ERROR_NO_SUCH_DEVINST
: ERROR_INVALID_PARAMETER;
goto clean0;
}
if(RequiredSize) {
*RequiredSize = ulLen;
}
if(DeviceInstanceIdSize < ulLen) {
Err = ERROR_INSUFFICIENT_BUFFER;
goto clean0;
}
//
// Now retrieve the ID.
//
if((cr = CM_Get_Device_ID_Ex(DevInfoElem->DevInst,
DeviceInstanceId,
DeviceInstanceIdSize,
0,
pDeviceInfoSet->hMachine)) != CR_SUCCESS) {
switch(cr) {
case CR_INVALID_POINTER :
Err = ERROR_INVALID_USER_BUFFER;
break;
default :
//
// Should never hit this!
//
Err = ERROR_INVALID_DATA;
}
}
clean0: ; // nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
DWORD
pSetupAddDeviceInterfaceToDevInfoElem(
IN PDEVICE_INFO_SET DeviceInfoSet,
IN PDEVINFO_ELEM DevInfoElem,
IN CONST GUID *InterfaceClassGuid,
IN PTSTR DeviceInterfaceName,
IN BOOL IsActive,
IN BOOL IsDefault,
IN BOOL StoreTruncateNode,
IN BOOL OpenExistingOnly,
OUT PDEVICE_INTERFACE_NODE *DeviceInterfaceNode OPTIONAL
)
/*++
Routine Description:
This routine adds the specified device interface onto a device information
element's list of device interfaces.
Arguments:
DeviceInfoSet - Supplies a pointer to the device information set
containing the specified element.
DevInfoElem - Supplies a pointer to the DEVINFO_ELEM structure whose
device interface list is being added to.
InterfaceClassGuid - Supplies a pointer to a GUID representing the class
that this device interface is a member of.
DeviceInterfaceName - Supplies the symbolic link name of the device interface
being added.
IsActive - Specifies whether or not the device interface is presently active.
IsDefault - Specifies whether or not the device interface is presently the
default device interface for this device interface class.
StoreTruncateNode - If non-zero, then store the address of this device
interface node (if newly-added) when this is the first such node added
to the device information elements device interface node list (i.e.,
the interface class list's DeviceInterfaceTruncateNode field is NULL).
OpenExistingOnly - If non-zero, then only succeed if the requested device
interface is already in the device information set.
DeviceInterfaceNode - Optionally, supplies the address of a device interface
node pointer to be filled in with the node created for this device interface.
Return Value:
If success, the return value is NO_ERROR.
If failure, the return value is ERROR_NOT_ENOUGH_MEMORY.
--*/
{
LONG GuidIndex;
PINTERFACE_CLASS_LIST InterfaceClassList;
PDEVICE_INTERFACE_NODE NewDeviceInterfaceNode, CurDeviceInterface, PrevDeviceInterface;
LONG SymLinkNameId;
//
// First, get a reference (i.e., pointer) to this interface class guid (create one
// if it's not already present for this set).
//
GuidIndex = AddOrGetGuidTableIndex(DeviceInfoSet, InterfaceClassGuid, TRUE);
if(GuidIndex == -1) {
return ERROR_NOT_ENOUGH_MEMORY;
}
//
// Now, get the interface class list for this class from the relevant
// devinfo element (again, we will create a new (empty) list if it doesn't
// already exist).
//
if(!(InterfaceClassList = AddOrGetInterfaceClassList(DeviceInfoSet,
DevInfoElem,
GuidIndex,
TRUE))) {
return ERROR_NOT_ENOUGH_MEMORY;
}
//
// Now we will add a new device interface node to this list (making sure
// that the node isn't already there).
//
SymLinkNameId = pStringTableAddString(DeviceInfoSet->StringTable,
DeviceInterfaceName,
STRTAB_CASE_INSENSITIVE | STRTAB_BUFFER_WRITEABLE,
NULL,
0
);
if(SymLinkNameId == -1) {
return ERROR_NOT_ENOUGH_MEMORY;
}
for(CurDeviceInterface = InterfaceClassList->DeviceInterfaceNode, PrevDeviceInterface = NULL;
CurDeviceInterface;
PrevDeviceInterface = CurDeviceInterface, CurDeviceInterface = CurDeviceInterface->Next) {
if(CurDeviceInterface->SymLinkName == SymLinkNameId) {
//
// The node is already in our list, we don't want to add it again.
// Update the flags for this device interface to reflect whether
// the device is presently active, and whether it is the default
// interface for this class.
//
CurDeviceInterface->Flags = (CurDeviceInterface->Flags & ~SPINT_ACTIVE) | (IsActive ? SPINT_ACTIVE : 0);
CurDeviceInterface->Flags = (CurDeviceInterface->Flags & ~SPINT_DEFAULT) | (IsDefault ? SPINT_DEFAULT : 0);
//
// Return this node to the caller.
//
if(DeviceInterfaceNode) {
*DeviceInterfaceNode = CurDeviceInterface;
}
return NO_ERROR;
}
}
//
// The device interface node wasn't already in our list--add it (unless
// we've been told not to)
//
if(OpenExistingOnly) {
return ERROR_NO_SUCH_DEVICE_INTERFACE;
}
if(!(NewDeviceInterfaceNode = MyMalloc(sizeof(DEVICE_INTERFACE_NODE)))) {
return ERROR_NOT_ENOUGH_MEMORY;
}
ZeroMemory(NewDeviceInterfaceNode, sizeof(DEVICE_INTERFACE_NODE));
NewDeviceInterfaceNode->SymLinkName = SymLinkNameId;
if(PrevDeviceInterface) {
PrevDeviceInterface->Next = NewDeviceInterfaceNode;
} else {
InterfaceClassList->DeviceInterfaceNode = NewDeviceInterfaceNode;
}
InterfaceClassList->DeviceInterfaceCount++;
//
// If this is the first device interface node added to this list, then
// remember it so we can truncate the list at this point if we later find
// that we need to rollback (because we encountered some error).
//
if(StoreTruncateNode && !InterfaceClassList->DeviceInterfaceTruncateNode) {
InterfaceClassList->DeviceInterfaceTruncateNode = NewDeviceInterfaceNode;
}
//
// Store the interface class GUID index in the node, so that we can easily
// determine the class of the node later.
//
NewDeviceInterfaceNode->GuidIndex = GuidIndex;
//
// Setup the flags for this device interface (these are the same flags that
// the caller sees in the SP_DEVICE_INTERFACE_DATA structure).
//
NewDeviceInterfaceNode->Flags = IsActive ? SPINT_ACTIVE : 0;
NewDeviceInterfaceNode->Flags |= IsDefault ? SPINT_DEFAULT : 0;
//
// Store a back-pointer in the device interface node, so that we can get
// back to the devinfo element that owns it (there are circumstances when
// we will be given a device interface data buffer outside of the context
// of any devinfo element).
//
NewDeviceInterfaceNode->OwningDevInfoElem = DevInfoElem;
if(DeviceInterfaceNode) {
*DeviceInterfaceNode = NewDeviceInterfaceNode;
}
return NO_ERROR;
}
BOOL
WINAPI
SetupDiEnumDeviceInterfaces(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData, OPTIONAL
IN CONST GUID *InterfaceClassGuid,
IN DWORD MemberIndex,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
)
/*++
Routine Description:
This API enumerates device interfaces of the specified class that are
contained in the devinfo set (optionally, filtered based on DeviceInfoData).
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
device interfaces to be enumerated.
DeviceInfoData - Optionally, supplies a pointer to a device information
element for whom device interfaces are to be enumerated.
InterfaceClassGuid - Supplies a pointer to the interface class GUID whose
members are to be enumerated.
MemberIndex - Supplies the zero-based index of the device interface to be
retrieved. If DeviceInfoData is specified, then this is relative to
all device interfaces of the specified class owned by that device
information element. If DeviceInfoData is not specified, then this
index is relative to all device interfaces contained in the device
information set.
DeviceInterfaceData - Supplies a pointer to a device interface data buffer
that receives information about the specified device interface. The
cbSize field of this structure must be filled in with
sizeof(SP_DEVICE_INTERFACE_DATA), or the buffer is considered invalid.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
To enumerate device interface members, an application should initially call
the SetupDiEnumDeviceInterfaces function with the MemberIndex parameter set
to zero. The application should then increment MemberIndex and call the
SetupDiEnumDeviceInterfaces function until there are no more values (i.e.,
the function fails, and GetLastError returns ERROR_NO_MORE_ITEMS).
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err, i;
PDEVINFO_ELEM DevInfoElem;
LONG InterfaceClassGuidIndex;
PINTERFACE_CLASS_LIST InterfaceClassList;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// Retrieve the index of this interface class GUID.
//
if((InterfaceClassGuidIndex = AddOrGetGuidTableIndex(pDeviceInfoSet,
InterfaceClassGuid,
FALSE)) == -1) {
Err = ERROR_NO_MORE_ITEMS;
goto clean0;
}
//
// Find the requested device interface.
//
if(DeviceInfoData) {
//
// Then we're enumerating only those device interfaces that are owned
// by a particular devinfo element.
//
if(!(DevInfoElem = FindAssociatedDevInfoElem(pDeviceInfoSet,
DeviceInfoData,
NULL))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
if(!(InterfaceClassList = AddOrGetInterfaceClassList(pDeviceInfoSet,
DevInfoElem,
InterfaceClassGuidIndex,
FALSE))
|| (MemberIndex >= InterfaceClassList->DeviceInterfaceCount))
{
Err = ERROR_NO_MORE_ITEMS;
goto clean0;
}
} else {
//
// We're enumerating across all devinfo elements. Find the appropriate devinfo
// element, and adjust the member index accordingly.
//
for(DevInfoElem = pDeviceInfoSet->DeviceInfoHead;
DevInfoElem;
DevInfoElem = DevInfoElem->Next) {
if(InterfaceClassList = AddOrGetInterfaceClassList(pDeviceInfoSet,
DevInfoElem,
InterfaceClassGuidIndex,
FALSE)) {
if(MemberIndex < InterfaceClassList->DeviceInterfaceCount) {
//
// We've found the devinfo element containing the device
// interface we're looking for.
//
break;
} else {
//
// The device interface we're looking for isn't associated with
// this devinfo element. Adjust our index to eliminate the
// device interfaces for this element, and continue searching.
//
MemberIndex -= InterfaceClassList->DeviceInterfaceCount;
}
}
}
if(!DevInfoElem) {
//
// Then the specified index was higher than the count of device
// interfaces in this devinfo set.
//
Err = ERROR_NO_MORE_ITEMS;
goto clean0;
}
}
//
// If we reach this point, we've found the devinfo element that contains the requested
// device interface, and we have a pointer to the relevant interface class list. Now
// all we need to do is retrieve the correct member of this list, and fill in the caller's
// device interface data buffer with the appropriate information.
//
DeviceInterfaceNode = InterfaceClassList->DeviceInterfaceNode;
for(i = 0; i < MemberIndex; i++) {
DeviceInterfaceNode = DeviceInterfaceNode->Next;
}
if(!DeviceInterfaceDataFromNode(DeviceInterfaceNode, InterfaceClassGuid, DeviceInterfaceData)) {
Err = ERROR_INVALID_USER_BUFFER;
}
clean0:
; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiGetDeviceInterfaceDetailA(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
OUT PSP_DEVICE_INTERFACE_DETAIL_DATA_A DeviceInterfaceDetailData, OPTIONAL
IN DWORD DeviceInterfaceDetailDataSize,
OUT PDWORD RequiredSize, OPTIONAL
OUT PSP_DEVINFO_DATA DeviceInfoData OPTIONAL
)
{
//
// Since the maximum length for both the symbolic link and refstring components
// of the device interface name is 255 characters (excluding NULL), the maximum
// length of the entire device interface name is 512 characters
// (255 + 255 + 1 backslash + 1 NULL character).
//
// Thus, we will retrieve the unicode form of this information using a maximally-
// sized buffer, then convert it to ANSI, and store it in the caller's buffer, if
// the caller's buffer is large enough.
//
BYTE UnicodeBuffer[offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA_W, DevicePath) + (512 * sizeof(WCHAR))];
PCHAR AnsiBuffer = NULL;
PSP_DEVICE_INTERFACE_DETAIL_DATA_W UnicodeDetailData;
DWORD rc, UnicodeRequiredSize, ReturnBufferRequiredSize;
int AnsiStringSize;
//
// Check parameters.
//
rc = NO_ERROR;
try {
if(DeviceInterfaceDetailData) {
//
// Check signature and make sure buffer is large enough
// to hold fixed part and at least a valid empty string.
//
if((DeviceInterfaceDetailData->cbSize != sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA_A))
|| (DeviceInterfaceDetailDataSize < (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA_A,DevicePath)+sizeof(CHAR)))) {
rc = ERROR_INVALID_USER_BUFFER;
}
} else {
//
// Doesn't want data, size has to be 0.
//
if(DeviceInterfaceDetailDataSize) {
rc = ERROR_INVALID_USER_BUFFER;
}
}
} except(EXCEPTION_EXECUTE_HANDLER) {
rc = ERROR_INVALID_USER_BUFFER;
}
if(rc != NO_ERROR) {
SetLastError(rc);
return FALSE;
}
UnicodeDetailData = (PSP_DEVICE_INTERFACE_DETAIL_DATA_W)UnicodeBuffer;
UnicodeDetailData->cbSize = sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA_W);
if(!SetupDiGetDeviceInterfaceDetailW(DeviceInfoSet,
DeviceInterfaceData,
UnicodeDetailData,
sizeof(UnicodeBuffer),
&UnicodeRequiredSize,
DeviceInfoData)) {
return FALSE;
}
//
// We successfully retrieved the (unicode) device interface details. Now convert it
// to ANSI, and store it in the caller's buffer.
//
UnicodeRequiredSize -= offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA_W, DevicePath);
UnicodeRequiredSize /= sizeof(WCHAR);
try {
AnsiBuffer = pSetupUnicodeToAnsi(UnicodeDetailData->DevicePath);
if(!AnsiBuffer) {
rc = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
AnsiStringSize = lstrlenA(AnsiBuffer)+1;
ReturnBufferRequiredSize = AnsiStringSize + offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA_A, DevicePath);
if(RequiredSize) {
*RequiredSize = ReturnBufferRequiredSize;
}
if(ReturnBufferRequiredSize > DeviceInterfaceDetailDataSize) {
rc = ERROR_INSUFFICIENT_BUFFER;
goto clean0;
}
//
// OK, so we've determined that the caller's buffer is big enough. Now, copy the
// ANSI data into their buffer.
//
CopyMemory(DeviceInterfaceDetailData->DevicePath,
AnsiBuffer,
AnsiStringSize
);
clean0:
; // nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
rc = ERROR_INVALID_USER_BUFFER;
}
if(AnsiBuffer) {
MyFree(AnsiBuffer);
}
SetLastError(rc);
return (rc == NO_ERROR);
}
BOOL
WINAPI
SetupDiGetDeviceInterfaceDetail(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
OUT PSP_DEVICE_INTERFACE_DETAIL_DATA DeviceInterfaceDetailData, OPTIONAL
IN DWORD DeviceInterfaceDetailDataSize,
OUT PDWORD RequiredSize, OPTIONAL
OUT PSP_DEVINFO_DATA DeviceInfoData OPTIONAL
)
/*++
Routine Description:
This routine retrieves details about a particular device interface (i.e., what
it's "name" is that you can do a CreateFile on).
Arguments:
DeviceInfoSet - Supplies a handle to a device information set containing
a device interface to retrieve details about.
DeviceInterfaceData - Supplies a device interface information structure
for which details are to be retrieved.
DeviceInterfaceDetailData - Optionally, supplies the address of a device
interface detail data structure that will receive additional information
about the specified device interface. If this parameter is not specified,
then DeviceInterfaceDetailDataSize must be zero (this would be done if the
caller was only interested in finding out how large of a buffer is required).
If this parameter is specified, the cbSize field of this structure must
be set to the size of the structure before calling this API. NOTE:
The 'size of the structure' on input means sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA).
Note that this is essentially just a signature and is entirely separate
from DeviceInterfaceDetailDataSize. See below.
DeviceInterfaceDetailDataSize - Supplies the size, in bytes, of the
DeviceInterfaceDetailData buffer. To be valid this buffer must be at least
offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR) bytes,
which allows storage of the fixed part of the structure and a single nul to
terminate an empty multi_sz. (Depending on structure alignment,
character width, and the data to be returned, this may actually be
smaller than sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA).
RequiredSize - Optionally, supplies the address of a variable that receives
the number of bytes required to store the detailed device interface
information. This value includes both the size of the structure itself,
and the additional number of bytes required for the variable-length
character buffer at the end of it that holds the device path.
DeviceInfoData - Optionally, supplies a pointer to a SP_DEVINFO_DATA structure
that will receive information about the device information element that
owns this device interface. Callers that only want to retrieve this parameter
may pass NULL for DeviceInterfaceDetailData, and pass 0 for
DeviceInterfaceDetailDataSize. Assuming the specified device interface is
valid, the API will fail, with GetLastError returning ERROR_INSUFFICIENT_BUFFER.
However, DeviceInfoData will have been correctly filled in with the
associated device information element.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode;
PCTSTR DevicePath;
DWORD DevicePathLength, BufferLengthNeeded;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// First, find the devinfo element that owns this device interface. This
// is used as a form of validation, and also may be needed later on, if the
// user supplied us with a DeviceInfoData buffer to be filled in.
//
if(!(DevInfoElem = FindDevInfoElemForDeviceInterface(pDeviceInfoSet, DeviceInterfaceData))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// The Reserved field contains a pointer to the underlying device interface node.
//
DeviceInterfaceNode = (PDEVICE_INTERFACE_NODE)(DeviceInterfaceData->Reserved);
DevicePath = pStringTableStringFromId(pDeviceInfoSet->StringTable,
DeviceInterfaceNode->SymLinkName
);
DevicePathLength = (lstrlen(DevicePath) + 1) * sizeof(TCHAR);
//
// Before attempting to store the device path in the caller's buffer, check to see
// whether they requested that the associated devinfo element be returned. If so,
// do that first.
//
if(DeviceInfoData) {
if(!(DevInfoDataFromDeviceInfoElement(pDeviceInfoSet,
DevInfoElem,
DeviceInfoData))) {
Err = ERROR_INVALID_USER_BUFFER;
goto clean0;
}
}
//
// Validate the caller's buffer.
//
if(DeviceInterfaceDetailData) {
if((DeviceInterfaceDetailDataSize <
(offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR))) ||
(DeviceInterfaceDetailData->cbSize != sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA))) {
Err = ERROR_INVALID_USER_BUFFER;
goto clean0;
}
} else if(DeviceInterfaceDetailDataSize) {
Err = ERROR_INVALID_USER_BUFFER;
goto clean0;
}
//
// Compute the buffer size required.
//
BufferLengthNeeded = offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + DevicePathLength;
if(RequiredSize) {
*RequiredSize = BufferLengthNeeded;
}
if(BufferLengthNeeded > DeviceInterfaceDetailDataSize) {
Err = ERROR_INSUFFICIENT_BUFFER;
goto clean0;
}
CopyMemory(DeviceInterfaceDetailData->DevicePath, DevicePath, DevicePathLength);
clean0: ; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiOpenDeviceInterfaceA(
IN HDEVINFO DeviceInfoSet,
IN PCSTR DevicePath,
IN DWORD OpenFlags,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData OPTIONAL
)
{
PCWSTR UnicodeDevicePath;
DWORD rc;
rc = pSetupCaptureAndConvertAnsiArg(DevicePath, &UnicodeDevicePath);
if(rc == NO_ERROR) {
rc = _SetupDiOpenDeviceInterface(DeviceInfoSet,
(PWSTR)UnicodeDevicePath,
OpenFlags,
DeviceInterfaceData
);
MyFree(UnicodeDevicePath);
}
SetLastError(rc);
return(rc == NO_ERROR);
}
BOOL
WINAPI
SetupDiOpenDeviceInterface(
IN HDEVINFO DeviceInfoSet,
IN PCTSTR DevicePath,
IN DWORD OpenFlags,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData OPTIONAL
)
/*++
Routine Description:
This routine opens up the device information element that exposes the
specified device interface (if it's not already in the device information
set), and then adds this device interface to the set.
Arguments:
DeviceInfoSet - Supplies a handle to a device information set into which this
new device interface element is to be opened.
NOTE: The class of the underlying device instance must match the class
of the set (or the set should have no associated class). If this is not
the case, the call will fail, and GetLastError will return ERROR_CLASS_MISMATCH.
DevicePath - Supplies the name of the device interface to be opened. This name
is a Win32 device path of the form "\\?\<DeviceInterfaceName>[\<RefString>]",
and is returned via a previous enumeration of device interface (i.e., via
SetupDiGetClassDevs(...DIGCF_DEVICEINTERFACE) or by notification via
RegisterDeviceNotification).
OpenFlags - Supplies flags controlling how the device interface element is
to be opened. May be a combination of the following values:
DIODI_NO_ADD - Only succeed the call (and optionally return the device
interface data) if the device interface already exists
in the device information set. This flag may be used to
get a device interface data context buffer back given a
device interface name, without causing that interface to
be opened if it's not already in the set.
This is useful, for example, when an app receives a
device interface removal notification. Such an app will
want to remove the corresponding device interface data
from the device information they're using as a container,
but they wouldn't want to open up a device interface
element not already in the set just so they can close it.
DeviceInterfaceData - Optionally, supplies a pointer to a device interface data
buffer that receives information about the specified device interface. The
cbSize field of this structure must be filled in with sizeof(SP_DEVICE_INTERFACE_DATA)
or the buffer is considered invalid.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
If the new device interface was successfully opened, but the user-supplied
DeviceInterfaceData buffer is invalid, this API will return FALSE, with
GetLastError returning ERROR_INVALID_USER_BUFFER. The device interface
element _will_ have been added as a new member of the set, however.
If the device interface already exists in the set, the flags will be updated
to reflect the current state of the device. Thus, for example, if a device
was not active when originally opened into the set, but has since become
active, this API may be used to 'refresh' the flags on that device interface
element, so that the SPINT_ACTIVE bit is once again in sync with reality.
Note that since new device information elements are always added at the end
of the existing list, the enumeration ordering is preserved, thus we don't
need to invalidate our enumeration hint.
--*/
{
PCTSTR WritableDevicePath;
DWORD rc;
rc = CaptureStringArg(DevicePath, &WritableDevicePath);
if(rc == NO_ERROR) {
rc = _SetupDiOpenDeviceInterface(DeviceInfoSet,
(PTSTR)WritableDevicePath,
OpenFlags,
DeviceInterfaceData
);
MyFree(WritableDevicePath);
}
SetLastError(rc);
return(rc == NO_ERROR);
}
DWORD
_SetupDiOpenDeviceInterface(
IN HDEVINFO DeviceInfoSet,
IN PTSTR DevicePath,
IN DWORD OpenFlags,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData OPTIONAL
)
/*++
Routine Description:
Worker routine for SetupDiOpenDeviceInterface(A|W). This is a separate routine
so that both A and W versions can capture their DevicePath argument into a
writable buffer, because we need this for adding the case-insensitive form to
the string table.
Arguments:
See SetupDiOpenDeviceInterface for details.
Return Value:
If the function succeeds, the return value is NO_ERROR. Otherwise, it is a
Win32 error code.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err, DevicePathLen;
PCTSTR p;
TCHAR InterfaceGuidString[GUID_STRING_LEN];
GUID InterfaceGuid;
HKEY hKey;
TCHAR DeviceInstanceId[MAX_DEVICE_ID_LEN];
PCTSTR MachineName;
BOOL DevInfoAlreadyPresent, IsActive, IsDefault;
PDEVINFO_ELEM DevInfoElem;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode = NULL;
if(OpenFlags & ~DIODI_NO_ADD) {
return ERROR_INVALID_FLAGS;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
return ERROR_INVALID_HANDLE;
}
Err = NO_ERROR;
hKey = INVALID_HANDLE_VALUE;
DevInfoElem = NULL;
try {
//
// Retrieve the interface class of this device. Since the device path is of
// the form "\\?\MungedDevInstName#{InterfaceClassGuid}[\RefString]", we can
// retrieve the GUID from the name.
//
// NOTE: The algorithm about how this name is generated must be kept in sync
// with the kernel-mode implementation of IoRegisterDeviceClassAssocation, et. al.
//
DevicePathLen = lstrlen(DevicePath);
//
// Move past "\\?\" prefix (also allow "\\.\" until Memphis fixes their code)
//
if((DevicePathLen < 4) ||
(DevicePath[0] != TEXT('\\')) ||
(DevicePath[1] != TEXT('\\')) ||
((DevicePath[2] != TEXT('?')) && (DevicePath[2] != TEXT('.'))) ||
(DevicePath[3] != TEXT('\\')))
{
Err = ERROR_BAD_PATHNAME;
goto clean0;
}
p = _tcschr(&(DevicePath[4]), TEXT('\\'));
if(!p) {
//
// This name has no refstring--set the pointer to the end of the string
//
p = DevicePath + DevicePathLen;
}
//
// Make sure there are enough characters preceding the current position for a
// GUID to fit.
//
if(p < (DevicePath + 3 + GUID_STRING_LEN)) {
Err = ERROR_BAD_PATHNAME;
goto clean0;
}
MYVERIFY(SUCCEEDED(StringCchCopyN(InterfaceGuidString,
SIZECHARS(InterfaceGuidString),
p - (GUID_STRING_LEN - 1),
GUID_STRING_LEN - 1)));
if(pSetupGuidFromString(InterfaceGuidString, &InterfaceGuid) != NO_ERROR) {
Err = ERROR_BAD_PATHNAME;
goto clean0;
}
//
// Retrieve the name of the machine associated with this DeviceInfoSet.
//
if(pDeviceInfoSet->hMachine) {
MYASSERT(pDeviceInfoSet->MachineName != -1);
MachineName = pStringTableStringFromId(pDeviceInfoSet->StringTable, pDeviceInfoSet->MachineName);
} else {
MachineName = NULL;
}
//
// OK, now we know that we retrieved a valid GUID from an (apparently) valid device path.
// Go open up this device interface key under the DeviceClasses registry branch.
//
hKey = SetupDiOpenClassRegKeyEx(&InterfaceGuid,
KEY_READ,
DIOCR_INTERFACE,
MachineName,
NULL
);
if(hKey == INVALID_HANDLE_VALUE) {
Err = GetLastError();
goto clean0;
}
if(NO_ERROR != (Err = pSetupGetDevInstNameAndStatusForDeviceInterface(
hKey,
DevicePath,
DeviceInstanceId,
SIZECHARS(DeviceInstanceId),
&IsActive,
&IsDefault)))
{
goto clean0;
}
if(NO_ERROR != (Err = pSetupOpenAndAddNewDevInfoElem(pDeviceInfoSet,
DeviceInstanceId,
TRUE,
NULL,
NULL,
&DevInfoElem,
TRUE,
&DevInfoAlreadyPresent,
(OpenFlags & DIODI_NO_ADD),
0,
pDeviceInfoSet)))
{
//
// Make sure DevInfoElem is still NULL, so we won't try to delete it.
//
DevInfoElem = NULL;
goto clean0;
}
//
// Now that we've successfully opened up the device instance that 'owns'
// this device interface, add a new device interface node onto this
// devinfo element's list.
//
if((NO_ERROR == (Err = pSetupAddDeviceInterfaceToDevInfoElem(pDeviceInfoSet,
DevInfoElem,
&InterfaceGuid,
DevicePath,
IsActive,
IsDefault,
FALSE,
(OpenFlags & DIODI_NO_ADD),
&DeviceInterfaceNode)))
|| DevInfoAlreadyPresent)
{
//
// Either we successfully added the device interface or the owning devinfo element
// was already in the set. In either case, we want to reset the DevInfoElem pointer
// to NULL so we won't try to delete it from the set.
//
DevInfoElem = NULL;
}
clean0: ; // nothing to do
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Reference the following variables so the compiler will respect statement ordering
// w.r.t. assignment.
//
DevInfoElem = DevInfoElem;
hKey = hKey;
}
if(hKey != INVALID_HANDLE_VALUE) {
RegCloseKey(hKey);
}
if(Err != NO_ERROR) {
if(DevInfoElem) {
SP_DEVINFO_DATA DeviceInfoData;
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DevInfoDataFromDeviceInfoElement(pDeviceInfoSet, DevInfoElem, &DeviceInfoData);
SetupDiDeleteDeviceInfo(DeviceInfoSet, &DeviceInfoData);
}
} else if(DeviceInterfaceData) {
try {
if(!DeviceInterfaceDataFromNode(DeviceInterfaceNode, &InterfaceGuid, DeviceInterfaceData)) {
Err = ERROR_INVALID_USER_BUFFER;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_USER_BUFFER;
}
}
UnlockDeviceInfoSet(pDeviceInfoSet);
return Err;
}
BOOL
WINAPI
SetupDiGetDeviceInterfaceAlias(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
IN CONST GUID *AliasInterfaceClassGuid,
OUT PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
)
/*++
Routine Description:
This routine retrieves the device interface of a particular class that 'aliases'
the specified device interface. Two device interfaces are considered aliases of
each other if the following to criteria are met:
1. Both device interfaces are exposed by the same device instance.
2. Both device interfaces share the same RefString.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing the
device interface for which an alias is to be retrieved.
DeviceInterfaceData - Specifies the device interface whose alias is to be
retrieved.
AliasInterfaceClassGuid - Supplies a pointer to the GUID representing the interface
class for which the alias is to be retrieved.
AliasDeviceInterfaceData - Supplies a pointer to a device interface data buffer
that receives information about the alias device interface. The cbSize field
of this structure must be filled in with sizeof(SP_DEVICE_INTERFACE_DATA) or
the buffer is considered invalid.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
If the alias device interface was successfully opened, but the user-supplied
AliasDeviceInterfaceData buffer is invalid, this API will return FALSE, with
GetLastError returning ERROR_INVALID_USER_BUFFER. The alias device interface
element _will_ have been added as a new member of the set, however.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem, DevInfoElem2;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode;
PCTSTR DevicePath;
PTSTR AliasPath;
ULONG AliasPathLength;
CONFIGRET cr;
SP_DEVICE_INTERFACE_DATA TempInterfaceDevData;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
AliasPath = NULL;
try {
//
// First, find the devinfo element that owns this device interface (for validation).
//
if(!(DevInfoElem = FindDevInfoElemForDeviceInterface(pDeviceInfoSet, DeviceInterfaceData))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// The Reserved field contains a pointer to the underlying device interface node.
//
DeviceInterfaceNode = (PDEVICE_INTERFACE_NODE)(DeviceInterfaceData->Reserved);
//
// Get the device path for this device interface.
//
DevicePath = pStringTableStringFromId(pDeviceInfoSet->StringTable,
DeviceInterfaceNode->SymLinkName
);
//
// Choose a buffer size that should always be large enough (we know this is the
// case today, but since there is no defined maximum length on this path, we leave
// the capability for it to grow in the future).
//
AliasPathLength = 512;
while(TRUE) {
if(!(AliasPath = MyMalloc(AliasPathLength * sizeof(TCHAR)))) {
Err = ERROR_NOT_ENOUGH_MEMORY;
goto clean0;
}
//
// Now retrieve the name of this device interface's alias in the specified class.
//
cr = CM_Get_Device_Interface_Alias_Ex(DevicePath,
(LPGUID)AliasInterfaceClassGuid,
AliasPath,
&AliasPathLength,
0,
pDeviceInfoSet->hMachine);
if(cr == CR_SUCCESS) {
break;
} else {
//
// If our buffer was too small, then free it, and try again with a larger buffer.
//
if(cr == CR_BUFFER_SMALL) {
MyFree(AliasPath);
AliasPath = NULL;
} else {
Err = MapCrToSpError(cr, ERROR_NO_SUCH_DEVICE_INTERFACE);
goto clean0;
}
}
}
//
// If we get to here then we've successfully retrieved the alias name. Now open this
// device interface in our device information set.
//
TempInterfaceDevData.cbSize = sizeof(SP_DEVICE_INTERFACE_DATA);
if(!SetupDiOpenDeviceInterface(DeviceInfoSet,
AliasPath,
0,
&TempInterfaceDevData)) {
//
// This should never happen.
//
Err = GetLastError();
goto clean0;
}
//
// Retrieve the device information element for this alias device interface (this has to succeed).
//
DevInfoElem2 = FindDevInfoElemForDeviceInterface(pDeviceInfoSet, DeviceInterfaceData);
//
// Since these two device interfaces are aliases of each other, they'd better be owned by
// the same devinfo element!
//
MYASSERT(DevInfoElem == DevInfoElem2);
DeviceInterfaceNode = (PDEVICE_INTERFACE_NODE)(TempInterfaceDevData.Reserved);
clean0: ; // nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Reference the following variable so the compiler will respect our statement ordering
// w.r.t. assignment.
//
AliasPath = AliasPath;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
if(AliasPath) {
MyFree(AliasPath);
}
if(Err == NO_ERROR) {
try {
if(!DeviceInterfaceDataFromNode(DeviceInterfaceNode,
AliasInterfaceClassGuid,
AliasDeviceInterfaceData)) {
Err = ERROR_INVALID_USER_BUFFER;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_USER_BUFFER;
}
}
SetLastError(Err);
return(Err == NO_ERROR);
}
DWORD
pSetupGetDevInstNameAndStatusForDeviceInterface(
IN HKEY hKeyInterfaceClass,
IN PCTSTR DeviceInterfaceName,
OUT PTSTR OwningDevInstName, OPTIONAL
IN DWORD OwningDevInstNameSize,
OUT PBOOL IsActive, OPTIONAL
OUT PBOOL IsDefault OPTIONAL
)
/*++
Routine Description:
This routine retrieves the name of the device instance that exposes the specified
device interface and whether or not that device interface is currently active,
or is the default interface for the interface class to which it belongs.
Arguments:
hKeyInterfaceClass - Supplies a handle to the registry key for the interface class
of which this device interface is a member. E.g.,
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{InterfaceClassGuid}
DeviceInterfaceName - Supplies the name of the device interface.
OwningDevInstName - Optionally, supplies the address of a character buffer that
receives the name of the device instance that exposes this device interface.
This buffer should be at least MAX_DEVICE_ID_LEN characters long.
OwningDevInstNameSize - Supplies the size, in characters, of the OwningDevInstName
buffer.
IsActive - Optionally, supplies the address of a boolean variable that is set upon
return to indicate whether this interface is presently exposed.
IsDefault - Optionally, supplies the address of a boolean variable that is set upon
return to indicate whether this interface is presently the default
device interface for its device class.
Return Value:
If the function succeeds, the return value is NO_ERROR. Otherwise, it is a Win32
error code.
--*/
{
DWORD Err, DataBufferSize, RegDataType, TmpVal;
HKEY hKeyDeviceInterface, hKeyControl;
TCHAR InterfaceClassDefault[(2 * MAX_PATH) + 1]; // 2 max-sized regkey names + terminating NULL.
hKeyDeviceInterface = hKeyControl = INVALID_HANDLE_VALUE;
try {
DataBufferSize = OwningDevInstNameSize * sizeof(TCHAR);
Err = OpenDeviceInterfaceSubKey(hKeyInterfaceClass,
DeviceInterfaceName,
KEY_READ,
&hKeyDeviceInterface,
OwningDevInstName,
&DataBufferSize
);
if(Err != ERROR_SUCCESS) {
//
// Make sure the key handle is still invalid, so we'll know not to
// close it.
//
hKeyDeviceInterface = INVALID_HANDLE_VALUE;
goto clean0;
}
if(IsActive) {
//
// The user wants to find out whether this device interface is currently active.
// Check the 'Linked' value entry under the volatile 'Control' subkey to find
// this out.
//
*IsActive = FALSE;
if(ERROR_SUCCESS == RegOpenKeyEx(hKeyDeviceInterface,
pszControl,
0,
KEY_READ,
&hKeyControl)) {
DataBufferSize = sizeof(TmpVal);
if (ERROR_SUCCESS != RegQueryValueEx(hKeyControl,
pszLinked,
NULL,
NULL,
(PBYTE)&TmpVal,
&DataBufferSize)) {
*IsActive = FALSE;
} else {
*IsActive = TmpVal ? TRUE : FALSE;
}
}
}
if(IsDefault) {
//
// The user wants to find out whether this device interface is the
// default device interface for its device class. Check the
// 'Default' value entry under the interface class key to find this
// out.
//
*IsDefault = FALSE;
DataBufferSize = sizeof(InterfaceClassDefault);
if (ERROR_SUCCESS == RegQueryValueEx(hKeyInterfaceClass,
pszDefault,
NULL,
NULL,
(PBYTE)InterfaceClassDefault,
&DataBufferSize)) {
if (_tcsicmp(InterfaceClassDefault, DeviceInterfaceName) == 0) {
*IsDefault = TRUE;
}
}
}
clean0: ; // nothing to do
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Reference the following variables so the compiler will respect statement
// ordering w.r.t. assignment.
//
hKeyDeviceInterface = hKeyDeviceInterface;
hKeyControl = hKeyControl;
}
if(hKeyControl != INVALID_HANDLE_VALUE) {
RegCloseKey(hKeyControl);
}
if(hKeyDeviceInterface != INVALID_HANDLE_VALUE) {
RegCloseKey(hKeyDeviceInterface);
}
return Err;
}
//
// ANSI version
//
BOOL
WINAPI
SetupDiCreateDeviceInterfaceA(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
IN CONST GUID *InterfaceClassGuid,
IN PCSTR ReferenceString, OPTIONAL
IN DWORD CreationFlags,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData OPTIONAL
)
{
PCWSTR UnicodeRefString;
DWORD rc;
BOOL b;
b = FALSE;
if(ReferenceString) {
rc = pSetupCaptureAndConvertAnsiArg(ReferenceString, &UnicodeRefString);
} else {
UnicodeRefString = NULL;
rc = NO_ERROR;
}
if(rc == NO_ERROR) {
b = SetupDiCreateDeviceInterfaceW(DeviceInfoSet,
DeviceInfoData,
InterfaceClassGuid,
UnicodeRefString,
CreationFlags,
DeviceInterfaceData
);
rc = GetLastError();
if(UnicodeRefString) {
MyFree(UnicodeRefString);
}
}
SetLastError(rc);
return(b);
}
BOOL
WINAPI
SetupDiCreateDeviceInterface(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
IN CONST GUID *InterfaceClassGuid,
IN PCTSTR ReferenceString, OPTIONAL
IN DWORD CreationFlags,
OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData OPTIONAL
)
/*++
Routine Description:
This API creates (registers) a device interface for the specified device
information element, and adds this device interface to the device information
set.
Arguments:
DeviceInfoSet - Supplies a handle to a device information set containing the
device information element for which a new device interface is being added.
DeviceInfoData - Supplies the device information element for whom a device
interface is being added.
InterfaceClassGuid - Supplies the address of a GUID containing the class
for this new device interface.
ReferenceString - Optionally, supplies the reference string to be passed to the
driver when opening this device interface. This string becomes part of the
device interface's name (as an additional path component).
CreationFlags - Reserved for future use, must be set to 0.
DeviceInterfaceData - Optionally, supplies a pointer to a device interface data
buffer that receives information about the newly-created device interface.
The cbSize field of this structure must be filled in with sizeof(SP_DEVICE_INTERFACE_DATA)
or the buffer is considered invalid.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
If the new device interface was successfully created, but the user-supplied
DeviceInterfaceData buffer is invalid, this API will return FALSE, with
GetLastError returning ERROR_INVALID_USER_BUFFER. The device interface
element _will_ have been added as a new member of the set, however.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem;
TCHAR DeviceInterfaceName[(2 * MAX_PATH) + 1]; // 2 max-sized regkey names + terminating NULL.
ULONG DeviceInterfaceNameSize;
PCTSTR MachineName;
CONFIGRET cr;
BOOL IsActive, IsDefault;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode;
HKEY hKey;
if(CreationFlags) {
SetLastError(ERROR_INVALID_FLAGS);
return FALSE;
}
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
hKey = INVALID_HANDLE_VALUE;
try {
//
// Get a pointer to the device information element we're registering a
// device interface for.
//
if(!(DevInfoElem = FindAssociatedDevInfoElem(pDeviceInfoSet,
DeviceInfoData,
NULL))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// Register the device interface.
//
DeviceInterfaceNameSize = SIZECHARS(DeviceInterfaceName);
cr = CM_Register_Device_Interface_Ex(DevInfoElem->DevInst,
(LPGUID)InterfaceClassGuid,
ReferenceString,
DeviceInterfaceName,
&DeviceInterfaceNameSize,
0,
pDeviceInfoSet->hMachine);
if(cr != CR_SUCCESS) {
Err = MapCrToSpError(cr, ERROR_INVALID_DATA);
goto clean0;
}
//
// Retrieve the name of the machine associated with this DeviceInfoSet.
//
if(pDeviceInfoSet->hMachine) {
MYASSERT(pDeviceInfoSet->MachineName != -1);
MachineName = pStringTableStringFromId(pDeviceInfoSet->StringTable, pDeviceInfoSet->MachineName);
} else {
MachineName = NULL;
}
//
// This device interface might have already been registered, in which case it
// could already be active. We must check the 'Linked' registry value to see
// whether this device is active.
//
hKey = SetupDiOpenClassRegKeyEx(InterfaceClassGuid,
KEY_READ,
DIOCR_INTERFACE,
MachineName,
NULL
);
if(hKey != INVALID_HANDLE_VALUE) {
if(NO_ERROR != pSetupGetDevInstNameAndStatusForDeviceInterface(
hKey,
DeviceInterfaceName,
NULL,
0,
&IsActive,
&IsDefault))
{
//
// This shouldn't fail, but if it does, then just assume that the
// device interface's status is non-active, and it is not the default.
//
IsActive = FALSE;
IsDefault = FALSE;
}
} else {
//
// This should never happen--if it does, assume that the device
// interface isn't active.
//
IsActive = FALSE;
IsDefault = FALSE;
}
//
// The device interface was successfully registered, now add it to the list of
// device interfaces associated with this device information element.
//
Err = pSetupAddDeviceInterfaceToDevInfoElem(pDeviceInfoSet,
DevInfoElem,
InterfaceClassGuid,
DeviceInterfaceName,
IsActive,
IsDefault,
FALSE,
FALSE,
&DeviceInterfaceNode
);
clean0: ; // nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
//
// Reference the following variable so the compiler will respect statement
// ordering w.r.t. assignment.
//
hKey = hKey;
}
if(hKey != INVALID_HANDLE_VALUE) {
RegCloseKey(hKey);
}
if((Err == NO_ERROR) && DeviceInterfaceData) {
try {
if(!DeviceInterfaceDataFromNode(DeviceInterfaceNode, InterfaceClassGuid, DeviceInterfaceData)) {
Err = ERROR_INVALID_USER_BUFFER;
}
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_USER_BUFFER;
}
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return (Err == NO_ERROR);
}
BOOL
WINAPI
SetupDiDeleteDeviceInterfaceData(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
)
/*++
Routine Description:
This API deletes the specified device interface element from the device
information set. It _does not_ remove (unregister) the device interface
from the system (to do that, use SetupDiRemoveDeviceInterface).
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
device interface to be deleted.
DeviceInterfaceData - Specifies the device interface to be deleted.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
After a device interface is deleted, the device interface enumeration index
is invalid, and enumeration should be re-started at index 0.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode, CurDeviceInterfaceNode, PrevDeviceInterfaceNode;
PINTERFACE_CLASS_LIST InterfaceClassList;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// First, find the devinfo element that owns this device interface.
//
if(!(DevInfoElem = FindDevInfoElemForDeviceInterface(pDeviceInfoSet, DeviceInterfaceData))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// The Reserved field contains a pointer to the underlying device interface node.
//
DeviceInterfaceNode = (PDEVICE_INTERFACE_NODE)(DeviceInterfaceData->Reserved);
//
// Find this devinfo element's device interface list for this class.
//
if(!(InterfaceClassList = AddOrGetInterfaceClassList(pDeviceInfoSet,
DevInfoElem,
DeviceInterfaceNode->GuidIndex,
FALSE)))
{
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// Find this device interface node in the list of device interfaces for this device
// information element.
//
for(CurDeviceInterfaceNode = InterfaceClassList->DeviceInterfaceNode, PrevDeviceInterfaceNode = NULL;
CurDeviceInterfaceNode;
PrevDeviceInterfaceNode = CurDeviceInterfaceNode, CurDeviceInterfaceNode = CurDeviceInterfaceNode->Next)
{
if(CurDeviceInterfaceNode == DeviceInterfaceNode) {
break;
}
}
if(!CurDeviceInterfaceNode) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
MYASSERT(InterfaceClassList->DeviceInterfaceCount);
if(PrevDeviceInterfaceNode) {
PrevDeviceInterfaceNode->Next = CurDeviceInterfaceNode->Next;
} else {
InterfaceClassList->DeviceInterfaceNode = CurDeviceInterfaceNode->Next;
}
MyFree(DeviceInterfaceNode);
InterfaceClassList->DeviceInterfaceCount--;
clean0: ; // Nothing to do.
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
BOOL
WINAPI
SetupDiRemoveDeviceInterface(
IN HDEVINFO DeviceInfoSet,
IN OUT PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
)
/*++
Routine Description:
This API removes (unregisters) the specified device interface. It _does not_
delete the device interface element from the device information set (thus
enumeration is not affected). Instead, it marks the device interface element
as invalid, so that it cannot be used in any subsequent API calls except
SetupDiDeleteDeviceInterfaceData.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
device interface to be removed.
DeviceInterfaceData - Specifies the device interface to be removed. All
traces of this device will be removed from the registry.
Upon return, the Flags field of this structure will be updated to reflect
the new state of this device interface.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
Remarks:
There is no way to unregister a device interface while it is active. Thus,
this API will fail with ERROR_DEVICE_INTERFACE_ACTIVE in this case. If this
happens, you can do one of the following things in an attempt to remove the
device interface:
1. If there is some defined mechanism of communication to the device
interface/underlying device instance (e.g., an IOCTL) that causes the
driver to un-expose the device interface, then this method may be used,
and _then_ SetupDiRemoveDeviceInterface may be called.
2. If there is no mechanism as described in method (1), then the owning
device instance must be stopped (e.g., via SetupDiChangeState), which
will cause all device interfaces owned by that device instance to go
inactive. After that is done, then SetupDiRemoveDeviceInterface may
be called.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
DWORD Err;
PDEVINFO_ELEM DevInfoElem;
PDEVICE_INTERFACE_NODE DeviceInterfaceNode;
PCTSTR DevicePath, MachineName;
TCHAR InterfaceClassDefault[(2 * MAX_PATH) + 1]; // 2 max-sized regkey names + terminating NULL.
DWORD DataBufferSize;
HKEY hKeyInterfaceClass;
CONFIGRET cr;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR;
try {
//
// Get a pointer to the device information element for the specified
// device interface.
//
if(!(DevInfoElem = FindDevInfoElemForDeviceInterface(pDeviceInfoSet, DeviceInterfaceData))) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
//
// The Reserved field contains a pointer to the underlying device interface node.
//
DeviceInterfaceNode = (PDEVICE_INTERFACE_NODE)(DeviceInterfaceData->Reserved);
//
// OK, now open the device interface's root storage key.
//
DevicePath = pStringTableStringFromId(pDeviceInfoSet->StringTable,
DeviceInterfaceNode->SymLinkName
);
cr = CM_Unregister_Device_Interface_Ex(DevicePath, 0,pDeviceInfoSet->hMachine);
if(cr != CR_SUCCESS) {
switch(cr) {
case CR_NO_SUCH_DEVICE_INTERFACE :
//
// The device interface was deleted after it was enumerated/opened
// by this client. In this case, we'll go ahead and succeed this
// call.
//
break;
case CR_DEVICE_INTERFACE_ACTIVE :
Err = ERROR_DEVICE_INTERFACE_ACTIVE;
//
// If our SPINT_ACTIVE flag isn't set, then that means that the device
// wasn't active the last time we looked. Update our flag to indicate
// the device's new state.
//
DeviceInterfaceNode->Flags |= SPINT_ACTIVE;
goto clean1;
default :
Err = ERROR_INVALID_DATA;
goto clean0;
}
}
//
// The device interface was successfully removed. Now, mark the device
// interface node to reflect that it's now invalid.
//
DeviceInterfaceNode->Flags |= SPINT_REMOVED;
//
// Also, clear the SPINT_ACTIVE flag, in case it's set. It's possible that we thought
// the device was active, even though it was deactivated since the last time we looked.
//
DeviceInterfaceNode->Flags &= ~SPINT_ACTIVE;
//
// Retrieve the name of the machine associated with this DeviceInfoSet.
//
if(pDeviceInfoSet->hMachine) {
MYASSERT(pDeviceInfoSet->MachineName != -1);
MachineName = pStringTableStringFromId(pDeviceInfoSet->StringTable, pDeviceInfoSet->MachineName);
} else {
MachineName = NULL;
}
//
// Open this interface class key under the DeviceClasses registry
// branch.
//
hKeyInterfaceClass = SetupDiOpenClassRegKeyEx(&DeviceInterfaceData->InterfaceClassGuid,
KEY_READ | KEY_WRITE,
DIOCR_INTERFACE,
MachineName,
NULL);
if(hKeyInterfaceClass == INVALID_HANDLE_VALUE) {
goto clean1;
}
//
// Check if this interface is specified in the registry as the default
// device interface.
//
DataBufferSize = sizeof(InterfaceClassDefault);
if (ERROR_SUCCESS == RegQueryValueEx(hKeyInterfaceClass,
pszDefault,
NULL,
NULL,
(PBYTE)InterfaceClassDefault,
&DataBufferSize)) {
if (lstrcmpi(InterfaceClassDefault, DevicePath) == 0) {
//
// Delete the "Default" value under this interface class key.
//
if(ERROR_SUCCESS == RegDeleteValue(hKeyInterfaceClass,
pszDefault)) {
//
// This interface has been successfully removed as the
// "Default" interface for this class. Clear the
// SPINT_DEFAULT flag.
//
DeviceInterfaceNode->Flags &= ~SPINT_DEFAULT;
}
} else {
//
// This interface is not listed in the registry as the
// current default device interface for this class, so clear
// the SPINT_DEFAULT flag.
//
DeviceInterfaceNode->Flags &= ~SPINT_DEFAULT;
}
} else {
//
// We could not retrieve the "Default" value, but we should still
// make sure to clear the SPINT_DEFAULT flag on this interface.
//
DeviceInterfaceNode->Flags &= ~SPINT_DEFAULT;
}
RegCloseKey(hKeyInterfaceClass);
clean1:
//
// Finally, updated the flags in the caller-supplied buffer to indicate the new status
// of this device interface.
//
DeviceInterfaceData->Flags = DeviceInterfaceNode->Flags;
clean0: ; // nothing to do
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}
BOOL
pSetupDiSetDeviceInfoContext(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
IN DWORD Context
)
/*++
Routine Description:
This API stores a context value into the specified device information element
for later retrieval via pSetupDiGetDeviceInfoContext.
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
the device information element with which the context data is to be
associated.
DeviceInfoData - Supplies the address of a SP_DEVINFO_DATA structure indicating
which element the context data should be associated with.
Context - Specifies the data value to be stored for this device information element.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
--*/
{
return pSetupDiGetOrSetDeviceInfoContext(DeviceInfoSet,
DeviceInfoData,
Context,
NULL
);
}
BOOL
pSetupDiGetDeviceInfoContext(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
OUT PDWORD Context
)
/*++
Routine Description:
This API retrieves a context value from the specified device information element
(stored there via pSetupDiSetDeviceInfoContext).
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
the device information element with which the context data is associated.
DeviceInfoData - Supplies the address of a SP_DEVINFO_DATA structure indicating
which element the context data is associated with.
Context - Supplies the address of a variable that receives the context value
stored for the device information element in a prior call to
pSetupDiSetDeviceInfoContext. If no context data has previously been stored
for this element, this variable will be filled in with zero upon return.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
--*/
{
//
// If we let a NULL context pointer go through to the worker routine, it will
// think this is a 'set' instead of a 'get'. Make sure that doesn't happen.
//
if(!Context) {
SetLastError(ERROR_INVALID_PARAMETER);
return FALSE;
}
return pSetupDiGetOrSetDeviceInfoContext(DeviceInfoSet,
DeviceInfoData,
0, // ignored
Context
);
}
BOOL
pSetupDiGetOrSetDeviceInfoContext(
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
IN DWORD InContext,
OUT PDWORD OutContext OPTIONAL
)
/*++
Routine Description:
This API retrieves or sets a context value from the specified device information
element (stored there via pSetupDiSetDeviceInfoContext).
Arguments:
DeviceInfoSet - Supplies a handle to the device information set containing
the device information element with which the context data is associated.
DeviceInfoData - Supplies the address of a SP_DEVINFO_DATA structure indicating
which element the context data is associated with.
InContext - Specifies the data value to be stored for this device information element.
If OutContext is specified, then this is a 'get' instead of a 'set', and
this parameter is ignored.
OutContext - Optionally, supplies the address of a variable that receives the
context value stored for the device information element in a prior call to
pSetupDiSetDeviceInfoContext. If no context data has previously been stored
for this element, this variable will be filled in with zero upon return.
Return Value:
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error
information, call GetLastError.
--*/
{
PDEVICE_INFO_SET pDeviceInfoSet;
PDEVINFO_ELEM DevInfoElem;
DWORD Err;
if(!(pDeviceInfoSet = AccessDeviceInfoSet(DeviceInfoSet))) {
SetLastError(ERROR_INVALID_HANDLE);
return FALSE;
}
Err = NO_ERROR; // assume success.
try {
DevInfoElem = FindAssociatedDevInfoElem(pDeviceInfoSet,
DeviceInfoData,
NULL
);
if(!DevInfoElem) {
Err = ERROR_INVALID_PARAMETER;
goto clean0;
}
if(OutContext) {
//
// Store the context in the caller-supplied buffer.
//
*OutContext = DevInfoElem->Context;
} else {
//
// Set the context to the caller-supplied value.
//
DevInfoElem->Context = InContext;
}
clean0:
; // nothing to do
} except(EXCEPTION_EXECUTE_HANDLER) {
Err = ERROR_INVALID_PARAMETER;
}
UnlockDeviceInfoSet(pDeviceInfoSet);
SetLastError(Err);
return(Err == NO_ERROR);
}