Fungsi RasEnumAutodialAddressesA (ras.h)

Fungsi RasEnumAutodialAddresses mengembalikan daftar semua alamat dalam database pemetaan AutoDial.

Sintaks

DWORD RasEnumAutodialAddressesA(
  [in, out] LPSTR   *lppRasAutodialAddresses,
  [in, out] LPDWORD lpdwcbRasAutodialAddresses,
  [out]     LPDWORD lpdwcRasAutodialAddresses
);

Parameter

[in, out] lppRasAutodialAddresses

Penunjuk ke array penunjuk string, dengan ruang tambahan untuk penyimpanan string itu sendiri di akhir buffer.

Pada output, setiap string menerima nama alamat dalam database pemetaan AutoDial.

Jika lppAddressesadalah NULL pada input, RasEnumAutodialAddresses mengatur parameter lpdwcbAddresses dan lpdwcAddresses untuk menunjukkan ukuran yang diperlukan, dalam byte, dan jumlah entri alamat dalam database.

[in, out] lpdwcbRasAutodialAddresses

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

Catatan  

Untuk menentukan ukuran buffer yang diperlukan, panggil RasEnumAutodialAddresses dengan lppAddresses yang diatur ke NULL. Variabel yang diarahkan oleh lpdwcbAddresses harus diatur ke nol. Fungsi ini akan mengembalikan ukuran buffer yang diperlukan dalam lpdwcbAddresses dan kode kesalahan ERROR_BUFFER_TOO_SMALL.

 

[out] lpdwcRasAutodialAddresses

Penunjuk ke variabel yang menerima jumlah string alamat yang dikembalikan dalam buffer lppAddresses .

Nilai kembali

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_INVALID_PARAMETER	NULL diteruskan untuk parameter lpdwcbAddresses atau lpdwcAddresses .
ERROR_BUFFER_TOO_SMALL	Buffer lppAddresses adalah NULL dan lpdwcbAddresses adalah nol. Fungsi mengembalikan ukuran buffer yang diperlukan dalam variabel yang diarahkan oleh lpdwcbAddresses.

Keterangan

Kode sampel kode berikut menggunakan RasEnumAutodialAddresses untuk menghitung database pemetaan Autodial.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#include <tchar.h>

DWORD __cdecl wmain(){

    DWORD dwBytes = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwAddresses = 0;
    LPTSTR * lppAddresses = NULL;
    LPCTSTR lpEntryAddress = L"www.microsoft.com";

    // Allocate memory for a new Autodial address to add to the mapping database
    LPRASAUTODIALENTRY lpentry = (LPRASAUTODIALENTRY) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASAUTODIALENTRY));
    lpentry->dwSize = sizeof(RASAUTODIALENTRY);

    // Add a (non-functional) address to the Autodial mapping database
    // (this ensures RasEnumAutodialAddresses() has something to return)
    dwRet = RasSetAutodialAddress(lpEntryAddress, 0, lpentry, lpentry->dwSize, 1);
    
    // Call RasEnumAutodialAddresses() with lppAddresses = NULL. dwBytes is returned with the 
    // required buffer size and a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumAutodialAddresses(lppAddresses, &dwBytes, &dwAddresses);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS Autodial addresses.
        lppAddresses = (LPTSTR *) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwBytes);
        if (lppAddresses == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        
        // Call RasEnumAutodialAddresses() to enumerate all RAS Autodial addresses
        dwRet = RasEnumAutodialAddresses(lppAddresses, &dwBytes, &dwAddresses);

        // If successful, print the RAS Autodial addresses
        if (dwRet == ERROR_SUCCESS){
            wprintf(L"The following RAS Autodial addresses were found:\n");
            for (DWORD i = 0; i < dwAddresses; i++){
                wprintf(L"%s\n", lppAddresses[i]);
            }
        }
        // Remove the address
        dwRet = RasSetAutodialAddress(lpEntryAddress, 0, NULL, 0, 0);
        
        //Deallocate memory for the address buffers
        HeapFree(GetProcessHeap(), 0, lppAddresses);    
        HeapFree(GetProcessHeap(), 0, lpentry);
        lppAddresses = NULL;
        return 0;
    }

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

    // Remove the address
    dwRet = RasSetAutodialAddress(lpEntryAddress, 0, NULL, 0, 0);
    HeapFree(GetProcessHeap(), 0, lpentry);
    return 0;
}

Catatan

Header ras.h mendefinisikan RasEnumAutodialAddresses sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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

RASAUTODIALENTRY

RasGetAutodialAddress

RasSetAutodialAddress

Gambaran Umum Layanan Akses Jarak Jauh (RAS)

Fungsi Layanan Akses Jarak Jauh