PROTOCOL_CM_REG_SAP fungsi panggilan balik (ndis.h)

Artikel
08/07/2023

Fungsi ProtocolCmRegisterSap adalah fungsi yang diperlukan yang dipanggil oleh NDIS untuk meminta agar manajer panggilan mendaftarkan SAP (titik akses layanan) atas nama klien berorientasi koneksi.

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

Sintaks

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

Parameter

[in] CallMgrAfContext

Menentukan handel ke area konteks yang dialokasikan manajer panggilan tempat manajer panggilan mempertahankan status AF per terbukanya. Manajer panggilan menyediakan handel ini ke NDIS dari fungsi ProtocolCmOpenAf-nya .

[in] Sap

Arahkan ke struktur CO_SAP khusus media yang berisi SAP tertentu yang didaftarkan klien berorientasi koneksi.

[in] NdisSapHandle

Menentukan handel, yang disediakan oleh NDIS, yang secara unik mengidentifikasi SAP ini. Handel ini buram untuk manajer panggilan dan dicadangkan untuk penggunaan pustaka NDIS.

[out] CallMgrSapContext

Saat kembali, menentukan handel ke area konteks yang disediakan manajer panggilan di mana manajer panggilan mempertahankan status tentang SAP ini.

Nilai kembali

ProtocolCmRegisterSap mengembalikan status operasinya sebagai salah satu dari berikut ini:

Menampilkan kode	Deskripsi
NDIS_STATUS_SUCCESS	Menunjukkan bahwa pengelola panggilan berhasil mengalokasikan dan/atau menginisialisasi sumber daya yang diperlukan untuk mendaftar dan memelihara SAP. Selain itu, ini juga menunjukkan bahwa SAP berhasil didaftarkan seperti yang diperlukan oleh media jaringan yang didukung manajer panggilan.
NDIS_STATUS_PENDING	Menunjukkan bahwa manajer panggilan akan menyelesaikan pemrosesan permintaan ini secara asinkron. Manajer panggilan harus memanggil NdisCmRegisterSapComplete ketika semua pemrosesan telah selesai untuk memberi sinyal NDIS bahwa pendaftaran selesai.
NDIS_STATUS_RESOURCES	Menunjukkan bahwa manajer panggilan tidak dapat mengalokasikan dan/atau menginisialisasi sumber dayanya yang diperlukan untuk mendaftarkan SAP atas nama klien berorientasi koneksi.
NDIS_STATUS_INVALID_DATA	Menunjukkan bahwa spesifikasi yang disediakan di Sap tidak valid atau tidak dapat didukung.
NDIS_STATUS_XXX	Menunjukkan bahwa manajer panggilan mengalami kesalahan dalam mencoba mendaftarkan SAP untuk klien berorientasi koneksi. Kode pengembalian sesuai dengan kesalahan dan dapat berupa kode pengembalian yang disebarluaskan dari fungsi pustaka NDIS lain.

Keterangan

ProtocolCmMakeCall berkomunikasi dengan perangkat kontrol jaringan atau agen khusus media lainnya, seperlunya, untuk mendaftarkan SAP, seperti yang ditentukan di Sap, di jaringan untuk klien berorientasi koneksi. Tindakan tersebut dapat mencakup, tetapi tidak terbatas pada berkomunikasi dengan beralih perangkat keras, berkomunikasi dengan stasiun kontrol jaringan, atau tindakan lain yang sesuai dengan media jaringan.

Jika manajer panggilan diperlukan untuk berkomunikasi dengan agen kontrol jaringan (dengan kata lain, sakelar jaringan) ia harus menggunakan koneksi virtual ke agen kontrol jaringan yang dibuatnya dalam fungsi ProtocolBindAdapterEx . Manajer panggilan mandiri berkomunikasi melalui driver miniport yang mendasar dengan memanggil NdisCoSendNetBufferLists. Driver Miniport dengan dukungan manajemen panggilan terintegrasi tidak pernah memanggil NdisCoSendNetBufferLists. Sebaliknya, mereka mengirimkan data langsung di seluruh jaringan.

Selain itu, ProtocolCmRegisterSap harus melakukan alokasi sumber daya dan struktur dinamis yang diperlukan manajer panggilan untuk mempertahankan informasi status tentang SAP atas nama klien berorientasi koneksi. Sumber daya tersebut termasuk, tetapi tidak terbatas pada, buffer memori, struktur data, peristiwa, dan sumber daya serupa lainnya. Manajer panggilan juga harus menginisialisasi sumber daya apa pun yang dialokasikan sebelum mengembalikan kontrol ke NDIS. Manajer panggilan harus menyimpan handel yang disediakan NDIS yang mengidentifikasi SAP, yang disediakan di NdisSapHandle, di area konteksnya untuk digunakan di masa mendatang.

Jika ProtocolCmRegisterSap akan mengembalikan NDIS_STATUS_SUCCESS, seharusnya, setelah mengalokasikan area status per SAP, atur alamat area status ini di CallMgrSapContext sebelum mengembalikan kontrol ke NDIS. Untuk melakukan ini, dereferensi CallMgrSapContext dan simpan pointer ke area data sebagai nilai handel. Contohnya:

*CallMgrSapContext = SomeBuffer ;

Jika SAP yang diberikan yang sudah didaftarkan oleh klien berorientasi koneksi lain, manajer panggilan harus gagal dalam permintaan dan mengembalikan NDIS_STATUS_INVALID_DATA.

Setelah manajer panggilan mendaftarkan SAP atas nama klien berorientasi koneksi, ia memberi tahu klien tentang penawaran panggilan masuk yang diarahkan ke SAP tersebut dengan memanggil NdisCmDispatchIncomingCall.

Contoh

Untuk menentukan fungsi ProtocolCmRegisterSap , 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 ProtocolCmRegisterSap yang diberi nama "MyCmRegisterSap", gunakan jenis PROTOCOL_CM_REG_SAP seperti yang ditunjukkan dalam contoh kode ini:

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

Kemudian, terapkan fungsi Anda sebagai berikut:

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

Jenis fungsi PROTOCOL_CM_REG_SAP didefinisikan 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_CM_REG_SAP 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 ProtocolCmRegisterSap (NDIS 5.1)) di Windows Vista. Didukung untuk driver NDIS 5.1 (lihat ProtocolCmRegisterSap (NDIS 5.1)) di Windows XP.
Target Platform	Windows
Header	ndis.h (termasuk Ndis.h)
IRQL	<= DISPATCH_LEVEL