RasEnumEntriesA, fonction (ras.h)
La fonction RasEnumEntries répertorie tous les noms d’entrée dans un carnet téléphonique d’accès à distance.
Syntaxe
DWORD RasEnumEntriesA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASENTRYNAMEA unnamedParam3,
[in, out] LPDWORD unnamedParam4,
[out] LPDWORD unnamedParam5
);
Paramètres
[in] unnamedParam1
Réservé; doit être NULL .
[in] unnamedParam2
Pointeur vers une chaîne terminée par null qui spécifie le chemin d’accès complet et le nom de fichier d’un fichier PBK (Phone-Book). Si ce paramètre est NULL, la fonction utilise le fichier de livre téléphonique par défaut actuel. Le fichier de carnet téléphonique par défaut est celui sélectionné par l’utilisateur dans la feuille de propriétés Préférences utilisateur de la boîte de dialogue Mise en réseau rendez-vous.
Si ce paramètre est NULL, les entrées sont énumérées à partir de tous les fichiers de livres téléphoniques d’accès à distance dans le profil AllUsers et le profil de l’utilisateur.
[in, out] unnamedParam3
Pointeur vers une mémoire tampon qui, en sortie, reçoit un tableau de structures RASENTRYNAME, une pour chaque entrée de livre téléphonique.
Lors de l’entrée, une application doit définir la dwSize membre du premier RASENTRYNAME structure dans la mémoire tampon sur sizeof(RASENTRYNAME) afin d’identifier la version de la structure passée.
[in, out] unnamedParam4
Pointeur vers une variable qui, en entrée, contient la taille, en octets, de la mémoire tampon spécifiée par lprasentryname.
Pointeur vers une variable qui, en sortie, contient la taille, en octets, du tableau de RASENTRYNAME structures requises pour les entrées de carnet téléphonique.
Windows Vista ou version ultérieure : Pour déterminer la taille de mémoire tampon requise, appelez RasEnumEntries avec lprasentryname défini sur NULL. La variable pointée par lpcb doit être définie sur zéro. La fonction retourne la taille de mémoire tampon requise dans lpcb et un code d’erreur de ERROR_BUFFER_TOO_SMALL.
[out] unnamedParam5
Pointeur vers une variable qui reçoit le nombre d’entrées de carnet téléphonique écrites dans la mémoire tampon spécifiée par lprasentryname.
Valeur de retour
Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.
Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants ou une valeur de Codes d’erreur d’acheminement et d’accès à distance ou Winerror.h.
| Valeur | Signification |
|---|---|
|
La mémoire tampon |
|
La valeur de dwSize dans la structure RASENTRYNAME pointée par lprasentryname, spécifie une version de la structure qui n’est pas prise en charge sur la plateforme actuelle. Par exemple, sur Windows 95, RasEnumEntries retourne cette erreur si dwSize indique que RASENTRYNAME inclut les dwFlags et szPhonebookPath membres, car ces membres ne sont pas pris en charge sur Windows 95 (ils ne sont pris en charge que sur Windows 2000 et versions ultérieures). |
|
La fonction n’a pas pu allouer suffisamment de mémoire pour terminer l’opération. |
Remarques
L’exemple de code suivant énumère les entrées de livres téléphoniques RAS sur Windows Vista et les versions ultérieures de Windows. Le code appelle initialement RasEnumEntries pour obtenir la taille de la mémoire tampon à transmettre. Le code appelle ensuite RasEnumEntries à nouveau, pour énumérer les entrées. Notez que pour le deuxième appel, le code définit la dwSize membre du premier RASENTRYNAME structure dans la mémoire tampon sur sizeof(RASENTRYNAME) pour spécifier la version de la structure.
#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;
}
Note
L’en-tête ras.h définit RasEnumEntries comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | ras.h |
| bibliothèque | Rasapi32.lib |
| DLL | Rasapi32.dll |
Voir aussi
Vue d’ensemble service d’accès à distance (RAS)