PROTOCOL_CO_CREATE_VC fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

Fungsi ProtocolCoCreateVc adalah fungsi yang diperlukan yang mengalokasikan sumber daya yang diperlukan bagi manajer panggilan atau klien untuk mengaktifkan dan memelihara koneksi virtual (VC).

Catatan Anda harus mendeklarasikan fungsi dengan menggunakan jenis PROTOCOL_CO_CREATE_VC . Untuk informasi selengkapnya, lihat bagian Contoh berikut ini.

Sintaks

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

Parameter

[in] ProtocolAfContext

Menentukan handel ke area konteks yang dialokasikan protokol tempat manajer panggilan atau klien mempertahankan status per terbukanya. Manajer panggilan menyediakan handel ini dari fungsi ProtocolCmOpenAf-nya . Klien menyediakan handel ini ketika disebut NdisClOpenAddressFamilyEx dari fungsi ProtocolCoAfRegisterNotify .

[in] NdisVcHandle

Menentukan handel, yang disediakan oleh NDIS, yang secara unik mengidentifikasi koneksi virtual ini. Handel ini buram untuk driver protokol dan dicadangkan untuk penggunaan pustaka NDIS. Namun, manajer panggilan dan klien harus menyimpan handel ini untuk meneruskan panggilan berikutnya ke fungsi NdisCo/Cl/Cm/MCmXxx yang menyangkut VC ini.

[out] ProtocolVcContext

Menentukan handel ke area konteks yang disediakan protokol tempat manajer panggilan atau klien mempertahankan status tentang koneksi virtual ini.

Nilai kembali

ProtocolCoCreateVc mengembalikan status operasinya sebagai salah satu nilai berikut:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	Menunjukkan bahwa manajer panggilan atau klien berhasil mengalokasikan dan/atau menginisialisasi sumber daya yang diperlukan yang diperlukan untuk membangun dan memelihara koneksi virtual.
NDIS_STATUS_RESOURCES	Menunjukkan bahwa manajer panggilan atau klien tidak dapat mengalokasikan dan/atau menginisialisasi sumber dayanya untuk membuat dan memelihara koneksi virtual.
NDIS_STATUS_XXX	Menunjukkan bahwa manajer panggilan atau klien tidak dapat mengatur dirinya ke dalam status di mana ia dapat membuat koneksi virtual. Ini bisa menjadi nilai pengembalian kesalahan yang disebarkan dari rutinitas pustaka NDIS lain. Catatan Manajer panggilan atau klien tidak dapat mengembalikan NDIS_STATUS_PENDING dari fungsi ProtocolCoCreateVc mereka. Mengembalikan tertunda akan membuat koneksi virtual ini tidak dapat digunakan dan pustaka NDIS akan memanggil klien atau manajer panggilan untuk menghapusnya.

Keterangan

Fungsi ProtocolCoCreateVc dari manajer panggilan atau klien dipanggil setiap kali klien atau manajer panggilan yang sesuai, masing-masing memanggil NdisCoCreateVc. Klien memulai pembuatan VC dalam proses menyiapkan panggilan keluar mereka sebelum mereka memanggil NdisClMakeCall. Manajer panggilan memulai pembuatan VC dalam proses memberi tahu kliennya bahwa CM menerima penawaran panggilan masuk dari simpul jarak jauh yang diarahkan ke SAP yang sudah terdaftar di CM oleh klien tersebut sebelum panggilan CM NdisCmDispatchIncomingCall.

ProtocolCoCreateVc melakukan alokasi sumber daya dan struktur dinamis yang diperlukan manajer panggilan atau klien untuk melakukan operasi berikutnya pada VC yang akan diaktifkan. Sumber daya tersebut termasuk, tetapi tidak terbatas pada, buffer memori, struktur data, peristiwa, dan sumber daya serupa lainnya. Manajer panggilan dan klien juga harus menginisialisasi struktur per VC yang relevan yang akan mereka butuhkan saat panggilan dibuat.

Driver protokol berorientasi koneksi harus menyimpan handel untuk VC, yang ditentukan dalam NdisVcHandle, di area status per-VC mereka untuk digunakan dalam operasi mendatang pada koneksi virtual ini. NdisVcHandle adalah parameter yang diperlukan untuk NdisCoXxx, NdisCmXxx, dan/atau NdisClXxx yang kemudian memanggil protokol berorientasi koneksi.

Ketika manajer panggilan atau klien telah mengalokasikan memori untuk data per VC sendiri dan menginisialisasi statusnya, alamat struktur data ini harus diatur dalam handel sebelum mengembalikan kontrol ke NDIS. Untuk melakukan ini, dereferensi handel dan simpan penunjuk ke area data yang dialokasikan protokol sebagai nilai handel. Contohnya:

*ProtocolVcContext = SomeBuffer;

Jika ProtocolCoCreateVc tidak dapat mengalokasikan sumber daya yang diperlukan untuk melakukan operasi I/O jaringan berikutnya, ia harus membebaskan semua sumber daya yang dialokasikan untuk VC ini dan mengembalikan kontrol dengan status NDIS_STATUS_RESOURCES.

Jika ProtocolCoCreateVc telah menyelesaikan operasi yang diperlukan dan telah membuat manajer panggilan atau klien siap untuk melakukan inisialisasi panggilan untuk koneksi virtual ini, ProtocolCoCreateVc harus mengembalikan kontrol secepat mungkin dengan status NDIS_STATUS_SUCCESS.

Panggilan ke ProtocolCoCreateVc bersifat sinkron secara inheren. Artinya, ProtocolCoCreateVctidak dapat mengembalikan NDIS_STATUS_PENDING.

Setelah fungsi ProtocolCoCreateVc manajer panggilan mengembalikan kontrol, fungsi ProtocolCmMakeCall manajer panggilan akan dipanggil untuk membuat koneksi ke simpul jarak jauh. Manajer panggilan tidak boleh mengambil tindakan apa pun di ProtocolCmMakeCall yang benar-benar membuat panggilan karena ada kemungkinan VC akan dihancurkan sebelum panggilan dibuat karena kondisi kesalahan di komponen lain dari NDIS berorientasi koneksi.

Setelah fungsi ProtocolCoCreateVc klien mengembalikan kontrol, fungsi ProtocolClIncomingCall klien akan diberi tahu ketika permintaan yang dimulai dari jarak jauh untuk terhubung pada SAP yang sebelumnya didaftarkan oleh klien masuk melalui jaringan.

Contoh

Untuk menentukan fungsi ProtocolCoCreateVc , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan fungsi ProtocolCoCreateVc yang diberi nama "MyCoCreateVc", gunakan jenis PROTOCOL_CO_CREATE_VC seperti yang ditunjukkan dalam contoh kode ini:

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

Jenis fungsi PROTOCOL_CO_CREATE_VC ditentukan dalam file header Ndis.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi PROTOCOL_CO_CREATE_VC dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver NDIS.

Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Didukung untuk driver NDIS 6.0 dan NDIS 5.1 (lihat ProtocolCoCreateVc (NDIS 5.1)) di Windows Vista. Didukung untuk driver NDIS 5.1 (lihat ProtocolCoCreateVc (NDIS 5.1)) di Windows XP.
Target Platform	Windows
Header	ndis.h (termasuk Ndis.h)
IRQL	<= DISPATCH_LEVEL