Fungsi WdfIoTargetFormatRequestForInternalIoctlOthers (wdfiotarget.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfIoTargetFormatRequestForInternalIoctlOthers membangun permintaan kontrol perangkat internal non-standar untuk target I/O tetapi tidak mengirim permintaan.

Sintaks

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
);

Parameter

[in] IoTarget

Handel ke objek target I/O lokal atau jarak jauh yang diperoleh dari panggilan sebelumnya ke WdfDeviceGetIoTarget atau WdfIoTargetCreate, atau dari metode yang disediakan target I/O khusus.

[in] Request

Handel ke objek permintaan kerangka kerja. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] IoctlCode

Kode kontrol I/O (IOCTL) yang didukung target I/O.

[in, optional] OtherArg1

Handel ke objek memori kerangka kerja. Objek ini mewakili buffer yang digunakan driver untuk informasi konteks khusus permintaan yang ditentukan driver. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini. Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] OtherArg1Offset

Penunjuk ke struktur WDFMEMORY_OFFSET yang dialokasikan penelepon yang memasok nilai offset dan panjang byte opsional. Driver dapat menggunakan nilai-nilai ini untuk menentukan alamat awal dan panjang segmen area konteks yang ditentukan oleh OtherArg1. Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

Penunjuk ke struktur WDFMEMORY_OFFSET yang dialokasikan penelepon yang memasok nilai offset dan panjang byte opsional. Driver dapat menggunakan nilai-nilai ini untuk menentukan alamat awal dan panjang segmen area konteks yang ditentukan oleh OtherArg2. Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

Penunjuk ke struktur WDFMEMORY_OFFSET yang dialokasikan penelepon yang memasok nilai offset dan panjang byte opsional. Driver dapat menggunakan nilai-nilai ini untuk menentukan alamat awal dan panjang segmen area konteks yang ditentukan oleh OtherArg4. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfIoTargetFormatRequestForInternalIoctlOthers mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INVALID_DEVICE_REQUEST	Panjang transfer lebih besar dari panjang buffer, atau permintaan I/O sudah diantrekan ke target I/O.
STATUS_INSUFFICIENT_RESOURCES	Kerangka kerja tidak dapat mengalokasikan sumber daya sistem (biasanya memori).
STATUS_REQUEST_NOT_ACCEPTED	Paket permintaan I/O (IRP) yang diwakili parameter Permintaan tidak menyediakan struktur IO_STACK_LOCATION yang cukup untuk memungkinkan driver meneruskan permintaan.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Gunakan metode WdfIoTargetFormatRequestForInternalIoctlOthers , diikuti dengan metode WdfRequestSend , untuk mengirim permintaan kontrol perangkat internal non-standar baik secara sinkron atau asinkron. Atau, gunakan metode WdfIoTargetSendInternalIoctlOthersSynchronously untuk mengirim permintaan kontrol perangkat internal non-standar secara sinkron.

Anda dapat meneruskan permintaan kontrol perangkat internal non-standar yang diterima driver Anda dalam antrean I/O, atau Anda dapat membuat dan mengirim permintaan baru. Dalam kedua kasus, kerangka kerja memerlukan objek permintaan dan beberapa ruang buffer.

Untuk meneruskan permintaan kontrol perangkat internal non-standar yang diterima driver Anda dalam antrean I/O:

Tentukan handel permintaan yang diterima untuk parameter Permintaan metode WdfIoTargetFormatRequestForInternalIoctlOthers.
Gunakan informasi konteks permintaan yang diterima untuk parameter WdfIoTargetFormatRequestForInternalIoctlOthers metode OtherArg1, OtherArg2, otherArg4 .
Untuk mendapatkan nilai parameter ini, driver harus memanggil WdfRequestGetParameters dan menggunakan anggota DeviceIoControl dari struktur WDF_REQUEST_PARAMETERS yang dikembalikan.

Untuk informasi selengkapnya tentang meneruskan permintaan I/O, lihat Meneruskan Permintaan I/O.

Driver sering membagi permintaan I/O yang diterima menjadi permintaan yang lebih kecil yang mereka kirim ke target I/O, sehingga driver Anda mungkin membuat permintaan baru.

Untuk membuat permintaan I/O baru:

Buat objek permintaan baru dan berikan handelnya untuk parameter Permintaan metode WdfIoTargetFormatRequestForInternalIoctlOthers.
Panggil WdfRequestCreate untuk melakukan pra-alokasi satu atau beberapa objek permintaan. Anda dapat menggunakan kembali objek permintaan ini dengan memanggil WdfRequestReuse. Fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat melakukan pra-alokasi objek permintaan untuk perangkat.
Berikan buffer konteks, jika permintaan memerlukannya, dan berikan pegangan buffer untuk parameter OtherArg1, OtherArg2, dan OtherArg4 metode WdfIoTargetFormatRequestForInternalIoctlOthers.
Driver Anda harus menentukan ruang buffer ini sebagai handel WDFMEMORY ke memori yang dikelola kerangka kerja. Untuk mendapatkan handel WDFMEMORY, driver memanggil WdfMemoryCreate atau WdfMemoryCreatePreallocated.

Setelah driver memanggil WdfIoTargetFormatRequestForInternalIoctlOthers untuk memformat permintaan kontrol perangkat, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O.

Beberapa panggilan ke WdfIoTargetFormatRequestForInternalIoctlOthers yang menggunakan permintaan yang sama tidak menyebabkan alokasi sumber daya tambahan. Oleh karena itu, untuk mengurangi kemungkinan WdfRequestCreate akan mengembalikan STATUS_INSUFFICIENT_RESOURCES, fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat memanggil WdfRequestCreate untuk melakukan pra-alokasi satu atau beberapa objek permintaan untuk perangkat. Driver kemudian dapat menggunakan kembali (panggil WdfRequestReuse), reformat (panggil WdfIoTargetFormatRequestForInternalIoctlOthers), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. (Jika driver tidak memanggil metode pemformatan permintaan yang sama setiap kali, sumber daya tambahan mungkin dialokasikan.) Semua panggilan berikutnya ke WdfIoTargetFormatRequestForInternalIoctlOthers untuk objek permintaan yang digunakan kembali akan mengembalikan STATUS_SUCCESS, jika nilai parameter tidak berubah.

Untuk informasi tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.

Untuk informasi selengkapnya tentang WdfIoTargetFormatRequestForInternalIoctlOthers, lihat Mengirim Permintaan I/O ke Target I/O Umum.

Untuk informasi selengkapnya tentang target I/O, lihat Menggunakan Target I/O.

Contoh

Contoh kode berikut membuat objek memori kerangka kerja, mendapatkan buffer yang dikandung objek memori, dan menginisialisasi buffer. Kemudian, contoh memformat permintaan, menetapkan fungsi panggilan balik CompletionRoutine , dan mengirim permintaan ke target 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;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfiotarget.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)