RASENTRY

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This 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

typedef_struct_RASENTRY {
  DWORD dwSize;
  DWORD dwfOptions;
  DWORD dwCountryID;
  DWORD dwCountryCode;
  TCHAR szAreaCode[ RAS_MaxAreaCode + 1 ];
  TCHAR szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
  DWORD dwAlternatesOffset;
  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 dwCustomAuthKey;
} RASENTRY;

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
  Specifies connection options. It can be one or more of the values shown in the following table.

  Value	Description
  RASEO_CustomScript	For Windows CE .NET 4.0 ,this flag must be set for RAS to invoke a custom-scripting DLL after establishing the connection to the server.
  RASEO_DialAsLocalCall	For Windows CE 2.10 and later,if this flag is set, RAS constructs the phone number as a local call, including the area code if it is different from the area code at the current location. This flag corresponds to the force local option in various dialog boxes. > [!NOTE] > If a user has selected the force local option when setting up a dial-up connection, RAS will dial the specified number, including the area code, without using the region code 1 as a prefix.
  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 it interferes with features such as server callback. Do not set this flag unless specifically required.
  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. This flag corresponds to the Use IP Header Compression check box in the TCP/IP Settings dialog box. 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_ModemLights	This flag is currently ignored.
  RASEO_NetworkLogon	If this flag is set, RAS logs on to the network after the point-to-point connection is established.
  RASEO_PreviewUserPw	If this flag is set, RAS will display a username and password dialog box before dialing.
  RASEO_ProhibitCHAP	If this flag is set to 1, the use of the Challenge Handshake Authentication Protocol (CHAP) authentication method is disabled. If this flag is set to zero (0), the client can negotiate the use of the CHAP authentication method with the server.
  RASEO_ProhibitEAP	If this flag is set to 1, the use of the Extensible Authentication Protocol (EAP) authentication method is disabled. If this flag is set to zero (0), the client can negotiate the use of the EAP authentication method with the server.
  RASEO_ProhibitMsCHAP	If this flag is set to 1, the use of the Microsoft Challenge Handshake Authentication Protocol (MSCHAP) authentication method is disabled. If this flag is set to zero (0), the client can negotiate the use of the MSCHAP authentication method with the server.
  RASEO_ProhibitMsCHAP2	If this flag is set to 1, the use of the Microsoft Challenge Handshake Authentication Protocol version 2.0 (MSCHAPv2) authentication method is disabled. If this flag is set to zero (0), the client can negotiate the use of the MSCHAPv2 authentication method with the server.
  RASEO_ProhibitPAP	If this flag is set to 1, the use of the Password Authentication Protocol (PAP) authentication method is disabled. If the flag is set to zero (0), then the client can negotiate the use of the PAP authentication method with the server.
  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.
  RASEO_RemoteDefaultGateway	If this flag is set, the TCP/IP route table will be modified so that the default route of that RAS connection will be chosen in preference to the existing default routes.
  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_RequireEncryptedPw	If this flag is set, only password schemes that provide enhanced security can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plaintext authentication protocol to authenticate the client. The CHAP and SPAP authentication protocols are also supported. Clear this flag for increased interoperability, and set it for enhanced security. 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 CHAP password scheme can be used to authenticate the client with the server. This prevents the PPP driver from using the PPP plaintext authentication protocol or MD5-CHAP. The flag should be cleared for maximum interoperability and should be set for the highest level of security. This flag takes precedence over RASEO_RequireEncryptedPw. This flag corresponds to the Require Microsoft Encrypted Password check box in the Security dialog box. See also RASEO_RequireDataEncryption.
  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. Setting the RASEO_SpecificIpAddr flag corresponds to selecting the Specify an IP Address setting in the TCP/IP Settings dialog box. Clearing the RASEO_SpecificIpAddr flag corresponds to selecting the Server Assigned IP Address setting in the TCP/IP Settings dialog box. 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 server addresses for the dial-up connection. If this flag is not set, RAS ignores these members. Setting the RASEO_SpecificNameServers flag corresponds to selecting the Specify Name Server Addresses setting in the TCP/IP Settings dialog box. Clearing the RASEO_SpecificNameServers flag corresponds to selecting the Server Assigned Name Server Addresses setting in the TCP/IP Settings dialog box.
  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_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/Region and Area Codes check box in the Phone dialog box.
  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.

• dwCountryID
  Specifies the TAPI country/region identifier. This member is currently ignored by Windows Embedded CE.

• dwCountryCode
  Specifies the country/region code portion of the phone number. This member is ignored unless the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag.

• szAreaCode
  Null-terminated string that contains the area code. 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
  Null-terminated string that contains a telephone number. The way RAS uses this string depends on if the dwfOptions member specifies the RASEO_UseCountryAndAreaCodes flag. If the flag is set, RAS combines szLocalPhoneNumber with the country/region and area codes specified by the dwCountryID, dwCountryCode, and szAreaCode members. If the flag is not set or if the RASEO_DialAsLocalCall flag is set, RAS uses the szLocalPhoneNumber string as the entire phone number.

• dwAlternatesOffset
  Not supported. Should be set to 0.

• ipaddr
  Specifies the IP address to be used while this connection is active. This member is ignored unless the dwfOptions member 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 the dwfOptions member 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 the dwfOptions member 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 the dwfOptions member 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 the dwfOptions member 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 the dwFramingProtocol member specifies the RASFP_Slip flag.

• dwfNetProtocols
  Specifies the network protocols to negotiate. The following flag is supported.

  Value	Description
  RASNP_Ip	Negotiate the TCP/IP protocol.

• 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.

  Value	Description
  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 containing the name of the script file. The file name should be a full path.

• szAutoDialDll
  Specifies a null-terminated string containing the full path and file name of the dynamic-link library (DLL) for the customized AutoDial handler. If szAutodialDll contains an empty string (""), RAS uses the default dialing user interface and the szAutodialFunc member is ignored.

• szAutoDialFunc
  Specifies a null-terminated string containing the exported name of the RASADFunc function for the customized AutoDial handler. An AutoDial DLL must provide both ANSI and Unicode versions of the RASADFunc handler. However, do not include the A or W suffix in the name specified by szAutodialFunc.

• szDeviceType
  Null-terminated string that indicates the RAS device type referenced by szDeviceName. This member is one of the following string constants.

  String constant	Description
  RASDT_Modem	A modem accessed through a COM port.
  RASDT_Direct	A direct serial connection.
  RASDT_Vpn	A connection through a virtual private network (VPN).

• szDeviceName
  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 the number of 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.

• szX25Address
  Contains a null-terminated string that identifies the X.25 address to connect to. 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
  Number specifying the number of channels supported by the device, where 1 is mono, 2 is stereo, and so on.

• dwReserved1
  Reserved; set to zero.

• dwReserved2
  Reserved; set to zero.

• dwCustomAuthKey
  Specifies the EAP extension type to be used.

Remarks

On Windows Embedded CE, the dwCountryID member is ignored, and the dwCountryCode member must be set to the correct country/region code for the phone number of the entry.

Windows Embedded CE does not support the RASEO_TerminalBeforeDial and RASEO_TerminalAfterDial values for the dwfOptions member.

Requirements

See Also

Reference

RasSetEntryProperties
RasEnumDevices

Other Resources