SwDeviceCreate 함수(swdevice.h)

  • 아티클

소프트웨어 디바이스의 열거를 시작합니다.

구문

HRESULT SwDeviceCreate(
  [in]           PCWSTR                      pszEnumeratorName,
  [in]           PCWSTR                      pszParentDeviceInstance,
  [in]           const SW_DEVICE_CREATE_INFO *pCreateInfo,
  [in]           ULONG                       cPropertyCount,
  [in, optional] const DEVPROPERTY           *pProperties,
  [in]           SW_DEVICE_CREATE_CALLBACK   pCallback,
  [in, optional] PVOID                       pContext,
  [out]          PHSWDEVICE                  phSwDevice
);

매개 변수

[in] pszEnumeratorName

소프트웨어 디바이스의 열거자 이름을 지정하는 문자열입니다. 디바이스를 열거하는 구성 요소를 나타내는 이름을 선택합니다.

[in] pszParentDeviceInstance

소프트웨어 디바이스의 부모인 디바이스의 디바이스 instance ID를 지정하는 문자열입니다.

HTREE\ROOT\0일 수 있지만 루트 디바이스의 자식을 최소한으로 유지하는 것이 좋습니다. 또한 소프트웨어 디바이스의 기본 설정 부모는 소프트웨어 디바이스가 기능을 확장하는 실제 디바이스가 되는 것이 좋습니다. 소프트웨어 디바이스에 이러한 자연 부모가 없는 경우 구성 요소가 열거할 모든 소프트웨어 디바이스를 수집할 수 있는 루트의 자식으로 디바이스를 만듭니다. 그런 다음 실제 소프트웨어 디바이스를 이 디바이스 그룹화 노드의 자식으로 열거합니다. 이렇게 하면 루트 디바이스의 자식이 관리 가능한 수로 유지됩니다.

[in] pCreateInfo

PnP가 디바이스를 만드는 데 사용하는 정보를 설명하는 SW_DEVICE_CREATE_INFO 구조체에 대한 포인터입니다.

[in] cPropertyCount

pProperties 배열의 DEVPROPERTY 구조체 수입니다.

[in, optional] pProperties

DEVPROPERTY 구조체의 선택적 배열입니다. 이러한 속성은 디바이스를 만든 후 디바이스가 생성되었다는 알림이 전송되기 전에 디바이스에서 설정됩니다. 자세한 내용은 비고를 참조하세요. 이 포인터는 NULL일 수 있습니다.

[in] pCallback

PnP가 디바이스를 열거한 후 운영 체제에서 호출하는 SW_DEVICE_CREATE_CALLBACK 콜백 함수입니다.

[in, optional] pContext

운영 체제가 콜백 함수에 전달하는 선택적 클라이언트 컨텍스트입니다. 이 포인터는 NULL일 수 있습니다.

[out] phSwDevice

디바이스를 나타내는 HSWDEVICE 핸들을 수신하는 변수에 대한 포인터입니다. 클라이언트 앱이 PnP에서 디바이스를 제거하려고 하면 SwDeviceClose 를 호출하여 이 핸들을 닫습니다.


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

반환 값

디바이스 열거가 성공적으로 시작된 경우 S_OK 반환됩니다. 디바이스가 성공적으로 열거되었음을 의미하지는 않습니다. SW_DEVICE_CREATE_CALLBACK 콜백 함수의 CreateResult 매개 변수를 확인하여 디바이스가 성공적으로 열거되었는지 확인합니다.

설명

SwDeviceCreate 는 디바이스를 나타내는 핸들을 반환합니다. 이 핸들이 닫힌 후 PnP는 디바이스를 제거합니다.

소프트웨어 디바이스의 열거를 시작하려면 호출 프로세스에 관리자 액세스 권한이 있어야 합니다.

PnP는 소프트웨어 디바이스의 디바이스 instance ID를 "SWD< pszEnumeratorName>< pszInstanceId>"이지만 이 문자열이 변경되거나 PnP가 이름을 데코레이트할 수 있습니다. 항상 콜백 함수에서 디바이스 instance ID를 가져옵니다.

SwDeviceCreate 호출의 일부로 설정된 속성과 SwDevicePropertySet을 호출하여 나중에 설정되는 속성 간에는 미묘한 차이가 있습니다. SwDeviceCreate의 일부로 설정된 속성은 메모리에 저장됩니다. 디바이스가 제거되거나 null 드라이버가 속성 저장소를 초기화하면 PnP가 디바이스를 다시 열거할 때 소프트웨어 디바이스 API 기능에 의해 이러한 속성이 다시 기록됩니다. 이는 모두 클라이언트에 투명합니다. 열거 후 SwDevicePropertySet 을 사용하여 설정된 속성은 메모리에 유지되지 않습니다. 그러나 SwDeviceCreate를 사용하여 속성을 설정하는 경우 SwDevicePropertySet을 사용하여 값을 업데이트할 수 있으며 이 업데이트는 메모리 내 값과 지속형 저장소에 적용됩니다.

가능한 경우 모든 속성을 SwDeviceCreate 호출의 일부로 지정하고 SwDeviceCreate를 호출할 때마다 이러한 속성을 지정하는 것이 좋습니다.

참고 운영 체제는 SwDeviceCreate 호출이 반환되기 전에 SW_DEVICE_CREATE_CALLBACK 호출할 수 있습니다. 이러한 이유로 디바이스의 소프트웨어 디바이스 핸들은 콜백 함수에 대한 매개 변수로 제공됩니다.
 
당시에 존재하지 않는 부모의 자식으로 소프트웨어 디바이스를 만들 수 있습니다. PnP는 부모가 있는 후에 소프트웨어 디바이스를 열거합니다.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 8
지원되는 최소 서버 Windows Server 2012
대상 플랫폼 유니버설
헤더 swdevice.h
라이브러리 Swdevice.lib; Windows 10 OneCoreUAP.lib
DLL Cfgmgr32.dll

추가 정보

SW_DEVICE_CREATE_CALLBACK