RasGetAutodialAddressA function (ras.h)

Article
02/09/2023

The RasGetAutodialAddress function retrieves information about all the AutoDial entries associated with a network address in the AutoDial mapping database.

Syntax

DWORD RasGetAutodialAddressA(
  [in]      LPCSTR              unnamedParam1,
  [in]      LPDWORD             unnamedParam2,
  [in, out] LPRASAUTODIALENTRYA unnamedParam3,
  [in, out] LPDWORD             unnamedParam4,
  [out]     LPDWORD             unnamedParam5
);

Parameters

[in] unnamedParam1

Pointer to a null-terminated string that specifies the address for which information is requested. This can be an IP address, Internet host name ("www.microsoft.com"), or NetBIOS name ("products1").

If this parameter is NULL, the function retrieves the default Internet connection. The function returns the per-user default Internet connection if one is configured. Otherwise, the function returns the global default Internet connection. If no default Internet connections are configured, the function returns zero for the lpdwcbAutoDialEntries and lpdwcAutoDialEntries parameters.

[in] unnamedParam2

Reserved; must be NULL.

[in, out] unnamedParam3

Pointer to a buffer that, on output, receives an array of RASAUTODIALENTRY structures, one for each AutoDial entry associated with the address specified by the lpszAddress parameter.

On input, set the dwSize member of the first RASAUTODIALENTRY structure in the buffer to sizeof(RASAUTODIALENTRY) to identify the version of the structure.

If lpAutoDialEntries is NULL, RasGetAutodialAddress sets the lpdwcbAutoDialEntries and lpdwcAutoDialEntries parameters to indicate the required buffer size, in bytes, and the number of AutoDial entries.

[in, out] unnamedParam4

Pointer to a variable that, on input, specifies the size, in bytes, of the lpAutoDialEntries buffer.

On output, this variable receives the number of bytes returned, or the number of bytes required if the buffer is too small.

[out] unnamedParam5

Pointer to a variable that receives the number of structure elements returned in the lpAutoDialEntries buffer.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes or a value from Routing and Remote Access Error Codes or Winerror.h.

Value	Meaning
ERROR_INVALID_SIZE	The dwSize member of the RASAUTODIALENTRY structure is an invalid value.
ERROR_INVALID_PARAMETER	The lpszAddress, lpdwcbAutoDialEntries, or lpdwcAutoDialEntries parameter was NULL.

Remarks

The Remote Access Service (RAS) supports default Internet connections. RAS supports a default Internet connection that is global to the local computer, and in addition, supports a default Internet connection for each user.

The name of the global default Internet connection is stored in the registry below the following registry key:

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Ras Autodial
            Default

The value that stores the name of the connection is:

DefaultInternet

This value is of type REG_SZ.

The global default Internet connection must be configured as a For all users connection in the Connections Folder user interface.

The name of the per-user default Internet connection is stored in the registry below the following registry key:

HKEY_CURRENT_USER\Software\Microsoft\Ras Autodial\Default

The value that stores the name of the connection is:

DefaultInternet

This value is of type REG_SZ.

Note

The ras.h header defines RasGetAutodialAddress as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ras.h
Library	Rasapi32.lib
DLL	Rasapi32.dll