Fungsi RasEnumDevicesA (ras.h)

Fungsi RasEnumDevices mengembalikan nama dan jenis semua perangkat berkemampuan RAS yang tersedia.

Sintaks

DWORD RasEnumDevicesA(
  [in]      LPRASDEVINFOA unnamedParam1,
  [in, out] LPDWORD       unnamedParam2,
  [out]     LPDWORD       unnamedParam3
);

Parameter

[in] unnamedParam1

Penunjuk ke buffer yang menerima array struktur RASDEVINFO , satu untuk setiap perangkat berkemampuan RAS. Sebelum memanggil fungsi, atur anggota dwSize dari struktur RASDEVINFO pertama dalam buffer ke sizeof (RASDEVINFO) untuk mengidentifikasi versi struktur.

[in, out] unnamedParam2

Penunjuk ke variabel yang, pada input, berisi ukuran, dalam byte, dari buffer lpRasDevInfo .

Pada output, fungsi mengatur variabel ini ke jumlah byte yang diperlukan untuk menghitung perangkat.

Catatan  

Untuk menentukan ukuran buffer yang diperlukan, panggil RasEnumDevices dengan lpRasDevInfo 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] unnamedParam3

Pointer ke variabel yang menerima jumlah struktur RASDEVINFO yang ditulis ke buffer lpRasDevInfo .

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_BUFFER_TOO_SMALL
Buffer lpRasDevInfo tidak cukup besar. Parameter lpcb kurang dari anggota dwSize dalam parameter lpRasDevInfo yang harus diatur sebelum memanggil fungsi. Fungsi mengembalikan ukuran buffer yang diperlukan dalam variabel yang ditunjukkan oleh lpcb.
ERROR_NOT_ENOUGH_MEMORY
Menunjukkan memori yang tidak mencukuum. Parameter lpRasDevInfo adalah non-NULL, parameter lpcbnon-NULL dan alokasi memori internal gagal. Ini mungkin karena kondisi memori rendah.
ERROR_INVALID_PARAMETER
Menunjukkan nilai parameter yang tidak valid. Parameter lpcb adalah NULL atau parameter lpcDevices adalah NULL.
ERROR_INVALID_USER_BUFFER
Alamat atau buffer yang ditentukan oleh lpRasDevInfo tidak valid. Anggota dwSize dari parameter lpRasDevInfo tidak sama dengan sizeof (RASDEVINFO).

Keterangan

Kode sampel berikut menghitung perangkat pada komputer saat ini. Kode awalnya memanggil RasEnumDevices dengan parameter lpRasDevInfoNULL, untuk mendapatkan ukuran buffer yang harus diteruskan. Kode ini juga mengatur anggota dwSize dari struktur RASDEVINFO pertama ke sizeof (RASDEVINFO) 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 dwDevices = 0;
    LPRASDEVINFO lpRasDevInfo = NULL;
    
    // Call RasEnumDevices with lpRasDevInfo = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS structure(s).
        lpRasDevInfo = (LPRASDEVINFO) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasDevInfo == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASDEVINFO structure in the array must contain the structure size
        lpRasDevInfo[0].dwSize = sizeof(RASDEVINFO);
        
        // Call RasEnumDevices to enumerate RAS devices
        dwRet = RasEnumDevices(lpRasDevInfo, &dwCb, &dwDevices);

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

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

    return 0;
}

Catatan

Header ras.h mendefinisikan RasEnumDevices 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

RASDEVINFO

Gambaran Umum Layanan Akses Jarak Jauh (RAS)

Fungsi Layanan Akses Jarak Jauh