RASENTRY Structure (Windows)

RASENTRY Structure

The RASENTRY structure describes a phone-book entry. The RasSetEntryProperties and RasGetEntryProperties functions use this structure to set and retrieve the properties of a phone-book entry.

Syntax

C++

typedef struct _RASENTRY {
  DWORD       dwSize;
  DWORD       dwfOptions;
  DWORD       dwCountryID;
  DWORD       dwCountryCode;
  TCHAR       szAreaCode[RAS_MaxAreaCode + 1];
  TCHAR       szLocalPhoneNumber[RAS_MaxPhoneNumber + 1];
  DWORD       dwAlternateOffset;
  RASIPADDR   ipaddr;
  RASIPADDR   ipaddrDns;
  RASIPADDR   ipaddrDnsAlt;
  RASIPADDR   ipaddrWins;
  RASIPADDR   ipaddrWinsAlt;
  DWORD       dwFrameSize;
  DWORD       dwfNetProtocols;
  DWORD       dwFramingProtocol;
  TCHAR       szScript[MAX_PATH];
  TCHAR       szAutodialDll[MAX_PATH];
  TCHAR       szAutodialFunc[MAX_PATH];
  TCHAR       szDeviceType[RAS_MaxDeviceType + 1];
  TCHAR       szDeviceName[RAS_MaxDeviceName + 1];
  TCHAR       szX25PadType[RAS_MaxPadType + 1];
  TCHAR       szX25Address[RAS_MaxX25Address + 1];
  TCHAR       szX25Facilities[RAS_MaxFacilities + 1];
  TCHAR       szX25UserData[RAS_MaxUserData + 1];
  DWORD       dwChannels;
  DWORD       dwReserved1;
  DWORD       dwReserved2;
  DWORD       dwSubEntries;
  DWORD       dwDialMode;
  DWORD       dwDialExtraPercent;
  DWORD       dwDialExtraSampleSeconds;
  DWORD       dwHangUpExtraPercent;
  DWORD       dwHangUpExtraSampleSeconds;
  DWORD       dwIdleDisconnectSeconds;
  DWORD       dwType;
  DWORD       dwEncryptionType;
  DWORD       dwCustomAuthKey;
  GUID        guidId;
  TCHAR       szCustomDialDll[MAX_PATH];
  DWORD       dwVpnStrategy;
  DWORD       dwfOptions2;
  DWORD       dwfOptions3;
  TCHAR       szDnsSuffix[RAS_MaxDnsSuffix];
  DWORD       dwTcpWindowSize;
  TCHAR       szPrerequisitePbk[MAX_PATH];
  TCHAR       szPrerequisiteEntry[RAS_MaxEntryName + 1];
  DWORD       dwRedialCount;
  DWORD       dwRedialPause;
  RASIPV6ADDR ipv6addrDns;
  RASIPV6ADDR ipv6addrDnsAlt;
  DWORD       dwIPv4InterfaceMetric;
  DWORD       dwIPv6InterfaceMetric;
  RASIPV6ADDR ipv6addr;
  DWORD       dwIPv6PrefixLength;
  DWORD       dwNetworkOutageTime;
}RASENTRY, *PRASENTRY;

Members

dwSize

Specifies the size, in bytes, of the RASENTRY structure. Before calling RasSetEntryProperties or RasGetEntryProperties, set dwSize to sizeof(RASENTRY) to identify the version of the structure.

dwfOptions

A set of bit flags that specify connection options. Set one or more of the following flags.

Note

You must clear all RASEO_RequiredXXX flags and the RASEO_Custom flag before setting RASEO_RequireEncryptedPw or RASEO_RequireMsEncryptedPw.

Flag	Meaning
RASEO_UseCountryAndAreaCodes	If this flag is set, the dwCountryID, dwCountryCode, and szAreaCode members are used to construct the phone number. If this flag is not set, these members are ignored. This flag corresponds to the Use Country and Area Codes check boxes in the Phone dialog box.
RASEO_SpecificIpAddr	If this flag is set, RAS tries to use the IP address specified by ipaddr as the IP address for the dial-up connection. If this flag is not set, the value of the ipaddr member is ignored. Currently, an IP address set in the phone-book entry properties or retrieved from a server overrides the IP address set in the network control panel.
RASEO_SpecificNameServers	If this flag is set, RAS uses the ipaddrDns, ipaddrDnsAlt, ipaddrWins, and ipaddrWinsAlt members to specify the name of the server addresses for the dial-up connection. If this flag is not set, RAS ignores these members.
RASEO_IpHeaderCompression	If this flag is set, RAS negotiates to use IP header compression on PPP connections. If this flag is not set, IP header compression is not negotiated. It is generally advisable to set this flag because IP header compression significantly improves performance. The flag should be cleared only when connecting to a server that does not correctly negotiate IP header compression.
RASEO_RemoteDefaultGateway	If this flag is set, the default route for IP packets is through the dial-up adapter when the connection is active. If this flag is clear, the default route is not modified. This flag corresponds to the Use default gateway on remote network check box in the TCP/IP settings dialog box.
RASEO_DisableLcpExtensions	If this flag is set, RAS disables the PPP LCP extensions defined in RFC 1570. This may be necessary to connect to certain older PPP implementations, but interferes with features such as server callback. Do not set this flag unless specifically required.
RASEO_TerminalAfterDial	If this flag is set, RAS displays a terminal window for user input after dialing the connection. Do not set this flag if a dial-up networking script is to be associated with the connection, because scripting has its own terminal implementation. This flag works only if this phone-book entry is dialed by the RasDialDlg function. This flag has no effect if the entry is dialed by the RasDial function.
RASEO_ModemLights	If this flag is set, a status monitor is displayed in the task bar.
RASEO_SwCompression	If this flag is set, software compression is negotiated on the link. Setting this flag causes the PPP driver to attempt to negotiate CCP with the server. This flag should be set by default, but clearing it can reduce the negotiation period if the server does not support a compatible compression protocol.
RASEO_RequireEncryptedPw	If this flag is set, only secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol to authenticate the client. The MD5-CHAP and SPAP authentication protocols are also supported. Clear this flag for increased interoperability, and set it for increased security. Setting RASEO_RequireEncryptedPw also sets RASEO_RequireSPAP, RASEO_RequireCHAP, RASEO_RequireMsCHAP, and RASEO_RequireMsCHAP2. This flag corresponds to the Require Encrypted Password check box in the Security dialog box. See also RASEO_RequireMsEncryptedPw.
RASEO_RequireMsEncryptedPw	If this flag is set, only the Microsoft secure password scheme, MSCHAP, can be used to authenticate the client with the server. This flag prevents the PPP driver from using the PPP plain-text authentication protocol (PAP), MD5-CHAP, or SPAP. See Also the following flags: RASEO_RequireMsCHAP, RASEO_RequireMsCHAP2, and RASEO_RequireW95MsCHAP. Setting RASEO_EncryptedMsPw also sets RASEO_RequireMsCHAP and RASEO_RequireMsCHAP2. This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also RASEO_RequireDataEncryption.
RASEO_RequireDataEncryption	If this flag is set, data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set. This flag corresponds to the Require Data Encryption check box in the Security dialog box.
RASEO_NetworkLogon	If this flag is set, RAS logs on to the network after the point-to-point connection is established.
RASEO_UseLogonCredentials	If this flag is set, RAS uses the user name, password, and domain of the currently logged-on user when dialing this entry. This flag is ignored unless RASEO_RequireMsEncryptedPw is also set. Note that this setting is ignored by the RasDial function, where specifying empty strings for the szUserName and szPassword members of the RASDIALPARAMS structure gives the same result. This flag corresponds to the Use Current Username and Password check box in the Security dialog box.
RASEO_PromoteAlternates	This flag has an effect when alternate phone numbers are defined by the dwAlternateOffset member. If this flag is set, an alternate phone number that connects successfully becomes the primary phone number, and the current primary phone number is moved to the alternate list. This flag corresponds to the check box in the Alternate Numbers dialog box. The successful number is moved to the top of the list.
RASEO_SecureLocalFiles	If this flag is set, RAS checks for existing remote file system and remote printer bindings before making a connection with this entry. Typically, set this flag is set on phone-book entries for public networks to remind users to break connections to their private network before connecting to a public network. If either Client for Microsoft Networks or File and Print Sharing is unchecked for a given connection, calling RasGetEntryProperties returns dwfOptions with RASEO_SecureLocalFiles set. Calling RasSetEntryProperties with RASEO_SecureLocalFiles set unchecks both Client for Microsoft Networks and File and Print Sharing; resetting the bit checks both items.
RASEO_RequireEAP	If this flag is set, an Extensible Authentication Protocol (EAP) must be supported for authentication.
RASEO_RequirePAP	If this flag is set, Password Authentication Protocol must be supported for authentication.
RASEO_RequireSPAP	If this flag is set, Shiva's Password Authentication Protocol must be supported for authentication.
RASEO_Custom	If this flag is set, the connection uses custom encryption.
RASEO_PreviewPhoneNumber	If this flag is set, the remote access dialer displays the phone number to be dialed.
RASEO_SharedPhoneNumbers	If this flag is set, all modems installed on the local computer share the same phone number. This option has no effect unless multiple modems are installed.
RASEO_PreviewUserPw	If this flag is set, the remote access dialer displays the user's name and password prior to dialing.
RASEO_PreviewDomain	If this flag is set, the remote access dialer displays the domain name prior to dialing.
RASEO_ShowDialingProgress	If this flag is set, the remote access dialer displays its progress in establishing the connection.
RASEO_RequireCHAP	If this flag is set, the Challenge Handshake Authentication Protocol must be supported for authentication.
RASEO_RequireMsCHAP	If this flag is set, the Microsoft Challenge Handshake Authentication Protocol must be supported for authentication.
RASEO_RequireMsCHAP2	If this flag is set, version 2 of the Microsoft Challenge Handshake Authentication Protocol must be supported for authentication.
RASEO_RequireW95MSCHAP	If this flag is set, RASEO_RequireMsCHAP must also be set and MS-CHAP must send the LanManager-hashed password.
RASEO_CustomScript	This flag must be set in order for RAS to invoke a custom-scripting DLL after establishing the connection to the server.

dwCountryID

Specifies the TAPI country/region identifier. Use the RasGetCountryInfo function to enumerate country/region identifiers. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.

dwCountryCode

Specifies the country/region code portion of the phone number. The country/region code must correspond to the country/region identifier specified by dwCountryID. If dwCountryCode is zero, the country/region code is based on the country/region identifier specified by dwCountryID. This member is ignored unless dwfOptions specifies the RASEO_UseCountryAndAreaCodes flag.

szAreaCode

Specifies the area code as a null-terminated string. If the dialing location does not have an area code, specify an empty string (""). Do not include parentheses or other delimiters in the area code string. For example, "206" is a valid area code; "(206)" is not. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.

szLocalPhoneNumber

Specifies a null-terminated device-type specific destination string. The following table describes the contents of the szLocalPhoneNumber member for various device types.

Device	szLocalPhoneNumber
RASDT_Modem	Telephone number.
RASDT_Atm	Virtual Path Identifier (VPI) and Virtual Channel Identifier (VCI) values of a permanent virtual circuit. Use the following format: p(vpi),(vci) Example: "P0,40"
RASDT_PPPoE	Service name.
RASDT_Vpn	DNS name, IPv4 address, or IPv6 address.

dwAlternateOffset

Specifies the offset, in bytes, from the beginning of the structure to a list of consecutive null-terminated strings. The last string is terminated by two consecutive null characters. The strings are alternate phone numbers that RAS dials in the order listed if the primary number (see szLocalPhoneNumber) fails to connect. The alternate phone number strings are ANSI or Unicode, depending on whether you use the ANSI or Unicode version of the structure.

You are not able to use the RAS API to set area codes or country/region codes for alternate phone numbers.

ipaddr

Specifies the IP address to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificIpAddr flag.

ipaddrDns

Specifies the IP address of the DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.

ipaddrDnsAlt

Specifies the IP address of a secondary or backup DNS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.

ipaddrWins

Specifies the IP address of the WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.

ipaddrWinsAlt

Specifies the IP address of a secondary WINS server to be used while this connection is active. This member is ignored unless dwfOptions specifies the RASEO_SpecificNameServers flag.

dwFrameSize

Specifies the network protocol frame size. The value should be either 1006 or 1500. This member is ignored unless dwFramingProtocol specifies the RASFP_Slip flag.

dwfNetProtocols

Specifies the network protocols to negotiate. This member can be a combination of the following flags.

Flag	Meaning
RASNP_Ipx	Negotiate the IPX protocol.
RASNP_Ip	Negotiate the TCP/IP protocol.
RASNP_Ipv6	Windows Vista or later: Negotiate the IPv6 protocol.

Windows 64-bit Edition: The RASNP_Ipx flag is not supported.

dwFramingProtocol

Specifies the framing protocol used by the server. PPP is the emerging standard. SLIP is used mainly in UNIX environments. This member can be one of the following flags.

Flag	Meaning
RASFP_Ppp	Point-to-Point Protocol (PPP).
RASFP_Slip	Serial Line Internet Protocol (SLIP).

To use Compressed SLIP, set the RASFP_Slip flag and set the RASEO_IpHeaderCompression flag in the dwfOptions member.

szScript

Specifies a null-terminated string that contains the name of the script file. The file name should be a full path. This field is only used for analog dial-up connections.

To indicate a SWITCH.INF script name, set the first character of the name to "[".

szAutodialDll

Windows 2000 or later: This member is no longer supported. The szCustomDialDll member of the RASENTRY structure specifies the path to the custom-dial DLL. For more information on custom dialers, see RAS Custom Dialers.

szAutodialFunc

Windows 2000 or later: This member is no longer supported. See RAS Custom Dialers for more information on custom dialers.

szDeviceType

Specifies a null-terminated string that indicates the RAS device type referenced by szDeviceName. This member can be one of the following string constants.

String	Meaning
RASDT_Modem	A modem accessed through a COM port.
RASDT_Isdn	An ISDN card with corresponding NDISWAN driver installed.
RASDT_X25	An X.25 card with corresponding NDISWAN driver installed.
RASDT_Vpn	A virtual private network connection. For more information, see VPN Connections.
RASDT_Pad	A Packet Assembler/Disassembler.
RASDT_Generic	Generic.
RASDT_Serial	Direct serial connection through a serial port.
RASDT_FrameRelay	Frame Relay.
RASDT_Atm	Asynchronous Transfer Mode (ATM).
RASDT_Sonet	Sonet.
RASDT_SW56	Switched 56K Access.
RASDT_Irda	Infrared Data Association (IrDA) compliant device.
RASDT_Parallel	Direct parallel connection through a parallel port.
RASDT_PPPoE	Point-to-Point Protocol over Ethernet. For more information, see PPPoE Connections.

szDeviceName

Contains a null-terminated string that contains the name of a TAPI device to use with this phone-book entry, for example, "XYZ Corp 28800 External". To enumerate all available RAS-capable devices, use the RasEnumDevices function.

szX25PadType

Contains a null-terminated string that identifies the X.25 PAD type. Set this member to "" unless the entry should dial using an X.25 PAD. The szX25PadType string maps to a section name in PAD.INF.

szX25Address

Contains a null-terminated string that identifies the X.25 address to which to connect . Set this member to "" unless the entry should dial using an X.25 PAD or native X.25 device.

szX25Facilities

Contains a null-terminated string that specifies the facilities to request from the X.25 host at connection. This member is ignored if szX25Address is an empty string ("").

szX25UserData

Contains a null-terminated string that specifies additional connection information supplied to the X.25 host at connection. This member is ignored if szX25Address is an empty string ("").

dwChannels

Reserved for future use.

dwReserved1

Reserved. Must be zero.

dwReserved2

Reserved. Must be zero.

dwSubEntries

Specifies the number of multilink subentries associated with this entry. When calling RasSetEntryProperties, set this member to zero. To add subentries to a phone-book entry, use the RasSetSubEntryProperties function.

dwDialMode

Specifies whether RAS should dial all of this entry's multilink subentries when the entry is first connected. This member can be one of the following values.

Value	Meaning
RASEDM_DialAll	Dial all subentries initially.
RASEDM_DialAsNeeded	Adjust the number of subentries as bandwidth is needed. RAS uses the dwDialExtraPercent, dwDialExtraSampleSeconds, dwDialHangUpExtraPercent, and dwHangUpExtraSampleSeconds members to determine when to dial or disconnect a subentry.

Windows 2000: In order for RAS to dial all subentries, dwDialMode must be set to RASEDM_DialAll and the dwSubEntry member of RASDIALPARAMS must be set to zero.

Windows XP: To dial the first available subentry, set dwDialMode to zero, and set the dwSubEntry member of RASDIALPARAMS to zero.

dwDialExtraPercent

Specifies a percent of the total bandwidth available from the currently connected subentries. RAS dials an additional subentry when the total bandwidth used exceeds dwDialExtraPercent percent of the available bandwidth for at least dwDialExtraSampleSeconds seconds.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwDialExtraSampleSeconds

Specifies the number of seconds that current bandwidth usage must exceed the threshold specified by dwDialExtraPercent before RAS dials an additional subentry.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwHangUpExtraPercent

Specifies a percent of the total bandwidth available from the currently connected subentries. RAS terminates (hangs up) an existing subentry connection when total bandwidth used is less than dwHangUpExtraPercent percent of the available bandwidth for at least dwHangUpExtraSampleSeconds seconds.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwHangUpExtraSampleSeconds

Specifies the number of seconds that current bandwidth usage must be less than the threshold specified by dwHangUpExtraPercent before RAS terminates an existing subentry connection.

This member is ignored unless the dwDialMode member specifies the RASEDM_DialAsNeeded flag.

dwIdleDisconnectSeconds

Specifies the number of seconds after which the connection is terminated due to inactivity. Note that unless the idle time out is disabled, the entire connection is terminated if the connection is idle for the specified interval. This member can specify a number of seconds, or one of the following values.

Value	Meaning
RASIDS_Disabled	There is no idle time out for this connection.
RASIDS_UseGlobalValue	Use the user preference value as the default.

dwType

The type of phone-book entry. This member can be one of the following types.

Type	Description
RASET_Phone	Phone line, for example, modem, ISDN, X.25.
RASET_Vpn	Virtual Private Network.
RASET_Direct	Direct serial or parallel connection. Windows Vista or later: This type is no longer supported.
RASET_Internet	Connection Manager (CM) connection. This value is reserved for system use.
RASET_Broadband	Windows XP or later: Broadband connections, e.g. Digital Subscriber Line (DSL).

Windows XP: To create a Point-to-Point Protocol over Ethernet (PPPoE) connection programmatically, use the RASET_Broadband entry type. For more information, see PPPoE Connections.

dwEncryptionType

The type of encryption to use with the connection. The encryption is either provided by IPSec (for L2TP/IPSec connections) or by Microsoft Point-to-Point Encryption (MPPE). This member can be one of the following values.

Value	Meaning
ET_None	No encryption.
ET_Require	Require encryption.
ET_RequireMax	Require maximum-strength encryption.
ET_Optional	Do encryption if possible. No encryption is okay.

The value of dwEncryptionType does not affect how passwords are encrypted. Whether passwords are encrypted and how passwords are encrypted is determined by the authentication protocol, such as, PAP, MS-CHAP, or EAP. However, if IPSec encryption is negotiated it will provide an additional layer of encryption for the authentication protocol.

dwCustomAuthKey

This member is used for Extensible Authentication Protocol (EAP). This member contains the authentication key provided to the EAP vendor.

guidId

The GUID (Globally Unique Identifier) that represents this phone-book entry. This member is read-only.

szCustomDialDll

A null-terminated string that contains the full path and file name for the dynamic link library (DLL) that implements the custom-dialing functions. This DLL should export Unicode versions of functions named RasCustomDial, RasCustomHangup, RasCustomEntryDlg, and RasCustomDialDlg. These functions should have prototypes RasCustomDialFn and RasCustomHangUpFn as defined in Ras.h, and RasCustomDialDlgFn and RasCustomEntryDlgFn as defined in Rasdlg.h.

dwVpnStrategy

The VPN strategy to use when dialing a VPN connection. This member can have one of the following values.

Value	Meaning
VS_Default	With this strategy, RAS dials Layer 2 Tunneling Protocol (L2TP) first. If L2TP fails, Point-to-Point Tunneling Protocol (PPTP) is attempted. Whichever protocol succeeds is tried first in subsequent dials for this entry.
VS_PptpOnly	RAS dials only PPTP.
VS_PptpFirst	RAS always dials PPTP first. Windows 7: RAS always dials PPTP first followed by Internet Key Exchange version (IKEv2), Secure Socket Tunneling Protocol (SSTP), then Layer 2 Tunneling Protocol (L2TP)
VS_L2tpOnly	RAS dials only L2TP.
VS_L2tpFirst	RAS always dials L2TP first. Windows 7: RAS always dials L2TP first followed by IKEv2, SSTP, then PPTP
VS_SstpOnly	Windows Vista with SP1 or later: RAS dials only SSTP.
VS_SstpFirst	Windows Vista with SP1 or later: RAS always dials SSTP first followed by IKEv2, PPTP, then L2TP.
VS_Ikev2Only	Windows 7: RAS dials only IKEv2.
VS_Ikev2First	Windows 7: RAS always dials IKEv2 first followed by SSTP, PPTP, then L2TP.

dwfOptions2