RASDIALPARAMS structure

The RASDIALPARAMS structure contains parameters that are used by RasDial to establish a remote access connection.

Syntax

typedef struct _RASDIALPARAMS {
  DWORD     dwSize;
  TCHAR     szEntryName[RAS_MaxEntryName + 1];
  TCHAR     szPhoneNumber[RAS_MaxPhoneNumber + 1];
  TCHAR     szCallbackNumber[RAS_MaxCallbackNumber + 1];
  TCHAR     szUserName[UNLEN + 1];
  TCHAR     szPassword[PWLEN + 1];
  TCHAR     szDomain[DNLEN + 1];
  DWORD     dwSubEntry;
  ULONG_PTR dwCallbackId;
  DWORD     dwIfIndex;
} RASDIALPARAMS, *PRASDIALPARAMS;

Members

• dwSize
  A value that specifies the size, in bytes, of the structure.

• szEntryName
  A null-terminated string that contains the phone-book entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port, in which case a non-empty szPhoneNumber must be provided.

  The callback number is no longer stored in the registry. Specifying an asterisk for szCallbackNumber causes RAS to return error 704: ERROR_BAD_CALLBACK_NUMBER.

• szPhoneNumber
  A null-terminated string that contains an overriding phone number. An empty string ("") indicates that the phone-book entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".

• szCallbackNumber
  A null-terminated string that contains a callback phone number. An empty string ("") indicates that callback should not be used. This string is ignored unless the user has "Set By Caller" callback permission on the RAS server. An asterisk indicates that the number stored in the phone book should be used for callback.

• szUserName
  A null-terminated string that contains the user's user name. This string is used to authenticate the user's access to the remote access server.

• szPassword
  A null-terminated string that contains the user's password. This string is used to authenticate the user's access to the remote access server.

  Use szPassword to send a new password to the remote server when you restart a RasDial connection from a RASCS_PasswordExpired paused state.

  When retrieving the password using the RasGetEntryDialParams function, the szPassword member does not receive the actual password. Instead, szPassword receives a handle to the saved password. Substitute this handle for the saved password in calls to RasSetEntryDialParams, and RasDial. When presented with this handle, RasDial retrieves and uses the saved password. The value of this handle may change in future versions of the operating system; do not develop code that depends on the contents or format of this value.

• szDomain
  A null-terminated string that contains the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phone book for the entry.

• dwSubEntry
  A value that specifies the index of the initial subentry to dial. If the dial mode is RASEDM_DialAsNeeded, RAS dials this subentry. If dwSubEntry is not a valid subentry index, RAS dials the first subentry.

  If the dial mode of the phone-book entry is RASEDM_DialAll, dwSubEntry is ignored. If the phone-book entry has no subentries, dwSubEntry is ignored.

  The subentry indexes are one-based. That is, the first subentry has an index of one, the second subentry as an index of two, and so on.

  The RASENTRY structure returned by RasGetEntryProperties indicates the dial mode (dwDialMode) and number of subentries (dwSubEntries) for the phone-book entry.

  If dwSubEntry specifies a valid subentry index, RAS dials the specified subentry regardless of the dial mode. If the dial mode is RASEDM_DialAll and dwSubEntry is zero, RAS dials all of the subentries.

• dwCallbackId
  Specifies an application-defined value that RAS passes to the RasDialFunc2 callback function.

• dwIfIndex
  A value that specifies the interface index on top of which the Virtual Private Network (VPN) connection will be dialed.

  Note  Supported in Windows 7 and later versions of Windows.

   

Remarks

The szUserName and szPassword strings are used to authenticate the user's access to the remote access server.

RAS does not actually log the user onto the network. The user does this in the usual manner, for example, by logging on with cached credentials prior to making the connection, or by using CTRL+ALT+DEL after the RAS connection is established.

If both the szUserName and szPassword members are empty strings (""), RAS uses the user name and password of the current logon context for authentication. For a user-mode application, RAS uses the credentials of the currently logged-on interactive user. For a service process, RAS uses the credentials associated with the service.

Requirements

Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Ras.h
Unicode and ANSI names	RASDIALPARAMSW (Unicode) and RASDIALPARAMSA (ANSI)

See also

Remote Access Service (RAS) Overview

Remote Access Service Structures

RasDial

RasGetEntryProperties

RasGetEntryDialParams

RasSetEntryDialParams

RASENTRY