Fungsi RasEnumEntriesA (ras.h)

Fungsi RasEnumEntries mencantumkan semua nama entri dalam buku telepon akses jarak jauh.

Sintaks

DWORD RasEnumEntriesA(
  [in]      LPCSTR          unnamedParam1,
  [in]      LPCSTR          unnamedParam2,
  [in, out] LPRASENTRYNAMEA unnamedParam3,
  [in, out] LPDWORD         unnamedParam4,
  [out]     LPDWORD         unnamedParam5
);

Parameter

[in] unnamedParam1

Dipesan; harus NULL.

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

Jika parameter ini NULL, entri dijumlahkan dari semua file buku telepon akses jarak jauh di profil AllUsers dan profil pengguna.

[in, out] unnamedParam3

Pointer ke buffer yang, pada output, menerima array struktur RASENTRYNAME , satu untuk setiap entri buku telepon.

Pada input, aplikasi harus mengatur anggota dwSize dari struktur RASENTRYNAME pertama dalam buffer ke sizeof(RASENTRYNAME) untuk mengidentifikasi versi struktur yang diteruskan.

[in, out] unnamedParam4

Penunjuk ke variabel yang, pada input, berisi ukuran, dalam byte, dari buffer yang ditentukan oleh lprasentryname.

Penunjuk ke variabel yang, pada output, berisi ukuran, dalam byte, dari array struktur RASENTRYNAME yang diperlukan untuk entri buku telepon.

Windows Vista atau yang lebih baru: Untuk menentukan ukuran buffer yang diperlukan, panggil RasEnumEntries dengan lprasentryname diatur ke NULL. Variabel yang ditunjukkan oleh lpcb harus diatur ke nol. Fungsi ini akan mengembalikan ukuran buffer yang diperlukan dalam lpcb dan kode kesalahan ERROR_BUFFER_TOO_SMALL.

[out] unnamedParam5

Penunjuk ke variabel yang menerima jumlah entri buku telepon yang ditulis ke buffer yang ditentukan oleh lprasentryname.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut atau nilai dari Kode Kesalahan Perutean dan Akses Jarak Jauh atau Winerror.h.

Nilai	Makna
ERROR_BUFFER_TOO_SMALL	Buffer lprasentryname tidak cukup besar. Parameter lpcb kurang dari anggota dwSize dalam parameter lprasentryname yang harus diatur sebelum memanggil fungsi. Fungsi mengembalikan ukuran buffer yang diperlukan dalam variabel yang ditunjukkan oleh lpcb. Windows Vista atau yang lebih baru: Buffer lprasentryname dapat diatur ke NULL dan variabel yang diacu oleh lpcb dapat diatur ke nol. Fungsi akan mengembalikan ukuran buffer yang diperlukan dalam variabel yang ditunjukkan oleh lpcb.
ERROR_INVALID_SIZE	Nilai dwSize dalam struktur RASENTRYNAME yang diarahkan oleh lprasentryname, menentukan versi struktur yang tidak didukung pada platform saat ini. Misalnya, pada Windows 95, RasEnumEntries mengembalikan kesalahan ini jika dwSize menunjukkan bahwa RASENTRYNAME menyertakan anggota dwFlags dan szPhonebookPath , karena anggota ini tidak didukung pada Windows 95 (mereka hanya didukung pada Windows 2000 dan yang lebih baru).
ERROR_NOT_ENOUGH_MEMORY	Fungsi tidak dapat mengalokasikan memori yang cukup untuk menyelesaikan operasi.

Keterangan

Kode sampel berikut menghitung entri buku telepon RAS di Windows Vista dan versi Windows yang lebih baru. Kode awalnya memanggil RasEnumEntries untuk mendapatkan ukuran buffer untuk diteruskan. Kode kemudian memanggil RasEnumEntries lagi, untuk menghitung entri. Perhatikan bahwa untuk panggilan kedua, kode menetapkan anggota dwSize dari struktur RASENTRYNAME pertama dalam buffer ke sizeof (RASENTRYNAME) untuk menentukan versi struktur.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")

DWORD __cdecl wmain(){

    DWORD dwCb = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwEntries = 0;
    LPRASENTRYNAME lpRasEntryName = NULL;
    
    // Call RasEnumEntries with lpRasEntryName = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS entry names.
        lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasEntryName == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASENTRYNAME structure in the array must contain the structure size
        lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
        
        // Call RasEnumEntries to enumerate all RAS entry names
        dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

        // If successful, print the RAS entry names 
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS entry names were found:\n");
            for (DWORD i = 0; i < dwEntries; i++){
                wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
            }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasEntryName);
        lpRasEntryName = NULL;
        return 0;
    }

    // There was either a problem with RAS or there are RAS entry names to enumerate    
    if(dwEntries >= 1){
        wprintf(L"The operation failed to acquire the buffer size.\n");
    }else{
        wprintf(L"There were no RAS entry names found:.\n");
    }

    return 0;
}

Catatan

Header ras.h mendefinisikan RasEnumEntries 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	ras.h
Pustaka	Rasapi32.lib
DLL	Rasapi32.dll

Lihat juga

RASENTRYNAME

RasEnumConnections

Gambaran Umum Layanan Akses Jarak Jauh (RAS)

Fungsi Layanan Akses Jarak Jauh