RasEnumEntriesA, fonction (ras.h)
La fonction RasEnumEntries répertorie tous les noms d’entrée dans un annuaire 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és au; 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 a la valeur NULL, la fonction utilise le fichier d’annuaire par défaut actuel. Le fichier d’annuaire 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 à distance .
Si ce paramètre a la valeur NULL, les entrées sont énumérées à partir de tous les fichiers d’annuaire téléphonique d’accès à distance dans le profil AllUsers et le profil de l’utilisateur.
[in, out] unnamedParam3
Pointeur vers une mémoire tampon qui, à la sortie, reçoit un tableau de structures RASENTRYNAME , une pour chaque entrée de carnet de téléphone.
Lors de l’entrée, une application doit définir le membre dwSize de la première structure RASENTRYNAME 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, à l’entrée, contient la taille, en octets, de la mémoire tampon spécifiée par lprasentryname.
Pointeur vers une variable qui, sur la sortie, contient la taille, en octets, du tableau des structures RASENTRYNAME requises pour les entrées du répertoire 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 de téléphone écrites dans la mémoire tampon spécifiée par lprasentryname.
Valeur retournée
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 provenant des codes d’erreur de routage et d’accès à distance ou winerror.h.
| Valeur | Signification |
|---|---|
|
La mémoire tampon lprasentryname n’est pas assez grande. Le paramètre lpcb est inférieur au membre dwSize dans le paramètre lprasentryname qui doit être défini avant d’appeler la fonction. La fonction retourne la taille de mémoire tampon requise dans la variable pointée par lpcb.
Windows Vista ou version ultérieure : La mémoire tampon lprasentryname peut avoir la valeur NULL et la variable pointée par lpcb peut avoir la valeur zéro. La fonction retourne la taille de mémoire tampon requise dans la variable pointée par lpcb. |
|
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 renvoie cette erreur si dwSize indique que RASENTRYNAME inclut les membres dwFlags et szPhonebookPath , car ces membres ne sont pas pris en charge sur Windows 95 (ils sont pris en charge uniquement 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 l’annuaire téléphonique 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 à nouveau RasEnumEntries pour énumérer les entrées. Notez que pour le deuxième appel, le code définit le membre dwSize de la première structure RASENTRYNAME 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;
}
Notes
L’en-tête ras.h définit RasEnumEntries en tant qu’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. La combinaison 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ras.h |
| Bibliothèque | Rasapi32.lib |
| DLL | Rasapi32.dll |