RasEnumAutodialAddressesA, fonction (ras.h)

Article
03/01/2024

La fonction RasEnumAutodialAddresses retourne une liste de toutes les adresses dans la base de données de mappage AutoDial.

Syntaxe

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

Paramètres

[in, out] lppRasAutodialAddresses

Pointeur vers un tableau de pointeurs de chaîne, avec un espace supplémentaire pour le stockage des chaînes elles-mêmes à la fin de la mémoire tampon.

Lors de la sortie, chaque chaîne reçoit le nom d’une adresse dans la base de données de mappage autoDial.

Si lppAddresses a la valeur NULL lors de l’entrée, RasEnumAutodialAddresses définit les paramètres lpdwcbAddresses et lpdwcAddresses pour indiquer la taille requise, en octets, et le nombre d’entrées d’adresse dans la base de données.

[in, out] lpdwcbRasAutodialAddresses

Pointeur vers une variable qui, à l’entrée, contient la taille, en octets, de la mémoire tampon spécifiée par le paramètre lpRasEnumAutodialAddressespAddresses .

Remarque

Pour déterminer la taille de mémoire tampon requise, appelez RasEnumAutodialAddresses avec lppAddresses défini sur NULL. La variable pointée par lpdwcbAddresses doit être définie sur zéro. La fonction retourne la taille de mémoire tampon requise dans lpdwcbAddresses et un code d’erreur de ERROR_BUFFER_TOO_SMALL.

[out] lpdwcRasAutodialAddresses

Pointeur vers une variable qui reçoit le nombre de chaînes d’adresse retournées dans la mémoire tampon lppAddresses .

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
ERROR_INVALID_PARAMETER	Null a été passé pour le paramètre lpdwcbAddresses ou lpdwcAddresses .
ERROR_BUFFER_TOO_SMALL	La mémoire tampon lppAddresses était NULL et lpdwcbAddresses était zéro. La fonction retourne la taille de mémoire tampon requise dans la variable pointée par lpdwcbAddresses.

Remarques

L’exemple de code suivant utilise RasEnumAutodialAddresses pour énumérer la base de données de mappage automatique.

#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;
}

Notes

L’en-tête ras.h définit RasEnumAutodialAddresses 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

Voir aussi

RASAUTODIALENTRY

RasGetAutodialAddress

RasSetAutodialAddress

Vue d’ensemble du service d’accès à distance (RAS)

Fonctions du service d’accès à distance

Partager via