RasSetAutodialAddress function

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 RasSetAutodialAddress(
  _In_  LPCTSTR lpszAddress,
  _In_  DWORD dwReserved,
  _In_  LPRASAUTODIALENTRY lpAutoDialEntries,
  _In_  DWORD dwcbAutoDialEntries,
  _In_  DWORD dwcAutoDialEntries
);

Parameters

lpszAddress [in]

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.

dwReserved [in]

Reserved; must be zero.

lpAutoDialEntries [in]

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.

dwcbAutoDialEntries [in]

Specifies the size, in bytes, of the lpAutoDialEntries buffer.

dwcAutoDialEntries [in]

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.

ValueMeaning
ERROR_INVALID_SIZE

The dwSize member of the RASAUTODIALENTRY structure is an invalid value.

ERROR_INVALID_PARAMETER

The lpszAddress parameter is NULL.

ERROR_CANNOT_FIND_PHONEBOOK_ENTRY

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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Ras.h

Library

Rasapi32.lib

DLL

Rasapi32.dll

Unicode and ANSI names

RasSetAutodialAddressW (Unicode) and RasSetAutodialAddressA (ANSI)

See also

Remote Access Service (RAS) Overview
Remote Access Service Functions
RASAUTODIALENTRY
RasEnumAutodialAddresses
RasGetAutodialAddress

 

 

Community Additions

ADD
Show:
© 2014 Microsoft