fungsi TSPI_lineConfigDialogEdit (tspi.h)

Artikel
08/26/2023

Fungsi TSPI_lineConfigDialogEdit usang. TAPI versi 1.4 atau penyedia layanan yang lebih lama dapat menerapkan fungsi TSPI ini. TSP TAPI versi 2.0 atau yang lebih baru menerapkan TUISPI_lineConfigDialogEdit.

Fungsi TSPI_lineConfigDialogEdit menyebabkan penyedia perangkat baris yang ditentukan menampilkan kotak dialog modal sebagai jendela anak hwndOwner untuk memungkinkan pengguna mengonfigurasi parameter yang terkait dengan perangkat baris.

Sintaks

LONG TSPIAPI TSPI_lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

Parameter

dwDeviceID

Perangkat baris yang akan dikonfigurasi.

hwndOwner

Handel ke jendela tempat kotak dialog akan dilampirkan.

lpszDeviceClass

Penunjuk ke string Unicode yang dihentikan null yang mengidentifikasi nama kelas perangkat. Kelas perangkat ini memungkinkan pemanggil untuk memilih sub-layar tertentu dari informasi konfigurasi yang berlaku untuk kelas perangkat tersebut. Jika parameter ini NULL atau menunjuk ke string kosong, konfigurasi tingkat tertinggi dipilih. String yang diizinkan sama dengan untuk TSPI_lineGetID.

lpDeviceConfigIn

Penunjuk ke struktur data konfigurasi buram yang dikembalikan oleh TSPI_lineGetDevConfig (atau pemanggilan TSPI_lineConfigDialogEdit sebelumnya) dalam bagian variabel struktur VARSTRING .

dwSize

Jumlah byte dalam struktur yang diacu oleh lpDeviceConfigIn. Nilai ini dikembalikan dalam anggota dwStringSize dalam struktur VARSTRING yang dikembalikan oleh TSPI_lineGetDevConfig atau pemanggilan TSPI_lineConfigDialogEdit sebelumnya.

lpDeviceConfigOut

Penunjuk ke lokasi memori jenis VARSTRING tempat struktur konfigurasi perangkat dikembalikan. Setelah berhasil menyelesaikan permintaan, lokasi ini diisi dengan konfigurasi perangkat. Anggota dwStringFormat dalam struktur VARSTRING diatur ke STRINGFORMAT_BINARY. Sebelum memanggil lineGetDevConfig (atau pemanggilan lineConfigDialogEdit di masa mendatang), aplikasi harus mengatur anggota dwTotalSize dari struktur ini untuk menunjukkan jumlah memori yang tersedia untuk TAPI untuk mengembalikan informasi.

Nilai kembali

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

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

Keterangan

Fungsi ini menyebabkan penyedia layanan menampilkan kotak dialog modal (dilampirkan ke hwndOwner) untuk memungkinkan pengguna mengonfigurasi parameter yang terkait dengan baris yang ditentukan oleh dwDeviceID.

Parameter lpszDeviceClass memilih sub-layar tertentu dari informasi konfigurasi yang berlaku untuk kelas perangkat tempat pengguna tertarik; string yang diizinkan sama dengan untuk TSPI_lineGetID. Misalnya, jika baris mendukung Comm API, meneruskan comm/datamodem sebagai lpszDeviceClass menyebabkan penyedia menampilkan parameter yang terkait khusus untuk Comm (atau, setidaknya, mulai dari titik yang sesuai dalam rantai kotak dialog konfigurasi multitingkat, sehingga pengguna tidak perlu "menggali" untuk menemukan parameter yang menarik).

Parameter lpszDeviceClass adalah "tapi/line", "", atau NULL menyebabkan penyedia menampilkan konfigurasi tingkat tertinggi untuk baris.

Perbedaan antara fungsi ini dan TSPI_lineConfigDialog adalah sumber parameter untuk diedit dan hasil pengeditan. Dalam TSPI_lineConfigDialog, parameter yang diedit adalah parameter yang saat ini digunakan pada perangkat (atau diatur untuk digunakan pada panggilan berikutnya), dan setiap perubahan yang dilakukan memiliki (sejauh mungkin) dampak langsung pada koneksi aktif apa pun; selain itu, aplikasi harus menggunakan lineGetDevConfig untuk mengambil hasil perubahan parameter dari TSPI_lineConfigDialog. Dengan TSPI_lineConfigDialogEdit, parameter yang akan diedit diteruskan dari aplikasi, dan hasilnya dikembalikan ke aplikasi, tanpa dampak pada koneksi aktif; hasil pengeditan dikembalikan dengan fungsi ini, dan aplikasi tidak perlu memanggil lineGetDevConfig. Dengan demikian, TSPI_lineConfigDialogEdit mengizinkan aplikasi untuk memberikan kemampuan bagi pengguna untuk menyiapkan parameter untuk panggilan di masa mendatang tanpa berdampak pada panggilan aktif apa pun. Namun, output fungsi ini dapat diteruskan ke TSPI_lineSetDevConfig untuk memengaruhi panggilan saat ini atau panggilan berikutnya.

Untuk kompatibilitas mundur, fungsi ini tidak diekspor oleh penyedia layanan yang lebih lama. TAPI mendeteksi kondisi ini dan melaporkan LINEERR_OPERATIONUNAVAIL jika aplikasi mencoba memanggil fungsi ini pada penyedia yang lebih lama.