RasSetAutodialAddressA function (ras.h)
The RasSetAutodialAddress function can add an address to the AutoDial mapping database. Alternatively, the function can delete or modify the data associated with an existing address in the database.
Syntax
DWORD RasSetAutodialAddressA(
[in] LPCSTR unnamedParam1,
[in] DWORD unnamedParam2,
[in] LPRASAUTODIALENTRYA unnamedParam3,
[in] DWORD unnamedParam4,
[in] DWORD unnamedParam5
);
Parameters
[in] unnamedParam1
Pointer to a null-terminated string that specifies the address to add, delete, or modify. This address can be an IP address, Internet host name ("www.microsoft.com"), or NetBIOS name ("products1").
If this parameter is NULL, the function sets the default Internet connection (see Remarks). If this parameter points to a zero-length string, the function deletes the default Internet connection.
[in] unnamedParam2
Reserved; must be zero.
[in] unnamedParam3
Pointer to an array of one or more RASAUTODIALENTRY structures to be associated with the lpszAddress address. If lpAutoDialEntries is NULL and dwcbAutoDialEntries is zero, RasSetAutodialAddress deletes all structures associated with lpszAddress from the mapping database.
[in] unnamedParam4
Specifies the size, in bytes, of the lpAutoDialEntries buffer.
[in] unnamedParam5
Specifies the number of RASAUTODIALENTRY structures 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 |
|---|---|
|
The dwSize member of the RASAUTODIALENTRY structure is an invalid value. |
|
The lpszAddress parameter is NULL. |
|
The connection name specified in lpAutoDialEntries does not exist. |
Remarks
An address in the AutoDial mapping database can have any number of associated RASAUTODIALENTRY entries. Each entry specifies AutoDial information for a particular TAPI dialing location.
If the address specified by the lpszAddress parameter is an existing address in the database and the lpAutoDialEntries parameter is not NULL, the RasSetAutodialAddress function modifies the set of AutoDial entries associated with the address. If an entry in the lpAutoDialEntries array specifies a dialing location for which the address already has an entry, the function replaces the existing entry with the new entry. Otherwise, the function simply adds the lpAutoDialEntries entries to the set of entries for the address.
If the lpszAddress address exists in the database, lpAutoDialEntries is NULL, and lpAutoDialEntries is zero, RasSetAutodialAddress deletes the address from the database.
If the lpszAddress address does not exist in the database, RasSetAutodialAddress adds the address to the database. The lpAutoDialEntries parameter specifies the AutoDial entries to associate with the new address.
RAS supports a default Internet connection that is global to the local computer and supports a default Internet connection for each user.
When the lpszAddress parameter is NULL, and the lpAutoDialEntries parameter specifies a connection name with one entry, RasSetAutodialAddress sets the connection as the default internet connection. The connection name specified in lpAutoDialEntries should already exist. If it does not, ERROR_CANNOT_FIND_PHONEBOOK_ENTRY will be returned.
When the lpszAddress parameter is a zero-length string and the lpAutoDialEntries parameter specifies an empty connection name with one entry, RasSetAutodialAddress deletes the default internet connection.
On non-domain client machines, if a user wants to set a connection as the default internet connection and specifies a "for-all-users" connection in the szEntry member of the RASAUTODIALENTRY structure, then the default internet connection is set globally on the local computer. In all other cases the default internet connection is set for each user of the machine individually.
It is possible to have two connections that have the same name if one is configured as a "for-all-users" connection and the other is configured as a "for-me-only" connection. If the lpAutoDialEntries parameter specifies a connection name that corresponds to both a global and a per-user connection, the per-user connection is set.
Note
The ras.h header defines RasSetAutodialAddress 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 |