Fungsi RasDialA (ras.h)

Artikel
03/15/2023

Fungsi RasDial menetapkan koneksi RAS antara klien RAS dan server RAS. Data koneksi mencakup informasi panggilan balik dan autentikasi pengguna.

Sintaks

DWORD RasDialA(
  [in]  LPRASDIALEXTENSIONS unnamedParam1,
  [in]  LPCSTR              unnamedParam2,
  [in]  LPRASDIALPARAMSA    unnamedParam3,
  [in]  DWORD               unnamedParam4,
  [in]  LPVOID              unnamedParam5,
  [out] LPHRASCONN          unnamedParam6
);

Parameter

[in] unnamedParam1

Arahkan ke struktur RASDIALEXTENSIONS yang menentukan serangkaian fitur yang diperluas RasDial untuk diaktifkan. Atur parameter ini ke NULL jika tidak perlu mengaktifkan fitur-fitur ini.

[in] unnamedParam2

Penunjuk ke string yang dihentikan null yang menentukan jalur lengkap dan nama file file buku telepon (PBK). Jika parameter ini NULL, fungsi menggunakan file buku telepon default saat ini. File buku telepon default adalah file yang dipilih oleh pengguna di lembar properti Preferensi Pengguna dari kotak dialog Jaringan Dial-Up .

[in] unnamedParam3

Penunjuk ke struktur RASDIALPARAMS yang menentukan parameter panggilan untuk koneksi RAS. Gunakan fungsi RasGetEntryDialParams untuk mengambil salinan struktur ini untuk entri buku telepon tertentu.

Pemanggil harus mengatur anggota dwSize struktur RASDIALPARAMS ke sizeof (RASDIALPARAMS) untuk mengidentifikasi versi struktur yang diteruskan.

Jika anggota szPhoneNumber dari struktur RASDIALPARAMS adalah string kosong, RasDial menggunakan nomor telepon yang disimpan dalam entri buku telepon.

[in] unnamedParam4

Menentukan sifat parameter lpvNotifier . Jika lpvNotifierADALAH NULL, dwNotifierType diabaikan. Jika lpvNotifier bukan NULL, atur dwNotifierType ke salah satu nilai berikut.

Nilai	Makna
0	Parameter lpvNotifier menunjuk ke fungsi panggilan balik RasDialFunc .
1	Parameter lpvNotifier menunjuk ke fungsi panggilan balik RasDialFunc1 .
2	Parameter lpvNotifier menunjuk ke fungsi panggilan balik RasDialFunc2 .

[in] unnamedParam5

Menentukan handel jendela atau fungsi panggilan balik RasDialFunc, RasDialFunc1, atau RasDialFunc2 untuk menerima pemberitahuan peristiwa RasDial . Parameter dwNotifierType menentukan sifat lpvNotifier. Silakan merujuk ke deskripsinya sebelumnya untuk detail lebih lanjut.

Jika parameter ini bukan NULL, RasDial mengirimkan pesan ke jendela, atau memanggil fungsi panggilan balik, untuk setiap peristiwa RasDial . Selain itu, panggilan RasDial beroperasi secara asinkron: RasDial segera kembali, sebelum koneksi dibuat, dan mengomunikasikan kemajuannya melalui jendela atau fungsi panggilan balik.

Jika lpvNotifier adalah NULL, panggilan RasDial beroperasi secara sinkron: RasDial tidak kembali sampai upaya koneksi berhasil diselesaikan atau gagal.

Jika lpvNotifier bukan NULL, pemberitahuan ke jendela atau fungsi panggilan balik dapat terjadi kapan saja setelah panggilan awal ke RasDial. Pemberitahuan berakhir ketika salah satu peristiwa berikut terjadi:

Koneksi dibuat. Dengan kata lain, status koneksi RAS RASCS_Connected.
Koneksi gagal. Dengan kata lain, dwError bukan nol.
RasHangUp dipanggil pada koneksi.

Pemberitahuan panggilan balik dibuat dalam konteks utas yang diambil selama panggilan awal ke RasDial.

[out] unnamedParam6

Penunjuk ke variabel jenis HRASCONN. Atur variabel HRASCONN ke NULL sebelum memanggil RasDial. Jika RasDial berhasil, RasDial menyimpan handel ke koneksi RAS ke dalam *lphRasConn.

Nilai kembali

Jika fungsi berhasil, nilai pengembalian ERROR_SUCCESS dan handel ke koneksi RAS dikembalikan dalam variabel yang diarahkan oleh lphRasConn.

Jika fungsi gagal, nilai yang dikembalikan berasal dari Kode Kesalahan Perutean dan Akses Jarak Jauh atau Winerror.h.

Keterangan

Kesalahan yang terjadi setelah pengembalian langsung dapat dideteksi oleh RasGetConnectStatus. Data tersedia hingga aplikasi memanggil RasHangUp untuk menutup koneksi.

Aplikasi akhirnya harus memanggil RasHangUp setiap kali handel koneksi non-NULL disimpan ke dalam *lphRasConn. Ini berlaku bahkan jika RasDial mengembalikan nilai bukan nol (kesalahan).

Aplikasi dapat dengan aman memanggil RasHangUp dari fungsi panggilan balik pemberitahuan RasDial . Namun, jika ini dilakukan, tutup telepon tidak terjadi sampai rutinitas kembali.

Jika struktur yang ditujukkan oleh lpRasDialExtensions memungkinkan RDEOPT_PausedStates, fungsi RasDial dijeda setiap kali memasuki status di mana bit RASCS_PAUSED diatur ke salah satunya. Untuk memulai ulang RasDial dari status dijeda seperti itu, panggil RasDial lagi, melewati handel koneksi yang dikembalikan dari panggilan RasDial asli di *lphRasConn. Pemberitahuan yang sama yang digunakan dalam panggilan RasDial asli harus digunakan saat memulai ulang dari status dijeda.

Parameter lpvNotifier adalah handel ke jendela untuk menerima pesan pemberitahuan kemajuan. Dalam pesan pemberitahuan kemajuan, wParam setara dengan parameter rasconnstateRasDialFunc dan RasDialFunc1, dan lParam setara dengan parameter dwErrorRasDialFunc dan RasDialFunc1.

Pesan pemberitahuan kemajuan menggunakan kode pesan terdaftar sistem. Anda dapat memperoleh nilai kode pesan ini sebagai berikut:

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS mendukung koneksi yang direferensikan. Jika entri yang diputar sudah tersambung, RasDial mengembalikan SUCCESS dan koneksi direferensikan. Untuk memutuskan koneksi, setiap RasDial pada koneksi harus dicocokkan dengan RasHangUp.

Karena beberapa entri buku telepon memerlukan Extensible Authentication Protocol (EAP) untuk autentikasi, pemanggil harus memanggil RasGetEapUserIdentity sebelum memanggil RasDial. Jika RasGetEapUserIdentity mengembalikan ERROR_INVALID_FUNCTION_FOR_ENTRY, entri buku telepon tidak memerlukan EAP. Namun, jika RasGetEapUserIdentity mengembalikan NO_ERROR, pemanggil harus menyalin informasi identitas EAP dari RasGetEapUserIdentity ke anggota RasEapInfo dari RASDIALEXTENSIONS, dan anggota szUserNameRASDIALPARAMS. Lihat RasGetEapUserIdentity untuk informasi selengkapnya. Jika entri buku telepon memerlukan EAP, anggota dwfOptions dari struktur RASENTRY untuk entri berisi bendera RASEO_RequireEAP .

Untuk menentukan bahwa RasDial harus memasuki status RASCS_CallbackSetByCaller, atur lpRasDialParams-szCallbackNumber> ke "*" pada panggilan awal ke RasDial. Saat handler pemberitahuan dipanggil dengan status ini, atur nomor panggilan balik ke nomor yang disediakan oleh pengguna.

Catatan

Header ras.h mendefinisikan RasDial sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ras.h
Pustaka	Rasapi32.lib
DLL	Rasapi32.dll