WdfIoTargetSendInternalIoctlOthersSynchronously 함수(wdfiotarget.h)

아티클
07/16/2024

[KMDF에만 적용]

WdfIoTargetSendInternalIoctlOthersSynchronously 메서드는 비표준 내부 디바이스 제어 요청을 빌드하고 I/O 대상에 동기적으로 보냅니다.

통사론

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

매개 변수

[in] IoTarget

WdfDeviceGetIoTarget 또는 WdfIoTargetCreate이전 호출에서 가져온 로컬 또는 원격 I/O 대상 개체 또는 특수 I/O 대상이 제공하는 메서드에서 가져온 핸들입니다.

[in, optional] Request

프레임워크 요청 개체에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL수 있습니다. 자세한 내용은 다음 설명 섹션을 참조하세요.

[in] IoctlCode

I/O 대상이 지원하는 I/O 제어 코드(IOCTL)입니다.

[in, optional] OtherArg1

컨텍스트 정보를 포함하는 메모리 버퍼를 설명하는 WDF_MEMORY_DESCRIPTOR 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL수 있습니다.

[in, optional] OtherArg2

컨텍스트 정보를 포함하는 메모리 버퍼를 설명하는 WDF_MEMORY_DESCRIPTOR 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL수 있습니다.

[in, optional] OtherArg4

컨텍스트 정보를 포함하는 메모리 버퍼를 설명하는 WDF_MEMORY_DESCRIPTOR 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL수 있습니다.

[in, optional] RequestOptions

요청에 대한 옵션을 지정하는 호출자가 할당한 WDF_REQUEST_SEND_OPTIONS 구조체에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL수 있습니다. 자세한 내용은 다음 설명 섹션을 참조하세요.

[out, optional] BytesReturned

WdfRequestCompleteWithInformation호출하여 요청을 완료할 때 다른 드라이버가 제공하는 정보(예: 전송된 바이트 수)를 수신하는 위치에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL수 있습니다.

반환 값

작업이 성공하면 내부 디바이스 제어 요청이 완료된 후 WdfIoTargetSendInternalIoctlOthersSynchronously 반환을 반환 값은 요청의 완료 상태 값입니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	묘사
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 검색되었습니다.
STATUS_INFO_LENGTH_MISMATCH	RequestOptions 매개 변수가 가리키는 WDF_REQUEST_SEND_OPTIONS 구조체의 크기가 잘못되었습니다.
STATUS_INVALID_DEVICE_REQUEST	요청이 이미 I/O 대상에 큐에 대기되었습니다.
STATUS_INSUFFICIENT_RESOURCES	프레임워크에서 시스템 리소스(일반적으로 메모리)를 할당할 수 없습니다.
STATUS_IO_TIMEOUT	드라이버에서 제한 시간 값을 제공했으며 할당된 시간 내에 요청이 완료되지 않았습니다.
STATUS_REQUEST_NOT_ACCEPTED	Request 매개 변수가 나타내는 I/O 요청 패킷(IRP)은 드라이버가 요청을 전달할 수 있는 충분한 IO_STACK_LOCATION 구조를 제공하지 않습니다.

이 메서드는다른 NTSTATUS 값을 반환할 수도 있습니다.

드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.

발언

비표준 내부 디바이스 제어 요청은 IOCTL 코드를 사용하여 수행할 작업을 식별하지만 요청은 다른 내부 디바이스 제어 요청에서 사용하는 표준 입력 및 출력 버퍼를 사용하지 않습니다. 상호 작용하는 드라이버 집합을 만드는 경우 이 드라이버 집합이 요청의 인수를 사용하는 방법을 정의할 수 있습니다. OtherArg1, OtherArg2및 OtherArg4.

프레임워크는 이러한 매개 변수를 Argument1, Argument2및 드라이버의 IO_STACK_LOCATION 구조에서 Other.Parameters 공용 구조체의 Argument4 멤버와 연결하므로 OtherArg3 매개 변수가 없습니다. 해당 공용 구조체의 Argument3 멤버는 IoctlCode 매개 변수에서 값을 받으므로 다른 드라이버 제공 값에는 사용할 수 없습니다.

WdfIoTargetSendInternalIoctlOthersSynchronously 메서드를 사용하여 비표준 내부 디바이스 제어 요청을 동기적으로 보냅니다. 내부 디바이스 제어 요청을 비동기적으로 보내려면 WdfIoTargetFormatRequestForInternalIoctlOthers사용하고 WdfRequestSend사용합니다.

내부 디바이스 제어 요청에 대한 자세한 내용은I/O 제어 코드 사용 참조하세요.

WdfIoTargetSendInternalIoctlOthersSynchously 메서드는 드라이버가 RequestOptions 매개 변수의 WDF_REQUEST_SEND_OPTIONS 구조에 시간 제한 값을 제공하지 않는 한 요청이 완료될 때까지 또는 오류가 검색되지 않는 한 반환되지 않습니다.

드라이버가 I/O 큐에서 받은 비표준 내부 디바이스 제어 요청을 전달하거나 새 요청을 만들고 보낼 수 있습니다. 두 경우 모두 프레임워크에는 요청 개체와 일부 컨텍스트 공간이 필요합니다.

드라이버가 I/O 큐에서 받은 비표준 내부 디바이스 제어 요청을 전달하려면 다음을 수행합니다.

WdfIoTargetSendInternalIoctlOthersSynchronously 메서드의 Request 매개 변수에 대해 수신된 요청의 핸들을 지정합니다.
WdfIoTargetSendInternalIoctlOthersSynchronously 메서드의 OtherArg1,OtherArg2및 기타Arg4 매개 변수를수신된 요청의 컨텍스트 정보를 사용합니다.
이러한 매개 변수 값을 가져오려면 드라이버는 WdfRequestGetParameters 호출하고 반환되는 WDF_REQUEST_PARAMETERS 구조체의 DeviceIoControl 멤버를 사용해야 합니다.

I/O 요청을 전달하는 방법에 대한 자세한 내용은전달 I/O 요청을 참조하세요.

드라이버는 수신된 I/O 요청을 I/O 대상으로 보내는 더 작은 요청으로 나누는 경우가 많으므로 드라이버는 새 요청을 만들 수 있습니다.

새 I/O 요청을 만들려면 다음을 수행합니다.

WdfIoTargetSendInternalIoctlOthersSynchronously 메서드의 Request 매개 변수에 대한 NULL 요청 핸들을 제공하거나 새 요청 개체를 만들고 해당 핸들을 제공합니다.
- NULL 요청 핸들을 제공하는 경우 프레임워크는 내부 요청 개체를 사용합니다. 이 기술은 사용하기는 간단하지만 드라이버는 요청을 취소할 수 없습니다.
- WdfRequestCreate 호출하여 하나 이상의 요청 개체를 만드는 경우 WdfRequestReuse호출하여 이러한 요청 개체를 다시 사용할 수 있습니다. 이 기술을 사용하면 드라이버의 EvtDriverDeviceAdd 콜백 함수가 디바이스에 대한 요청 개체를 미리 할당할 수 있습니다. 또한 필요한 경우 다른 드라이버 스레드가 WdfRequestCancelSentRequest 호출하여 요청을 취소할 수 있습니다.
드라이버가NULL이 아닌 또는 NULLRequest 매개 변수를 제공하는지 여부에 관계없이 드라이버에서NULLRequestOptions 매개 변수를 지정할 수 있습니다. 예를 들어 RequestOptions 매개 변수를 사용하여 제한 시간 값을 지정할 수 있습니다.
요청이 필요한 경우 WdfIoTargetSendInternalIoctlOthersSynchronously 메서드의 OtherArg1,OtherArg2및 OtherArg4 매개 변수에 대한 컨텍스트 공간을 제공합니다.
드라이버는 이 컨텍스트 공간을 로컬로 할당된 버퍼, WDFMEMORY 핸들 또는 MDL(메모리 설명자 목록)으로 지정할 수 있습니다. 가장 편리한 방법을 사용할 수 있습니다.

버퍼 공간을 지정하는 다음 기술을 사용할 수 있습니다.
- 로컬 버퍼를 제공합니다.
  WdfIoTargetSendInternalIoctlOthersSynchronously I/O 요청을 동기적으로 처리하므로 드라이버는 다음 코드 예제와 같이 호출 루틴에 로컬인 요청 버퍼를 만들 수 있습니다.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
```
- WDFMEMORY 핸들을 제공합니다.
  다음 코드 예제와 같이 WdfMemoryCreate 또는 WdfMemoryCreatePreallocated 호출하여 프레임워크 관리 메모리에 대한 핸들을 가져옵니다.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);
```
- MDL을 제공합니다.
  드라이버는 WdfRequestRetrieveInputWdmdl 호출하고 WdfRequestRetrieveOutputWdmMdl수신된 I/O 요청과 연결된 MDL을 가져올 수 있습니다.

I/O 요청이 완료된 후 상태 정보를 가져오는 방법에 대한 자세한 내용은 완료 정보 가져오기참조하세요.

WdfIoTargetSendInternalIoctlOthersSynchronously대한 자세한 내용은 일반 I/O 대상I/O 요청을 보내는 참조하세요.

I/O 대상에 대한 자세한 내용은 I/O 대상 사용참조하세요.

예제

다음 코드 예제에서는 IEEE 1394 IRB 구조를 초기화하고, 구조체의 주소를 사용하여 WDF_MEMORY_DESCRIPTOR 구조를 초기화한 다음, WdfIoTargetSendInternalIoctlOthersSynchronously호출합니다.

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           NULL,
                                                           NULL
                                                           );

요구 사항

요구	값
대상 플랫폼	보편적
최소 KMDF 버전	1.0
헤더	wdfiotarget.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조)
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf) , KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf)