fungsi TSPI_lineGetDevConfig (tspi.h)

Artikel
08/26/2023

Fungsi TSPI_lineGetDevConfig mengembalikan objek struktur data, konten yang khusus untuk baris (penyedia layanan) dan kelas perangkat, memberikan konfigurasi perangkat saat ini yang terkait satu-ke-satu dengan perangkat baris.

Sintaks

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

Parameter

dwDeviceID

Perangkat baris yang akan dikonfigurasi.

lpDeviceConfig

Penunjuk ke struktur data jenis VARSTRING tempat struktur konfigurasi perangkat perangkat terkait dikembalikan. Setelah berhasil menyelesaikan permintaan, penyedia layanan mengisi struktur data ini dengan konfigurasi perangkat. Anggota dwStringFormat dalam struktur VARSTRING harus diatur ke STRINGFORMAT_BINARY. Jika anggota dwTotalSize dari struktur VARSTRING yang diarahkan oleh parameter lpDeviceConfig lebih besar dari atau sama dengan ukuran bagian tetap struktur, penyedia layanan mengatur anggota dwNeedSize ke ukuran yang diperlukan dan mengembalikan nol.

lpszDeviceClass

Penunjuk ke string Unicode yang dihentikan null yang menentukan kelas perangkat perangkat yang konfigurasinya diminta. String kelas perangkat yang valid sama dengan yang ditentukan untuk fungsi TSPI_lineGetID saat diterapkan ke perangkat baris (dwSelect memiliki nilai LINECALLSELECT_LINE).

Nilai kembali

Mengembalikan nol jika fungsi berhasil, atau angka kesalahan jika terjadi kesalahan. Kemungkinan nilai yang dikembalikan adalah sebagai berikut:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Keterangan

Status panggilan khusus perangkat.

Fungsi ini dapat digunakan untuk mengambil struktur data dari penyedia layanan yang menentukan konfigurasi perangkat yang terkait satu-ke-satu dengan perangkat baris. Parameter lpszDeviceClass memilih di antara mungkin beberapa kelas perangkat yang berbeda adalah memiliki konfigurasinya yang diambil. Set kelas yang didukung dibatasi untuk mereka yang perangkatnya sesuai satu-ke-satu dengan perangkat baris. Untuk informasi selengkapnya tentang kelas perangkat umum, lihat Kelas Perangkat TSPI.

Penyedia layanan biasanya harus mengizinkan kelas perangkat tapi/baris di bawah fungsi ini. Ini akan mengambil parameter yang memiliki cakupan "baris", seperti daftar alamat di baris ini, daftar perangkat keras fisik seperti port COMM yang sesuai dengan alamat, jumlah maksimum panggilan bersamaan (jika dapat dikonfigurasi), dan sebagainya.

Secara umum, fungsi ini tidak memungkinkan kelas perangkat terkait media seperti mci waveaudio, gelombang tingkat rendah, atau kelas perangkat datamodem, karena ini biasanya berlaku untuk panggilan tertentu atau alamat tertentu. Karena mungkin ada lebih dari satu perangkat per baris ini, identifikasi panggilan atau alamat tertentu hanya dengan parameter pengidentifikasi perangkat baris dalam fungsi ini akan ambigu. Pengecualian dapat dibuat untuk kelas perangkat khusus panggilan atau khusus alamat jika ada informasi konfigurasi kelas yang berlaku untuk seluruh cakupan perangkat baris, seperti default awal, dan sebagainya.

Ada beberapa alasan mengapa dukungan luar biasa untuk kelas perangkat khusus panggilan dan khusus alamat hanya memiliki nilai terbatas di bawah fungsi ini. Pertama, karena kelas-kelas ini dapat ambigu pada penyedia layanan multi-alamat/multi-panggilan, hanya sebagian penyedia layanan yang mendukungnya. Aplikasi tidak mungkin menambahkan dependensi khusus perangkat pada penyertaan kelas-kelas ini dalam fungsi ini. Kedua, ketika "kelas" media tingkat lebih tinggi muncul yang menerapkan protokol tingkat tinggi seperti akses sistem file dial-in dalam hal API transportasi tingkat rendah, konfigurasi untuk kelas ini cenderung menuju cakupan "instans" alih-alih cakupan "kelas". API media tingkat tinggi harus menyediakan fungsinya sendiri untuk mengonfigurasi instans khusus panggilan atau khusus alamat.

Apa pun jenis perangkat dan kelas perangkat yang didukung fungsi ini, fungsi ini berpotensi memengaruhi dua jenis informasi konfigurasi: permanen dan sementara. Informasi permanen bertahan di berbagai "terbuka" baris, dan bahkan di berbagai "init" penyedia layanan itu sendiri. Informasi sementara hanya bertahan dalam "buka" baris yang unik. Ketika baris ditutup, informasi sementara apa pun yang telah diambil atau diatur melalui TSPI_lineSetDevConfig dapat kembali ke nilai default atau tidak terdefinis. Pemanggil dapat dengan andal mengambil konfigurasi sementara apa pun hanya dengan urutan seperti TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. Pemanggil dapat dengan andal mengatur informasi konfigurasi sementara yang diambil oleh urutan tersebut melalui urutan seperti TSPI_lineOpen, TSPI_lineSetDevConfig. Bagian sementara konfigurasi tetap stabil hanya sampai TSPI_lineConfigDialog, TSPI_lineSetDevConfig, atau TSPI_lineClose berikutnya. Penyedia layanan harus mengurus penyimpanan bagian permanen dari konfigurasi, biasanya dalam file .ini, dan memuat ulang setiap kali penyedia layanan diinisialisasi.

Format data yang tepat yang terkandung dalam struktur yang dikembalikan oleh fungsi ini khusus untuk API kelas baris dan perangkat, tidak terdokumentasi, dan tidak terdefinisi. Struktur yang dikembalikan oleh fungsi ini tidak dapat diakses atau dimanipulasi secara langsung oleh aplikasi, tetapi hanya dapat disimpan secara utuh dan kemudian digunakan dalam TSPI_lineSetDevConfig untuk memulihkan pengaturan. Struktur juga tidak selalu dapat diteruskan ke perangkat lain, bahkan dari kelas perangkat yang sama (meskipun ini mungkin berfungsi dalam beberapa instans, itu tidak dijamin). Penyedia layanan harus menempatkan item dalam struktur data untuk memungkinkannya diperiksa konsistensinya untuk melindungi dari kegagalan karena aplikasi klien meneruskan informasi yang tidak kompatibel.