Fungsi RasEnumDevicesA (ras.h)

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

Sintaksis

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

Parameter

[in] unnamedParam1

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

[in, out] unnamedParam2

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

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 lpRasDevInfo buffer.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian ERROR_SUCCESS.

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

Nilai	Arti
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 mencukup. Parameter lpRasDevInfo non-null, parameter lpcb non-null dan alokasi memori internal gagal. Ini mungkin karena kondisi memori rendah.
ERROR_INVALID_PARAMETER	Menunjukkan nilai parameter yang tidak valid. Parameter lpcb NULL atau parameter lpcDevices NULL.
ERROR_INVALID_USER_BUFFER	Alamat atau buffer yang ditentukan oleh lpRasDevInfo tidak valid. dwSize anggota parameter lpRasDevInfo tidak sama ukurannya(RASDEVINFO ).

Komentar

Kode sampel berikut menghitung perangkat pada komputer saat ini. Kode awalnya memanggil RasEnumDevices dengan parameter lpRasDevInfo NULL, untuk mendapatkan ukuran buffer yang harus diteruskan. Kode ini juga mengatur dwSize anggota 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;
}

Nota

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

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

Lihat juga

RASDEVINFO

Gambaran Umum Remote Access Service (RAS)

Fungsi Layanan Akses Jarak Jauh