Fungsi RasDialDlgA (rasdlg.h)

Fungsi RasDialDlg membuat koneksi RAS menggunakan entri buku telepon tertentu dan kredensial pengguna yang masuk. Fungsi menampilkan aliran kotak dialog yang menunjukkan status operasi koneksi.

Sintaks

BOOL RasDialDlgA(
  [in] LPSTR        lpszPhonebook,
  [in] LPSTR        lpszEntry,
  [in] LPSTR        lpszPhoneNumber,
  [in] LPRASDIALDLG lpInfo
);

Parameter

[in] lpszPhonebook

Penunjuk ke string yang dihentikan null yang menentukan jalur lengkap dan nama file dari file buku telepon (PBK). Jika parameter ini ADALAH 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] lpszEntry

Penunjuk ke string yang dihentikan null yang menentukan nama entri buku telepon untuk dihubungi.

[in] lpszPhoneNumber

Penunjuk ke string yang dihentikan null yang menentukan nomor telepon yang mengambil alih nomor yang disimpan dalam entri buku telepon. Jika parameter ini NULL, RasDialDlg menggunakan nomor dalam entri buku telepon.

[in] lpInfo

Penunjuk ke struktur RASDIALDLG yang menentukan parameter input dan output tambahan. Anggota dwSize dari struktur ini harus menentukan sizeof(RASDIALDLG). Jika terjadi kesalahan, anggota dwError mengembalikan kode kesalahan; jika tidak, ia mengembalikan nol.

Mengembalikan nilai

Jika fungsi menetapkan koneksi RAS, nilai yang dikembalikan adalah TRUE. Jika tidak, fungsi harus mengembalikan FALSE.

Jika terjadi kesalahan, RasDialDlg harus mengatur anggota dwError dari struktur RASDIALDLG ke nilai dari Perutean dan Kode Kesalahan Akses Jarak Jauh atau Winerror.h.

Keterangan

Fungsi RasDialDlg menampilkan serangkaian kotak dialog yang mirip dengan kotak dialog kotak dialog Jaringan Dial-Up utama ditampilkan saat pengguna memilih tombol Putar Nomor. Gunakan fungsi RasDialDlg untuk menampilkan antarmuka pengguna standar untuk operasi koneksi tanpa menyajikan kotak dialog buku telepon utama. Misalnya, layanan RAS AutoDial menggunakan fungsi ini untuk membuat koneksi menggunakan entri buku telepon yang terkait dengan alamat jarak jauh.

Fungsi RasDialDlg menampilkan kotak dialog selama operasi koneksi untuk memberikan umpan balik kepada pengguna tentang kemajuan operasi. Misalnya, kotak dialog mungkin menunjukkan kapan operasi berputar, saat mengautentikasi kredensial pengguna di server jarak jauh, dan sebagainya. Kotak dialog juga menyediakan tombol Batalkan bagi pengguna untuk mengakhiri operasi.

RasDialDlg kembali saat koneksi dibuat, atau ketika pengguna membatalkan operasi.

Contoh kode berikut memanggil entri dalam buku telepon default yang ditentukan oleh variabel lpszEntry.

Catatan Sampel sederhana ini dimaksudkan untuk dijalankan pada Windows Vista dan versi Windows yang lebih baru. Perlu diketahui bahwa panggilan ke sizeof (RASENTRY) akan mengembalikan nilai yang berbeda tergantung pada versi sistem operasi apa yang dijalankan kode. Silakan ambil langkah-langkah untuk memastikan ini ditangani dengan tepat.

 

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "rasdlg.h"
#include <tchar.h>
#include "strsafe.h"

#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5

DWORD __cdecl wmain(){

    DWORD dwError = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";
    LPTSTR lpszphonenumber = L"5555555";
    LPTSTR lpszdevicename = L"Modem";
    LPTSTR lpszdevicetype = RASDT_Modem;

    // Allocate heap memory and initialize RASENTRY structure
    LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
    // Allocate heap memory and initialize RASDIALDLG structure
    LPRASDIALDLG lpInfo = (LPRASDIALDLG) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASDIALDLG));
    
    if (lpentry == NULL || lpInfo == NULL){
        wprintf(L"HeapAlloc failed");
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // The RASDIALDLG and RASENTRY dwSize members have to be initialized or the RasDialDlg()
    // RasSetEntryProperties() APIs will fail below.
    lpInfo->dwSize = sizeof(RASDIALDLG);
    lpentry->dwSize = sizeof(RASENTRY);
    lpentry->dwFramingProtocol = RASFP_Ppp;
    lpentry->dwfOptions = 0;
    lpentry->dwType = RASFP_Ppp;
    dwError |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszphonenumber, PHONE_NUMBER_LENGTH);
    dwError |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszdevicename, DEVICE_NAME_LENGTH);
    dwError |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszdevicetype, DEVICE_TYPE_LENGTH);
    
    if (dwError != S_OK){
        wprintf(L"Structure initialization failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // Validate the new entry's name
    dwError = RasValidateEntryName(NULL, lpszEntry);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasValidateEntryName failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // Create and set the new entry's properties
    dwError = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }
    
    // Connect using the new entry
    nRet = RasDialDlg(NULL, lpszEntry, NULL, lpInfo);
    if (nRet != TRUE){
        wprintf(L"RasDialDlg failed: Error = %d\n", lpInfo->dwError);
    }
    
    // Clean up: delete the new entry
    dwError = RasDeleteEntry(NULL, lpszEntry);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasDeleteEntry failed: Error = %d\n", dwError);
    }
    
    HeapFree(GetProcessHeap(), 0, lpentry);
    HeapFree(GetProcessHeap(), 0, lpInfo);

    return 0;
}

Catatan

Header rasdlg.h mendefinisikan RasDialDlg 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

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	rasdlg.h
Pustaka	Rasdlg.lib
DLL	Rasdlg.dll

Lihat juga

RASDIALDLG

RasPhonebookDlg

Gambaran Umum Layanan Akses Jarak Jauh (RAS)

Fungsi Layanan Akses Jarak Jauh