[RAS] Ras Structure

RAS Messages

The following table shows the RAS messages with a description of the purpose of each.

Programming element	Description
WM_RASDIALEVENT	This message is sent by the operating system (OS) to a window procedure when a change of state event occurs during a Remote Access Service (RAS) connection process and a window has been specified to handle notifications of such events by using the notifier parameter of RasDial.

 

WM_RASDIALEVENT

This message is sent by the operating system (OS) to a window procedure when a change of state event occurs during a Remote Access Service (RAS) connection process and a window has been specified to handle notifications of such events by using the notifier parameter of RasDial.

The two message parameters are equivalent to the parameters of the same names that are used with RasDialFunc and RasDialFunc1 callback functions.

WM_RASDIALEVENT rasconnstate = (RASCONNSTATE) wParam;

dwError = (DWORD) lParam;

Parameters

rasconnstate

Equivalent to the rasconnstate parameter of the RasDialFunc and RasDialFunc1 callback functions. This parameter specifies a RASCONNSTATE enumerator value that indicates the state that the RasDial RAS connection process is about to enter.

dwError

Equivalent to the dwError parameter of the RasDialFunc and RasDialFunc1 callback functions. A nonzero value indicates the error that has occurred and zero indicates that no error has occurred.

RasDial sends this message with dwError set to zero upon entry to each connection state. If an error occurs within a state, the message is sent again for the state, this time with a nonzero dwError value.

Return Values

An application should return TRUE if it processes this message.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winuser.h.

RAS Structures

The following table shows the RAS structures with a description of the purpose of each.

Programming element	Description
DIALER_NOTIFICATION	This structure defines a message queue created by a dialer application to pass messages to the AutoDial DLL (Autoras.dll).
RAS_STATS	This structure stores the statistics for a single-link RAS connection, or for one of the links in a multilink RAS connection.
RASCONN	This structure provides data about a remote access connection. The RasEnumConnections function returns an array of RASCONN structures.
RASCONNSTATUS	This structure describes the current status of a remote access connection. It is returned by the RasGetConnectStatus function.
RASDEVINFO	This structure contains information that describes a Telephony API (TAPI) device capable of establishing a RAS connection.
RASDIALPARAMS	This structure contains parameters used by the RasDial function to establish a remote access connection.
RASENTRY	This structure describes a phone-book entry.
RASENTRYNAME	This structure contains an entry name from a remote access phone book.
RASIPADDR	This structure contains an IP address.
RASPPPIP	This structure contains the result of a PPP IP projection operation.
RASPPPIPV6	This structure describes the results of a PPP IPV6 (Internet) projection.

 

DIALER_NOTIFICATION

This structure defines a message queue created by a dialer application to pass messages to the AutoDial DLL (Autoras.dll).

typedef struct {

  DWORD dwNotificationId;

  DWORD dwNotificationParam;

} DIALER_NOTIFICATION, PDIALER_NOTIFICATION;

Members

dwNotificationId

Identifies the message being passed. The following table shows the possible values.

Value	Description
DIALER_START	Informs the AutoDial DLL that the dialer application is starting.
DIALER_TERMINATE	Informs the AutoDial DLL that the dialer application is shutting down.

dwNotificationParam

Used to pass parameters, if any, that are required by the message being passed.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Autoras.h.

RAS_STATS

This structure stores the statistics for a single-link RAS connection, or for one of the links in a multilink RAS connection.

typedef struct _RAS_STATS {

  DWORD dwSize;

  DWORD dwBytesXmited;

  DWORD dwBytesRcved;

  DWORD dwFramesXmited;

  DWORD dwFramesRcved;

  DWORD dwCrcErr;

  DWORD dwTimeoutErr;

  DWORD dwAlignmentErr;

  DWORD dwHardwareOverrunErr;

  DWORD dwFramingErr;

  DWORD dwBufferOverrunErr;

  DWORD dwCompressionRatioIn;

  DWORD dwCompressionRatioOut;

  DWORD dwBps;

  DWORD dwConnectDuration;

} RAS_STATS, *PRAS_STATS;

Members

dwSize

Specifies the version of the structure. Set this member to sizeof (RAS_STATS) before using the structure in a function call.

dwBytesXmited

The number of bytes transmitted through this connection or link.

dwBytesRcved

The number of bytes received through this connection or link.

dwFramesXmited

The number frames transmitted through this connection or link.

dwFramesRcved

The number of frames received through this connection or link.

dwCrcErr

The number of cyclic redundancy check (CRC) errors on this connection or link.

dwTimeoutErr

The number of timeout errors on this connection or link.

dwAlignmentErr

The number of alignment errors on this connection or link.

dwHardwareOverrunErr

The number of hardware overrun errors on this connection or link.

dwFramingErr

The number of framing errors on this connection or link.

dwBufferOverrunErr

The number of buffer overrun errors on this connection or link.

dwCompressionRatioIn

The compression ratio for the data being received on this connection or link.

dwCompressionRatioOut

The compression ratio for the data being transmitted on this connection or link.

dwBps

The speed of the connection or link, in bits per second. This speed is negotiated at the time that the connection or link is established.

This speed is not equal to the throughput of the connection or link. To calculate the average throughput, divide the number of bytes transmitted (dwBytesXmited) and received (dwBytesRcved) by the amount of time the connection or link has been up (dwConnectDuration).

dwConnectDuration

The amount of time, in milliseconds, that the connection or link has been connected.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.

RASCONN

This structure provides data about a remote access connection. The RasEnumConnections function returns an array of RASCONN structures.

typedef struct _RASCONN {

  DWORD dwSize;

  HRASCONN hrasconn;

  TCHAR szEntryName[ RAS_MaxEntryName + 1 ];

} RASCONN;

Members

dwSize

Specifies the size, in bytes, of the RASCONN structure.

hrasconn

Handle to the remote access connection. This handle is used in other remote access API calls.

szEntryName

Null-terminated string that specifies the phone-book entry used to establish the remote access connection. If the connection was established using an empty entry name, this string consists of a period (.) followed by the connection phone number.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

RASCONNSTATUS

This structure describes the current status of a remote access connection. It is returned by the RasGetConnectStatus function.

typedef struct _RASCONNSTATUS {

  DWORD dwSize;

  RASCONNSTATE rasconnstate;

  DWORD dwError;

  TCHAR szDeviceType[ RAS_MaxDeviceType + 1 ];

  TCHAR szDeviceName[ RAS_MaxDeviceName + 1 ];

} RASCONNSTATUS;

Members

dwSize

Specifies the structure size, in bytes.

rasconnstate

Specifies a RASCONNSTATE enumerator value that indicates the current state of the RasDial connection process; that is, the piece of the RasDial process that is currently executing.

The following table shows the two state values that are especially significant.

Value	Description
RASCS_Connected	Indicates that the connection has been successfully established.
RASCS_Disconnected	Indicates that the connection has failed.

dwError

If nonzero, specifies the reason for failure. The value is one of the error values from the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or ERROR_INVALID_HANDLE.

szDeviceType

Null-terminated string that specifies the type of the current device, if available. For example, common device types supported by RAS are modem, pad, switch, isdn, and NULL.

szDeviceName

Null-terminated string that specifies the name of the current device, if available. This would be the name of the modem, for example, Hayes Smartmodem 2400; the name of the PAD, for example, US Sprint; or the name of a switch device, for example, Racal-Guardata.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

RASDEVINFO

This structure contains information that describes a Telephony API (TAPI) device capable of establishing a RAS connection. The RasEnumDevices function uses this structure to retrieve information about RAS-capable devices.

typedef struct tagRASDEVINFO {

  DWORD dwSize;

  CHAR szDeviceType[ RAS_MaxDeviceType + 1 ];

  CHAR szDeviceName[ RAS_MaxDeviceName + 1 ];

} RASDEVINFO;

Members

dwSize

Specifies the size, in bytes, of the RASDEVINFO structure. Before calling RasEnumDevices, set dwSize to sizeof(RASDEVINFO) to identify the version of the structure.

szDeviceType

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

String constant	Description
RASDT_Modem	A modem accessed through a COM port.
RASDT_Isdn	An ISDN card with the corresponding NDISWAN driver installed.
RASDT_X25	An X.25 card with the corresponding NDISWAN driver installed.
RASDT_Vpn	For Windows CE 3.0 and later, a virtual private network connection.
RASDT_Pad	A Packet Assembler/Disassembler.

szDeviceName

Specifies a null-terminated string containing the name of a TAPI device.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

RASDIALPARAMS

This structure contains parameters used by the RasDial function to establish a remote access connection.

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 ];

} RASDIALPARAMS;

Members

dwSize

Specifies the structure size, in bytes.

szEntryName

Null-terminated string that contains the phone-book entry to use to establish the connection. This member cannot be NULL.

szPhoneNumber

This parameter is ignored and should be set to NULL.

szCallbackNumber

This parameter is ignored and should be set to NULL.

szUserName

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

Null-terminated string that contains the user's password. This string is used to authenticate the user's access to the remote access server.

szDomain

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.

Remarks

The szCallbackNumber and szPhoneNumber members are ignored and should always be set to NULL.

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

When retrieving the password using the RasGetEntryDialParams function in Windows CE 3.0 or later, 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.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

RASENTRY

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.

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, 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 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 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 CE does not support the RASEO_TerminalBeforeDial and RASEO_TerminalAfterDial values for the dwfOptions member.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

 

RASENTRYNAME

This structure contains an entry name from a remote access phone book. The RasEnumEntries function returns an array of these structures.

typedef struct _RASENTRYNAME {

  DWORD dwSize;

  TCHAR szEntryName[ RAS_MaxEntryName + 1 ];

} RASENTRYNAME;

Members

dwSize

Specifies the structure size, in bytes.

szEntryName

Null-terminated string that contains the name of a remote access phone-book entry.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

 

RASIPADDR

This structure contains an IP address. It uses this structure to specify the IP addresses of various servers associated with an entry in a RAS phone book.

typedef struct RASIPADDR {

  BYTE a;

  BYTE b;

  BYTE c;

  BYTE d;

} RASIPADDR;

Members

a, b, c, and d

These members specify the value of the corresponding location in the a.b.c.d IP address.

Remarks

In Windows CE, the order of the a, b, c, and d members are transposed to d, c, b, and a. Use the htonl function to reverse the byte order.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

 

RASPPPIP

This structure contains the result of a PPP IP projection operation.

The RasGetProjectionInfo function returns a RASPPPIP structure when its rasprojection parameter has the value RASP_PppIp.

typedef struct _RASPPPIP {

  DWORD dwSize;

  DWORD dwError;

  TCHAR szIpAddress[ RAS_MaxIpAddress + 1 ];

} RASPPPIP;

Members

dwSize

Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to indicate the version of the RASPPPIP structure that you are using. For information about earlier versions of this structure, see the Remarks section.

dwError

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure and is the actual fatal error that occurred during the control protocol negotiation, which is the error that prevented the projection from completing successfully.

szIpAddress

Contains a null-terminated string that is the client's IP address on the RAS connection. This address string has the form a.b.c.d; for example, 11.101.237.71.

Remarks

To retrieve PPP IP information on Windows CE–based devices, dwSize must specify the size of the RASPPPIP structure without the szServerIpAddress member.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Ras.h.

 

RASPPPIPV6

This structure describes the results of a PPP IPV6 (Internet) projection. The RasGetProjectionInfo function returns a RASPPPIPV6 structure when its rasprojection parameter has the value RASP_PppIpv6.

#define RASPPPIPV6 struct tagRASPPPIPV6

RASPPPIPV6

{

  DWORD dwSize;

  DWORD dwError;

  BYTE LocalInterfaceIdentifier[8];

  BYTE PeerInterfaceIdentifier[8];

  BYTE LocalCompressionProtocol[2];

  BYTE PeerCompressionProtocol[2];

};

 

#define LPRASPPPIPV6 RASPPPIPV6*

Members

dwSize

Specifies the size of the structure, in bytes.

dwError

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure and is the actual fatal error that occurred during the control protocol negotiation, which is the error that prevented the projection from completing successfully.

LocalInterfaceIdentifier

Specifies the local interface identifier, in bytes.

PeerInterfaceIdentifier

Specifies the peer interface identifier, in bytes.

LocalCompressionProtocol

Specifies the local compression protocol, in bytes.

PeerCompressionProtocol

Specifies the peer compression protocol, in bytes.

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Ras.h.

 

Scripting Reference

This language reference section contains descriptions of scripting programming elements.

Scripting Functions

The following table shows the scripting functions with a description of the purpose of each.

Programming element	Description
RasCustomScriptExecute	This function must be exported by the custom-scripting dynamic-link library (DLL), which is implemented by the developer. RAS calls this function when establishing a connection, allowing the DLL to communicate with the server and thus customize the connection process.
RasFreeBuffer	This function releases a memory buffer that was allocated by a previous call to RasGetBuffer.
RasGetBuffer	This function allocates memory for sending or receiving data over the port connected to the server.
RasReceiveBuffer	This function informs RAS that it is ready to receive data from the server over the specified port.
RasRetrieveBuffer	This function obtains data received from the RAS server over the specified port.
RasSendBuffer	This function sends data to the server over the specified port.

 

RasCustomScriptExecute

This function must be exported by the custom-scripting dynamic-link library (DLL), which is implemented by the developer. RAS calls this function when establishing a connection, allowing the DLL to communicate with the server and thus customize the connection process.

DWORD RasCustomScriptExecute(

  HANDLE hPort,

  LPCWSTR lpszPhonebook,

  LPCWSTR lpszEntryName,

  PFNRASGETBUFFER pfnRasGetBuffer,

  PFNRASFREEBUFFER pfnRasFreeBuffer,

  PFNRASSENDBUFFER pfnRasSendBuffer,

  PFNRASRECEIVEBUFFER pfnRasReceiveBuffer,

  PFNRASRETRIEVEBUFFER pfnRasRetrieveBuffer,

  HWND hWnd,

  RASDIALPARAMS* pRasDialParams,

  RASCUSTOMSCRIPTEXTENSIONS* pRasCustomScriptExtensions

);

Parameters

hPort

[in] Handle to the port on which the connection is established. Use this handle when sending or receiving data on the port.

lpszPhonebook

[in] Not used. Value always equals NULL.

lpszEntryName

[in] Pointer to a Unicode string that contains the name of the entry that was dialed to establish the connection.

pfnRasGetBuffer

[in] Pointer to a function of type PFNRASGETBUFFER. The custom-scripting DLL should use this function to allocate memory to send data to the server.

pfnRasFreeBuffer

[in] Pointer to a function of type PFNRASFREEBUFFER. The custom-scripting DLL should use this function to free memory allocated by the pfnRasGetBuffer parameter.

pfnRasSendBuffer

[in] Pointer to a function of type PFNRASSENDBUFFER. The custom-scripting DLL uses this function to communicate with the server over the specified port.

pfnRasReceiveBuffer

[in] Pointer to a function of type PFNRASRECEIVEBUFFER. The custom-scripting DLL uses this function to communicate with the server over the specified port.

pfnRasRetrieveBuffer

[in] Pointer to a function of type PFNRASRETRIEVEBUFFER. The custom-scripting DLL uses this function to communicate with the server over the specified port.

hWnd

[in] Handle to a window that the custom-scripting DLL can use to present a user interface to the user.

pRasDialParams

[in] Pointer to a Unicode RASDIALPARAMS structure. This structure contains the authentication credentials for the user. The custom-scripting DLL can modify the szUserName, szPassword, and szDomain members of this structure. The Point-to-Point Protocol (PPP) will use whatever is stored in these members when RasCustomScriptExecute returns.

pRasCustomScriptExtensions

[in] Not used. Value always equals NULL.

Return Values

If the function succeeds, it should return ERROR_SUCCESS.

If the function fails, the return value should be an appropriate error code from Winerror.h or Raserror.h.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: RasCustomScriptExecute is exported from the custom-scripting DLL, and therefore is not defined in a header file.
Link Library: Developer-implemented.

 

RasFreeBuffer

This function releases a memory buffer that was allocated by a previous call to RasGetBuffer. A custom-scripting DLL, which is implemented by the developer, calls RasFreeBuffer through a function pointer. RAS passes the function pointer through the phnRasFreeBuffer parameter of the DLL's RasCustomScriptExecute function.

typedef DWORD (APIENTRY *PFNRASFREEBUFFER)(

  PBYTE pBuffer

);

Parameters

pBuffer

Pointer to the memory buffer to free. This memory must have been obtained by a previous call to RasGetBuffer.

Return Values

ERROR_SUCCESS

The function completes successfully.

ERROR_OUT_OF_BUFFERS

RAS cannot allocate more buffer space.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Ppp.lib.

 

RasGetBuffer

This function allocates memory for sending or receiving data over the port connected to the server. A custom-scripting DLL, which is implemented by the developer, calls RasGetBuffer through a function pointer. RAS passes the function pointer through the phnRasGetBuffer parameter of the DLL's RasCustomScriptExecute function.

typedef DWORD (APIENTRY *PFNRASGETBUFFER)(

  PBYTE* ppBuffer,

  PDWORD pdwSize

);

Parameters

ppBuffer

Pointer to a pointer that receives the address of the returned buffer.

pdwSize

Pointer to a DWORD variable that, on input, contains the requested size of the buffer. On output, this variable contains the actual size of the buffer allocated.

Return Values

ERROR_SUCCESS

The function was successful.

ERROR_BUFFER_INVALID

The pointer to the buffer passed in the ppBuffer parameter is invalid.

Remarks

The maximum buffer size that can be allocated is 1500 bytes.

The custom-scripting DLL calls RasGetBuffer through a function pointer.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Ppp.lib.

 

RasReceiveBuffer

This function informs RAS that it is ready to receive data from the server over the specified port. A custom-scripting DLL, which is implemented by the developer, calls RasReceiveBuffer through a function pointer. RAS passes the function pointer through the phnRasReceiveBuffer parameter of the DLL's RasCustomScriptExecute function.

typedef DWORD (APIENTRY *PFNRASRECEIVEBUFFER)(

  HANDLE hPort,

  PBYTE pBuffer,

  PDWORD pdwSize,

  DWORD dwTimeout,

  HANDLE hEvent

);

Parameters

hPort

Handle to the port on which to receive the data. This handle should be the handle passed in by RAS as the first parameter of the RasCustomScriptExecute function.

pBuffer

Pointer to a buffer to receive the data from the port specified by the hPort parameter. Obtain this buffer using the RasGetBuffer function.

pdwSize

Pointer to a DWORD variable that receives the size of the data returned in the buffer pointed to by the pBuffer parameter.

dwTimeout

Specifies a time-out period, in milliseconds, after which the custom-scripting DLL will no longer wait for the data.

hEvent

Handle to an event object that RAS will signal when the received data is available.

Return Values

ERROR_SUCCESS

The function completes successfully.

ERROR_BUFFER_INVALID

The pointer to the buffer passed in the pBuffer parameter is invalid. The handle specified by the hPort parameter is invalid.

ERROR_INVALID_PORT_HANDLE

The handle specified by the hPort parameter is invalid.

Remarks

RasReceiveBuffer is an asynchronous function. RasReceiveBuffer returns immediately even if the data is not yet available. The custom-scripting DLL must wait on the event object specified by the hEvent parameter. When the data is available, RAS signals this event. The custom-scripting DLL should then call the RasRetrieveBuffer function to obtain the data. The custom-scripting DLL can pass the same buffer pointer in RasRetrieveBuffer that it passed in RasReceiveBuffer.

RAS also signals the event object if, for some reason, the port is disconnected before the data is posted. In this case, RasRetrieveBuffer returns an error defined in Raserror.h that indicates the cause of the failure.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Ppp.lib.

RasRetrieveBuffer

This function obtains data received from the RAS server over the specified port. A custom-scripting DLL, which is implemented by the developer, calls RasRetrieveBuffer through a function pointer. RAS passes the function pointer through the phnRasReceiveBuffer parameter of the DLL's RasCustomScriptExecute function.

typedef DWORD (APIENTRY *PFNRASRETRIEVEBUFFER)(

  HANDLE hPort,

  PBYTE pBuffer,

  PDWORD pdwSize

);

Parameters

hPort

Handle to the port on which to retrieve the data. This handle should be the handle passed in by RAS as the first parameter of the RasCustomScriptExecute function.

pBuffer

Pointer to a buffer to receive the data from the port specified by the hPort parameter. Obtain this buffer using the RasGetBuffer function. The value of this parameter may be the same as the pointer to the buffer passed into the RasReceiveBuffer function.

pdwSize

Pointer to a DWORD variable that receives the size of the data returned in the buffer pointed to by the pBuffer parameter.

Return Values

ERROR_SUCCESS

The function completes successfully.

ERROR_BUFFER_INVALID

The pointer to the buffer passed in the pBuffer parameter is invalid.

ERROR_INVALID_PORT_HANDLE

The handle specified by the hPort parameter is invalid.

RAS signals the event object if the port gets disconnected for some reason before the data is posted. In this case, RasRetrieveBuffer returns an error defined in Raserror.h that indicates the cause of the failure.

Remarks

The RasRetrieveBuffer function is synchronous. When it returns, the buffer pointed to by the pBuffer parameter contains the data received over the specified port. The custom-scripting DLL should call RasRetrieveBuffer only after RAS has signaled the event object that the DLL passed the call to RasReceiveBuffer.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Ppp.lib.

RasSendBuffer

This function sends data to the server over the specified port. A custom-scripting DLL, which is implemented by the developer, calls RasSendBuffer through a function pointer. RAS passes the function pointer through the phnRasSendBuffer parameter of the DLL's RasCustomScriptExecute function.

typedef DWORD (APIENTRY *PFNRASSENDBUFFER)(

  HANDLE hPort,

  PBYTE pBuffer,

  PDWORD dwSize

);

Parameters

hPort

Handle to the port on which to send the data. This handle should be the handle passed in by RAS as the first parameter of the RasCustomScriptExecute function.

pBuffer

Pointer to a buffer of data to send over the port specified by the hPort parameter. Obtain this buffer using RasGetBuffer function.

dwSize

Specifies the size of the buffer pointed to by the pBuffer parameter.

Return Values

ERROR_SUCCESS

The function completes successfully.

ERROR_BUFFER_INVALID

The pointer to the buffer passed in the pBuffer parameter is invalid.

ERROR_INVALID_PORT_HANDLE

The handle specified by the hPort parameter is invalid.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Ppp.lib.