fungsi TSPI_lineSetDevConfig (tspi.h)

Artikel
03/08/2023

Fungsi TSPI_lineSetDevConfig memulihkan konfigurasi perangkat yang terkait satu-ke-satu dengan perangkat baris dari struktur data yang sebelumnya diperoleh menggunakan TSPI_lineGetDevConfig. Isi struktur data ini khusus untuk baris [penyedia layanan] dan kelas perangkat.

Sintaks

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

Parameter

dwDeviceID

Perangkat baris yang akan dikonfigurasi.

lpDeviceConfig

Penunjuk ke struktur data konfigurasi yang dikembalikan dalam bagian variabel struktur VARSTRING dengan TSPI_lineGetDevConfig.

dwSize

Jumlah byte dalam struktur yang diacu oleh lpDeviceConfig. Nilai ini dikembalikan dalam anggota dwStringSize dalam struktur VARSTRING yang dikembalikan oleh TSPI_lineGetDevConfig.

Catatan Jika parameter ukuran dalam struktur tidak benar, ada kemungkinan data bisa ditimpa. Untuk informasi selengkapnya tentang pengaturan ukuran struktur, lihat topik alokasi memori .

lpszDeviceClass

Penunjuk ke string Unicode yang dihentikan null yang menentukan kelas perangkat perangkat yang konfigurasinya akan dipulihkan. String kelas perangkat yang valid sama dengan yang ditentukan untuk fungsi TSPI_lineGetID ketika diterapkan ke perangkat "baris" (yaitu, ketika dwSelect memiliki nilai LINECALLSELECT_LINE).

Nilai kembali

Mengembalikan nol jika fungsi berhasil, atau angka kesalahan jika terjadi kesalahan. Nilai yang mungkin dikembalikan adalah:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER.

Keterangan

Status panggilan spesifik perangkat.

Penyedia layanan mengembalikan LINEERR_INVALPARAM jika informasi yang terkandung dalam struktur yang diacu oleh lpDeviceConfig tidak valid untuk perangkat ini.

Penyedia layanan mengembalikan LINEERR_INVALLINESTATE jika konfigurasi perangkat tidak dapat diubah dalam status baris saat ini. Baris mungkin digunakan oleh aplikasi lain.

Fungsi ini dapat digunakan untuk memulihkan konfigurasi perangkat yang terkait satu-ke-satu dengan perangkat baris dari struktur data yang sebelumnya diambil dari penyedia layanan menggunakan fungsi TSPI_lineGetDevConfig . Parameter lpszDeviceClass memilih salah satu dari kemungkinan beberapa kelas perangkat yang berbeda adalah memulihkan konfigurasinya. Kumpulan 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 mengizinkan kelas perangkat tapi/line di bawah fungsi ini. Ini memulihkan parameter yang memiliki cakupan "baris", seperti daftar alamat di baris ini dan daftar perangkat keras fisik seperti port COMM yang sesuai dengan alamat atau jumlah maksimum panggilan bersamaan (jika dapat dikonfigurasi).

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 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.

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 beberapa alamat, penyedia layanan multi-panggilan, hanya sebagian penyedia layanan yang mendukungnya. Program 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 ditetapkan atau diambil melalui TSPI_lineGetDevConfig 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 diteruskan ke fungsi ini khusus untuk API kelas baris dan perangkat, tidak terdokumentasi, dan tidak ditentukan. Struktur yang diteruskan ke fungsi ini tidak dapat langsung diakses atau dimanipulasi oleh aplikasi, tetapi hanya dapat disimpan secara utuh dan kemudian digunakan dari TSPI_lineGetDevConfig sebelumnya untuk mendapatkan pengaturan. Struktur juga tidak selalu dapat diteruskan ke perangkat lain, bahkan dari kelas perangkat yang sama (meskipun ini mungkin berfungsi dalam beberapa kasus, itu tidak dijamin). Penyedia layanan harus memeriksa struktur data ini untuk konsistensi guna melindungi dari kegagalan karena aplikasi klien meneruskan informasi yang tidak kompatibel.

Catatan Beberapa penyedia layanan mungkin mengizinkan konfigurasi diatur saat perangkat sedang digunakan, dan yang lain mungkin tidak.