PcAddAdapterDevice 함수(portcls.h)
PcAddAdapterDevice 함수는 어댑터 디바이스를 WDM 디바이스 스택에 추가합니다.
구문
PORTCLASSAPI NTSTATUS PcAddAdapterDevice(
[in] PDRIVER_OBJECT DriverObject,
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] PCPFNSTARTDEVICE StartDevice,
[in] ULONG MaxObjects,
[in] ULONG DeviceExtensionSize
);
매개 변수
[in] DriverObject
드라이버 개체에 대한 포인터입니다. 이 포인터는 어댑터의 AddDevice 처리기에 매개 변수로 전달됩니다. 드라이버 개체는 DRIVER_OBJECT 형식의 시스템 구조입니다.
[in] PhysicalDeviceObject
디바이스의 PDO(물리적 디바이스 개체)에 대한 포인터입니다. PortCls는 이 포인터를 어댑터의 AddDevice 처리기에 호출 매개 변수로 전달합니다. PDO는 DEVICE_OBJECT 형식의 시스템 구조입니다.
[in] StartDevice
디바이스를 시작하기 위해 운영 체제에서 호출하는 함수에 대한 포인터입니다. 자세한 내용은 다음 설명 섹션을 참조 하세요 .
[in] MaxObjects
PcRegisterSubdevice 호출로 등록할 최대 하위 서비스 수를 지정합니다. 이 개수는 어댑터 드라이버가 인스턴스화할 수 있는 미니포트 개체의 총 수로 상한을 설정합니다.
[in] DeviceExtensionSize
디바이스 확장 크기를 지정합니다. 기본 크기에 0을 사용합니다. 사용자가 제공한 확장 크기에 대해서는 다음 설명 섹션을 참조하세요.
반환 값
PcAddAdapterDevice는 호출에 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 적절한 오류 코드를 반환합니다.
설명
이 함수는 오디오 어댑터 드라이버의 AddDevice 처리기가 수행해야 하는 대부분의 작업을 수행합니다. PcAddAdapterDevice 는 디바이스 개체를 만들고, 디바이스 컨텍스트를 초기화하고, 디바이스 개체를 디바이스 스택에 연결합니다.
어댑터 드라이버는 AddDevice 처리기에 대한 호출을 받으면 PcAddAdapterDevice를 호출합니다. 어댑터 드라이버는 일반적으로 PcInitializeAdapterDriver를 호출하여 AddDevice 처리기를 설치하지만 드라이버는 다른 수단으로 처리기를 설치할 수도 있습니다. PcAddAdapterDevice는 AddDevice 처리기에 전달된 PDO에 대한 FDO(기능 디바이스 개체)를 만듭니다.
DeviceExtensionSize 는 일반적으로 0입니다. 일부 어댑터 드라이버는 디바이스 확장에 추가 공간을 예약해야 할 수 있습니다. 이 경우 기본 크기인 PORT_CLASS_DEVICE_EXTENSION_SIZE보다 큰 DeviceExtensionSize 를 지정해야 합니다. 0보다 크고 PORT_CLASS_DEVICE_EXTENSION_SIZE 미만인 값은 불법입니다. 어댑터 드라이버는 오프셋 PORT_CLASS_DEVICE_EXTENSION_SIZE 후 디바이스 확장의 모든 부분을 자유롭게 사용할 수 있습니다. 또한 64비트 주소 지정이 있는 시스템의 오프셋 범위 32~63에서 32비트 주소 지정 및 바이트가 포함된 시스템에서 16~31의 오프셋 범위에서 바이트를 자유롭게 사용할 수 있습니다. 확장이 ULONG_PTR 배열로 간주되는 경우 어댑터 드라이버에서 4~7개의 배열 요소를 사용할 수 있습니다.
StartDevice 매개 변수는 헤더 파일 portcls.h가 다음으로 정의하는 PCPFNSTARTDEVICE 형식의 함수를 가리킵니다.
NTSTATUS
(*PCPFNSTARTDEVICE)(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PRESOURCELIST ResourceList
);
PcAddAdapterDevice 및 어댑터 드라이버의 디바이스 시작 및 AddDevice 루틴에 대한 자세한 내용은 시작 시퀀스를 참조하세요.
다음 예제 코드는 어댑터 드라이버가 DeviceExtensionSize 매개 변수를 사용하여 PortCls가 디바이스 컨텍스트에 할당하는 스토리지 블록 끝에 64바이트의 디바이스별 확장 데이터를 추가하는 방법을 보여 줍니다.
#define MY_EXTENSION_SIZE 64
NTSTATUS ntstatus = PcAddAdapterDevice(DriverObject, PhysicalDeviceObject,
MyStartDevice, MAX_MINIPORTS,
MY_EXTENSION_SIZE + PORT_CLASS_DEVICE_EXTENSION_SIZE);
위의 PcAddAdapterDevice 호출은 PcAddAdapterDevice에 전달된 마지막 매개 변수가 0이 아닌 경우를 제외하고 시작 시퀀스의 예제와 유사합니다.
그런 다음 어댑터 드라이버는 다음 코드 조각과 같이 디바이스별 확장 데이터에 액세스할 수 있습니다.
PVOID pMyExtensionData = (PVOID)((PCHAR)FunctionalDeviceObject->DeviceExtension +
PORT_CLASS_DEVICE_EXTENSION_SIZE);
Variable FunctionalDeviceObject 는 오디오 어댑터의 FDO에 대한 포인터이며 pMyExtensionData 는 확장 데이터에 대한 임시 포인터입니다. PCI 버스 드라이버에 속하는 PDO와 FDO를 혼동하지 않습니다. 이렇게 하면 PCI 버스 드라이버가 소유한 메모리가 손상되고 시스템이 충돌할 수 있으므로 어댑터 드라이버는 PDO에서 데이터를 수정해서는 안 됩니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000부터 사용할 수 있습니다. |
| 대상 플랫폼 | 유니버설 |
| 헤더 | portcls.h(Portcls.h 포함) |
| 라이브러리 | Portcls.lib |
| IRQL | PASSIVE_LEVEL |