Fungsi SerCx2CustomReceiveCreate (sercx.h)

Artikel
08/07/2023

Metode SerCx2CustomReceiveCreate membuat objek penerima kustom, yang digunakan ekstensi kerangka kerja serial (SerCx2) versi 2 untuk membaca menerima data dari pengontrol serial melalui mekanisme transfer data kustom.

Sintaks

NTSTATUS SerCx2CustomReceiveCreate(
  [in]  WDFDEVICE                     Device,
  [in]  PSERCX2_CUSTOM_RECEIVE_CONFIG CustomReceiveConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out] SERCX2CUSTOMRECEIVE           *CustomReceive
);

Parameter

[in] Device

Handel WDFDEVICE ke objek perangkat kerangka kerja yang mewakili pengontrol serial. Driver pengontrol serial membuat objek ini dalam fungsi panggilan balik EvtDriverDeviceAdd . Untuk informasi selengkapnya, lihat SerCx2InitializeDevice.

[in] CustomReceiveConfig

Penunjuk ke struktur SERCX2_CUSTOM_RECEIVE_CONFIG . Sebelum memanggil metode ini, pemanggil harus memanggil fungsi SERCX2_CUSTOM_RECEIVE_CONFIG_INIT untuk menginisialisasi struktur. Struktur ini berisi pointer ke serangkaian rutinitas panggilan balik peristiwa yang diimplementasikan oleh driver pengontrol serial. SerCx2 memanggil fungsi-fungsi ini untuk melakukan transaksi penerimaan kustom.

[in] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang menjelaskan atribut untuk ditetapkan ke objek penerima kustom baru. Sebelum memanggil metode ini, pemanggil harus memanggil fungsi WDF_OBJECT_ATTRIBUTES_INIT untuk menginisialisasi struktur. Parameter ini bersifat opsional dan dapat ditentukan sebagai WDF_NO_OBJECT_ATTRIBUTES jika driver pengontrol serial tidak perlu menetapkan atribut ke objek. Untuk informasi selengkapnya, lihat Keterangan.

[out] CustomReceive

Penunjuk ke lokasi tempat metode ini menulis handel SERCX2CUSTOMRECEIVE ke objek penerima kustom yang baru dibuat. SerCx2 dan driver pengontrol serial menggunakan handel ini dalam panggilan berikutnya untuk merujuk ke objek ini.

Nilai kembali

Metode ini mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan mencakup kode status berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	Objek penerima kustom sudah ada dari panggilan SerCx2CustomReceiveCreate sebelumnya; atau objek system-DMA-receive ada dari panggilan SerCx2CustomReceiveCreate sebelumnya; atau objek transmisi DMA sistem ada dari panggilan SerCx2CustomTransmitCreate sebelumnya; atau SerCx2PioReceiveCreate belum dipanggil untuk membuat objek penerima PIO.
STATUS_INVALID_PARAMETER	Nilai parameter tidak valid.
STATUS_INFO_LENGTH_MISMATCH	NilaiUkuranKonfigurasi-> tidak sama dengan sizeof(SERCX2_CUSTOM_RECEIVE_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Sumber daya yang tersedia tidak cukup untuk membuat objek penerima kustom.

Keterangan

Metode ini dipanggil oleh driver pengontrol serial untuk membuat objek penerima kustom. SerCx2 menggunakan objek ini untuk melakukan transaksi penerimaan kustom, yang merupakan transaksi yang menggunakan mekanisme transfer data kustom untuk membaca data yang diterima oleh pengontrol serial.

Driver pengontrol serial harus berhasil memanggil metode SerCx2InitializeDevice dan SerCx2PioReceiveCreate sebelum memanggil SerCx2CustomReceiveCreate.

Sebelum memanggil SerCx2CustomReceiveCreate, driver pengontrol serial harus memanggil fungsi SERCX2_CUSTOM_RECEIVE_CONFIG_INIT untuk menginisialisasi struktur SERCX2_CUSTOM_RECEIVE_CONFIG yang ditunjukkan oleh CustomReceiveConfig. Fungsi ini mengatur anggota struktur berikut ke nol:

Penjajaran
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
Eksklusif

Jika perlu, driver pengontrol serial dapat mengatur salah satu anggota ini ke nilai bukan nol setelah fungsi inisialisasi kembali. Namun, untuk kenyamanan, SerCx2CustomReceiveCreate menggunakan nilai default berikut jika anggota ini nol:

Jika Perataan nol, SerCx2 mengatur nilai perataan data menjadi satu, yang berarti buffer baca dapat dimulai pada batas byte arbitrer dalam memori.
Jika MinimumTransactionLength adalah nol, SerCx2 mengatur panjang transaksi minimum ke satu byte.
Jika MaximumTransactionLength adalah nol, SerCx2 menetapkan panjang transaksi maksimum ke ((ULONG)-1).
Jika MinimumTransferUnit adalah nol, SerCx2 mengatur unit transfer minimum ke satu byte.
Jika Eksklusif adalah nol (FALSE), mode eksklusif dinonaktifkan.

Jika driver panggilan mengatur Eksklusif ke TRUE, anggota MinimumTransferUnit, Alignment, dan MinimumTransactionLength harus nol. Untuk informasi selengkapnya, lihat SERCX2_CUSTOM_RECEIVE_CONFIG.

Sebagai opsi, driver pengontrol serial dapat menggunakan parameter Atribut untuk membuat konteks untuk objek penerima kustom, dan untuk menyediakan pointer ke fungsi EvtCleanupCallback dan EvtDestroyCallback yang dipanggil untuk menyiapkan objek untuk dihapus. Untuk informasi selengkapnya, lihat WDF_OBJECT_ATTRIBUTES.

Jika parameter Atribut menunjuk ke struktur WDF_OBJECT_ATTRIBUTES , pemanggil tidak boleh menimpa nilai yang ditulis fungsi inisialisasi WDF_OBJECT_ATTRIBUTES_INIT ke anggota ParentObject, ExecutionLevel, dan SynchronizationScope dari struktur ini.

Untuk informasi selengkapnya tentang membuat objek penerima kustom, lihat SERCX2CUSTOMRECEIVE. Untuk informasi selengkapnya tentang transaksi penerima kustom, lihat SerCx2 Custom-Receive Transactions.