WdfIoTargetFormatRequestForInternalIoctlOthers 함수(wdfiotarget.h)

2025-03-22

[KMDF에만 적용]

WdfIoTargetFormatRequestForInternalIoctlOthers 메서드는 I/O 대상에 대한 비표준 내부 디바이스 제어 요청을 빌드하지만 요청을 보내지 않습니다.

구문론

NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         OtherArg1,
  [in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
  [in, optional] WDFMEMORY         OtherArg2,
  [in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
  [in, optional] WDFMEMORY         OtherArg4,
  [in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);

매개 변수

[in] IoTarget

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

[in] Request

프레임워크 요청 개체에 대한 핸들입니다. 자세한 내용은 다음 설명 섹션을 참조하세요.

[in] IoctlCode

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

[in, optional] OtherArg1

프레임워크 메모리 개체에 대한 핸들입니다. 이 개체는 드라이버가 요청별 드라이버 정의 컨텍스트 정보에 사용하는 버퍼를 나타냅니다. 자세한 내용은 다음 설명 섹션을 참조하세요. 이 매개 변수는 선택 사항이며 NULL 수 있습니다.

[in, optional] OtherArg1Offset

선택적 바이트 오프셋 및 길이 값을 제공하는 호출자가 할당한 WDFMEMORY_OFFSET 구조체에 대한 포인터입니다. 드라이버는 이러한 값을 사용하여 OtherArg1지정된 컨텍스트 영역 세그먼트의 시작 주소와 길이를 지정할 수 있습니다. 이 매개 변수는 선택 사항이며 NULL 수 있습니다.

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

선택적 바이트 오프셋 및 길이 값을 제공하는 호출자가 할당한 WDFMEMORY_OFFSET 구조체에 대한 포인터입니다. 드라이버는 이러한 값을 사용하여 OtherArg2지정된 컨텍스트 영역 세그먼트의 시작 주소와 길이를 지정할 수 있습니다. 이 매개 변수는 선택 사항이며 NULL 수 있습니다.

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

선택적 바이트 오프셋 및 길이 값을 제공하는 호출자가 할당한 WDFMEMORY_OFFSET 구조체에 대한 포인터입니다. 드라이버는 이러한 값을 사용하여 OtherArg4지정된 컨텍스트 영역 세그먼트의 시작 주소와 길이를 지정할 수 있습니다. 이 매개 변수는 선택 사항이며 NULL 수 있습니다.

반환 값

WdfIoTargetFormatRequestForInternalIoctlOthers 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
파라미터 값이 잘못되었습니다	잘못된 매개 변수가 검색되었습니다.
STATUS_INVALID_DEVICE_REQUEST	전송 길이가 버퍼 길이보다 크거나 I/O 요청이 이미 I/O 대상에 대기 중입니다.
상태_불충분한_리소스	프레임워크에서 시스템 리소스(일반적으로 메모리)를 할당할 수 없습니다.
STATUS_REQUEST_NOT_ACCEPTED	Request 매개 변수가 나타내는 I/O 요청 패킷(IRP)은 드라이버가 요청을 전달할 수 있는 충분한 IO_STACK_LOCATION 구조를 제공하지 않습니다.

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

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

비고

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

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

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

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

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

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

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

새 요청 개체를 만들고 WdfIoTargetFormatRequestForInternalIoctlOthers 메서드의 Request 매개 변수에 대한 핸들을 제공합니다.
WdfRequestCreate 호출하여 하나 이상의 요청 개체를 미리 할당합니다. WdfRequestReuse호출하여 이러한 요청 개체를 다시 사용할 수 있습니다. 드라이버의 EvtDriverDeviceAdd 콜백 함수는 디바이스에 대한 요청 개체를 미리 할당할 수 있습니다.
요청이 필요한 경우 컨텍스트 버퍼를 제공하고 WdfIoTargetFormatRequestForInternalIoctlOthers 메서드의 OtherArg1, OtherArg2및 OtherArg4 매개 변수에 대한 버퍼 핸들을 제공합니다.
드라이버는 WDFMEMORY가 프레임워크 관리 메모리에 대해 처리할 때 이 버퍼 공간을 지정해야 합니다. WDFMEMORY 핸들을 가져오기 위해 드라이버는 WdfMemoryCreate 또는 WdfMemoryCreatePreallocated 호출합니다.

드라이버가 WdfIoTargetFormatRequestForInternalIoctlOthers 호출하여 디바이스 제어 요청의 형식을 지정한 후 드라이버는 WdfRequestSend 호출하여 요청을 I/O 대상으로 보내야 합니다(동기 또는 비동기적으로).

동일한 요청을 사용하는 WdfIoTargetFormatRequestForInternalIoctlOthers 대한 여러 호출은 추가 리소스 할당을 유발하지 않습니다. 따라서 WdfRequestCreate STATUS_INSUFFICIENT_RESOURCES 반환할 가능성을 줄이기 위해 드라이버의 EvtDriverDeviceAdd 콜백 함수는 WdfRequestCreate 호출하여 디바이스에 대한 하나 이상의 요청 개체를 미리 할당할 수 있습니다. 이후에 드라이버는 다시 사용(WdfRequestReuse호출), reformat(WdfIoTargetFormatRequestForInternalIoctlOthers호출)할 수 있습니다. WdfRequestCreate대한 이후 호출에서 STATUS_INSUFFICIENT_RESOURCES 반환 값을 위험하지 않고 각 요청 개체를 (WdfRequestSend호출)합니다. (드라이버가 매번 동일한 요청 형식 지정 메서드를 호출하지 않으면 추가 리소스가 할당될 수 있습니다.) 다시 사용된 요청 개체에 대한 WdfIoTargetFormatRequestForInternalIoctlOthers 대한 모든 후속 호출은 매개 변수 값이 변경되지 않으면 STATUS_SUCCESS 반환합니다.

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

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

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

예시

다음 코드 예제에서는 프레임워크 메모리 개체를 만들고, 메모리 개체에 포함된 버퍼를 가져오고, 버퍼를 초기화합니다. 그런 다음, 요청 형식을 지정하고, CompletionRoutine 콜백 함수를 설정하고, 요청을 I/O 대상으로 보냅니다.

PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(IRB),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIrb = WdfMemoryGetBuffer(
                          memory,
                          NULL
                          );

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

status = WdfIoTargetFormatRequestForInternalIoctlOthers(
                                                        IoTarget,
                                                        Request,
                                                        IOCTL_1394_CLASS,
                                                        memory,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL
                                                        );

if (!NT_SUCCESS(status)) {
    goto Done;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               MyRequestCompletion,
                               NULL
                               );

if (WdfRequestSend(
                   Request,
                   IoTarget,
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
}
else {
    status = STATUS_SUCCESS;
}

요구 사항

요구 사항	가치
대상 플랫폼	보편적
최소 KMDF 버전	1.0
헤더	wdfiotarget.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조)
IRQL	<=DISPATCH_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)