RAS Functions
The following table shows the RAS functions with a description of the purpose of each.
|
Programming element |
Description |
|
This function deletes an entry from the phone book. | |
|
This function is used to display the configuration dialog for the device-specific settings of a RAS device. | |
|
This function establishes a RAS connection between a RAS client and a RAS server. | |
|
This function lists all active RAS connections. | |
|
This function returns the name and type of all available RAS-capable devices. | |
|
This function lists all entry names in a remote access phone book. | |
|
This function retrieves information on the current status of the specified remote access connection. | |
|
This function obtains the displayable phone number to be used in a dial-up connection. | |
|
This function retrieves the connection information saved by the last successful call to the RasDial function for a specified phone book entry. | |
|
This function retrieves connection-specific Extensible Authentication Protocol (EAP) information. | |
|
This function retrieves user-specific Extensible Authentication Protocol (EAP) information for the specified phone-book entry. | |
|
This function retrieves the properties of a phone book entry. | |
|
This function retrieves accumulated statistics for the specified link in a RAS multilink connection. | |
|
This function obtains information about a remote access projection operation for a specified remote access component protocol. | |
|
This function terminates a remote access connection. | |
|
This function changes the name of an entry in the phone book. | |
|
This function changes the connection information saved by the last successful call to the RasDial or RasGetEntryDialParams function for a specified phone book entry. | |
|
This function stores connection-specific Extensible Authentication Protocol (EAP) information. | |
|
This function stores user-specific Extensible Authentication Protocol (EAP) information for the specified phone-book entry in the registry. | |
|
This function changes the connection information for an entry in the phone book or creates a new phone-book entry. | |
|
This function validates the format of a connection entry name. |
RasDeleteEntry
This function deletes an entry from the phone book.
DWORD RasDeleteEntry(
LPWSTR lpszPhonebook,
LPWSTR lpszEntry
);
Parameters
lpszPhonebook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
lpszEntry
Pointer to a null-terminated string that contains the name of an existing entry to be deleted.
Return Values
Zero indicates success. A nonzero RAS error code indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasDevConfigDialogEdit
This function is used to display the configuration dialog for the device-specific settings of a RAS device.
DWORD RasDevConfigDialogEdit(
LPCWSTR szDeviceName,
LPCWSTR szDeviceType,
HWND hWndOwner,
LPVOID lpDeviceConfigIn,
DWORD dwSize,
LPVARSTRING lpDeviceConfigOut
);
Parameters
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
[in] 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 lineInitialize function.
hWndOwner
[in] Handle to a window to which the dialog box is attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpDeviceConfigIn
[in] Pointer to a buffer that contains device-specific configuration information. This is opaque TAPI device configuration information. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmer's Reference.
dwSize
[in] The size (in bytes) of the lpDeviceConfigIn buffer, which is a device specific structure opaque to the caller.
lpDeviceConfigOut
[in, out] Pointer to a buffer that is used to return the modified device-specific configuration information.
· Before calling RasDevConfigDialogEdit, the structure's dwTotalSize field must be set to the total size of the buffer. The buffer's total size includes the size of the VARSTRING structure, and the size of the space that follows the structure. The space that follows the structure is used to return the device-specific configuration information.
· If STATUS_SUCCESS is returned, but dwNeededSize is greater than dwTotalSize, then the provided buffer was not large enough to return the device-configuration information. Attempt the call again using a new buffer, with dwTotalSize set to at least dwNeededSize bytes.
· If STATUS_SUCCESS is returned and dwNeededSize is not greater than dwTotalSize, then the returned device-specific configuration information is lpDeviceConfigOut->dwStringSize bytes at (PBYTE)lpDeviceConfigOut + lpDeviceConfigOut->dwStringOffset.
Return Values
Returns 0 if successful, otherwise, a non-zero error code is returned.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasDial
This function establishes a RAS connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.
DWORD RasDial(
LPRASDIALEXTENSIONS dialExtensions,
LPTSTR phoneBookPath,
LPRASDIALPARAMS rasDialParam,
DWORD NotifierType,
LPVOID notifier,
LPHRASCONN pRasConn
);
Parameters
dialExtensions
This parameter is ignored and should be set to NULL. On Windows CE, RasDial always uses the default behaviors for the RASDIALEXTENSIONS options.
phoneBookPath
This parameter should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
rasDialParam
Pointer to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.
The caller must set the RASDIALPARAMS structure's dwSize member to the sizeof(RASDIALPARAMS) to identify the version of the structure being passed.
NotifierType
Specifies the nature of the notifier parameter. If notifier is NULL, NotifierType is ignored. If notifier is not NULL, set NotifierType to the following value.
|
Value |
Description |
|
0xFFFFFFFF |
The notifier parameter is a handle to a window to receive progress notification messages. In a progress notification message, wParam indicates the connection state (rasconnstate) which the RAS connection is about to enter, while lParam indicates whether or not an error occurred. The progress notification message uses the WM_RASDIALEVENT message code. |
notifier
Pointer to a window handle to receive RasDial event notifications. If this parameter is not NULL, RasDial sends the window a message for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and uses the window to communicate its progress.
If notifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.
If notifier is not NULL, notifications to the window can occur at any time after the initial call to RasDial. Notifications end when one of the following events occurs:
· The connection is established. In other words, the RAS connection state is RASCS_Connected.
· The connection fails. In other words, dwError is nonzero.
· RasHangUp is called on the connection.
The callback notifications are made in the context of a thread captured during the initial call to RasDial.
pRasConn
Pointer to a variable of type HRASCONN. You must set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into pRasConn.
Return Values
Zero indicates success. In addition, the function stores a handle to the RAS connection into the variable pointed to by pRasConn. A nonzero error value, either from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY, indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Remarks
The szCallBackNumber and szPhoneNumber members of the structure pointed to by rasDialParam are not used and should be set to NULL.
RasDial will not automatically display the logon dialog box. This is currently done through the Network and Dial-up Connections application. Applications are responsible for getting the information from the user.
Errors that occur after the immediate return can be detected by RasGetConnectStatus. Data is available until an application calls RasHangUp to hang up the connection.
An application must eventually call RasHangUp whenever a non-NULL connection handle is stored into pRasConn. This applies even if RasDial returns a nonzero (error) value.
An application can call RasHangUp from a RasDial notifier handler. If this is done, however, the hangup does not occur until the routine returns.
The window handle-based notification only works if the underlying configuration supports the PostMessage function. PostMessage is exposed through the msgque component, which is a part of the GWES module. Event notification through a window handle can only work if GWES is part of the underlying configuration.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasEnumConnections
This function lists all active RAS connections. It returns each connection's handle and phone book entry name.
DWORD RasEnumConnections(
LPRASCONN lprasconn,
LPDWORD lpcb,
LPDWORD lpcConnections
);
Parameters
lprasconn
Long pointer to a buffer that receives an array of RASCONN structures, one for each RAS connection. Before calling the function, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.
lpcb
Long pointer to a variable that that contains the size, in bytes, of the buffer specified by lprasconn. On return, the function sets this variable to the number of bytes required to enumerate the RAS connections.
lpcConnections
Long pointer to a variable that the function sets to the number of RASCONN structures written to the buffer specified by lprasconn.
Return Values
Zero indicates success. A nonzero error value listed in the RAS header file, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasEnumDevices
This function returns the name and type of all available RAS-capable devices.
DWORD RasEnumDevices(
LPRASDEVINFOW lpRasDevinfo,
LPDWORD lpcb,
LPDWORD lpcDevices
);
Parameters
lpRasDevinfo
Long pointer to a buffer that receives an array of RASDEVINFO structures, one for each RAS-capable device. Before calling the function, set the dwSize member of the first RASDEVINFO structure in the buffer to sizeof(RASDEVINFO) to identify the version of the structure.
lpcb
Long pointer to a variable that contains the size, in bytes, of the lpRasDevInfo buffer. On return, the function sets this variable to the number of bytes required to enumerate the devices.
lpcDevices
Long pointer to a variable that the function sets to the number of RASDEVINFO structures written to the lpRasDevinfo buffer.
Return Values
Zero indicates success. A nonzero error value indicates failure. Valid error codes (as defined in Raserror.h) include: ERROR_BUFFER_TOO_SMALL.
Requirements
OS Versions: Windows CE 3.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasEnumEntries
This function lists all entry names in a remote access phone book.
DWORD RasEnumEntries(
LPWSTR Reserved,
LPWSTR lpszPhoneBookPath,
LPRASENTRYNAME lprasentryname,
LPDWORD lpcb,
LPDWORD lpcEntries
);
Parameters
Reserved
Reserved; set to NULL.
lpszPhoneBookPath
This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
lprasentryname
Pointer to a buffer that receives an array of RASENTRYNAME structures, one for each phone-book entry. Before calling the function, an application must set the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) in order to identify the version of the structure being passed.
lpcb
Pointer to a variable that that contains the size, in bytes, of the buffer specified by lprasentryname. On return, the function sets this variable to the number of bytes required to successfully complete the call.
lpcEntries
Pointer to a variable that the function, if successful, sets to the number of phone-book entries written to the buffer specified by lprasentryname.
Return Values
Zero indicates success. A nonzero error value listed in the RAS header file, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Remarks
The following sample code enumerates the RAS phonebook entries on the current machine. The code initially calls RasEnumEntries to obtain the size of the buffer to pass in. The code then calls RasEnumEntries again, to enumerate the entries. Note that for both calls, the code sets the dwSize member of the first RASENTRY structure in the buffer to sizeof(RASENTRY) to specify the structure version.
lprasentryname = (LPRASENTRYNAME)LocalAlloc(LPTR, sizeof(RASENTRYNAME));
lprasentryname->dwSize = sizeof(RASENTRYNAME);
if ((nRet = RasEnumEntries(NULL, NULL, lprasentryname, &cb, &cEntries))
== ERROR_BUFFER_TOO_SMALL)
{
lprasentryname = (LPRASENTRYNAME)LocalAlloc(LPTR, cb);
lprasentryname->dwSize = sizeof(RASENTRYNAME);
}
// Calling RasEnumEntries to enumerate the phonebook entries
nRet = RasEnumEntries(NULL, NULL, lprasentryname, &cb, &cEntries);
if (nRet != ERROR_SUCCESS)
{
printf("RasEnumEntries failed: Error %d\n", nRet);
}
else
{
printf("Phone book entries in the default phonebook:\n\n");
for(i=0;i < cEntries;i++)
{
printf("%s\n",lprasentryname->szEntryName);
lprasentryname++;
}
}
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasGetConnectStatus
This function retrieves information on the current status of the specified remote access connection. An application can use this call to determine when an asynchronous RasDial call has completed.
DWORD RasGetConnectStatus(
HRASCONN rasconn,
LPRASCONNSTATUS lprasconnstatus
);
Parameters
rasconn
Handle to the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial or RasEnumConnections.
lprasconnstatus
Pointer to a RASCONNSTATUS structure that the function fills with status information. Before calling the function, an application must set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.
Return Values
Zero indicates success. A nonzero error value listed in the RAS header file, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasGetDispPhoneNum
This function obtains the displayable phone number to be used in a dial-up connection.
RasGetDispPhoneNum(
LPCWSTR szPhonebook,
LPCWSTR szEntry,
LPWSTR szPhoneNum,
DWORD dwPhoneNumLen
);
Parameters
szPhonebook
This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
szEntry
Null-terminated string that specifies an existing entry name.
szPhoneNum
Specifies the phone number.
dwPhoneNumLen
Specifies the length of the phone number in bytes.
Return Values
Returns zero (0) if successful, otherwise, a non-zero error code is returned.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasGetEapConnectionData
This function retrieves connection-specific Extensible Authentication Protocol (EAP) information.
DWORD RasGetEapConnectionData(
LPCTSTR pszPhonebook,
LPCTSTR pszEntry,
PBYTE pbEapData,
PDWORD pdwSizeofEapData
);
Parameters
pszPhonebook
[in] This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
pszEntry
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.
pbEapData
[out] Pointer to a buffer that receives the retrieved EAP data for the user. The caller should allocate the memory for this buffer. If the buffer is not large enough, RasGetEapConnectionData will return ERROR_BUFFER_TOO_SMALL, and the pdwSizeofEapData parameter will contain the required size.
pdwSizeofEapData
[in, out]Pointer to a DWORD variable that, on input, specifies the size of the buffer pointed to by the pbEapData parameter.
If the buffer specified by the pbEapData parameter is not large enough, pdwSizeofEapData receives, on output, the required size.
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes.
|
Value |
Description |
|
E_INVALIDARG |
The pdwSizeofEapData parameter is NULL. |
|
ERROR_BUFFER_TOO_SMALL |
The buffer pointed to by pbEapData is too small to receive the data. The pdwSizeofEapData contains the required size. |
|
ERROR_CANNOT_OPEN_PHONEBOOK |
RasGetEapConnectionData was unable to open the specified phone-book file. |
|
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY |
RasGetEapConnectionData was unable to find the specified entry in the phone book. |
|
Other |
Use FormatMessage to retrieve the system error message that corresponds to the error code returned. |
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib
RasGetEapUserData
This function retrieves user-specific Extensible Authentication Protocol (EAP) information for the specified phone-book entry.
DWORD RasGetEapUserData(
HANDLE hToken,
LPCTSTR pszPhonebook,
LPCTSTR pszEntry,
PBYTE pbEapData,
PDWORD pdwSizeofEapData
);
Parameters
hToken
[in] This parameter should always be NULL for Windows CE.
pszPhonebook
[in] This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
pszEntry
[in] Pointer to a null-terminated string that specifies an existing entry name.
pbEapData
[out] Pointer to a buffer that receives the retrieved EAP data for the user. The caller should allocate the memory for this buffer. If the buffer is not large enough, RasGetEapUserData will return ERROR_BUFFER_TOO_SMALL, and the pdwSizeofEapData parameter will contain the required size.
pdwSizeofEapData
[in/out]Pointer to a DWORD variable that, on input, specifies the size of the buffer pointed to by the pbEapData parameter.
If the buffer specified by the pbEapData parameter is not large enough, pdwSizeofEapData receives, on output, the required size.
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes.
|
Value |
Description |
|
E_INVALIDARG |
The pdwSizeofEapData parameter is NULL. |
|
ERROR_BUFFER_TOO_SMALL |
The buffer pointed to by pbEapData is too small to receive the data. The pdwSizeofEapData contains the required size. |
|
ERROR_CANNOT_OPEN_PHONEBOOK |
RasGetEapUserData was unable to open the specified phone-book file. |
|
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY |
RasGetEapUserData was unable to find the specified entry in the phone book. |
|
Other |
Use FormatMessage to retrieve the system error message that corresponds to the error code returned. |
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib
RasGetEntryDialParams
This function retrieves the connection information saved by the last successful call to the RasDial function for a specified phone book entry.
DWORD RasGetEntryDialParams(
LPWSTR lpszPhoneBook,
LPRASDIALPARAMS lpRasDialParams,
LPBOOL lpfPassword
);
Parameters
lpszPhoneBook
This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
lpRasDialParams
Pointer to a RASDIALPARAMS structure. On input, the dwSize member must specify the size of the RASDIALPARAMS structure, and the szEntryName member must specify a valid phone-book entry. On output, the structure receives the connection parameters associated with the specified phone-book entry.
Note that the szPhoneNumber member of the structure does not receive the phone number associated with the phone-book entry. To get the phone number associated with a phone-book entry, call the RasGetEntryProperties function.
lpfPassword
Pointer to a flag that indicates whether the function retrieved the password associated with the user name for the phone-book entry. The function sets this flag to TRUE if the user's password was returned in the szPassword member of the RASDIALPARAMS structure pointed to by lpRasDialParams.
Return Values
Zero indicates success. ERROR_BUFFER_INVALID indicates that the lpRasDialParams or lpfPassword pointer is invalid, or the lpRasDialParams buffer is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.
Include Raserror.h for definitions of the RAS error codes.
Remarks
The szCallBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.
When the dwSize member of the RASDIALPARAMS structure, which is pointed to by the lpRasDialParams parameter, is uninitialized or set to an incorrect value, the RasGetEntryDialParams function fails and returns a misleading error value, ERROR_CANNOT_FIND_PHONEBOOK_ENTRY.
Note This function requires that a plain text password is provided, but it does not return a plain text password. Therefore only trusted applications should be allowed to make calls to RasGetEntryDialParams.
To provide a networking environment with enhanced security, Windows CE-based devices should include the functionality for a power-on password. Users are strongly encouraged to use the power-on password feature to prevent unauthorized users from searching for stored passwords on the device.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasGetEntryProperties
This function retrieves the properties of a phone book entry.
DWORD RasGetEntryProperties(
LPWSTR lpszPhoneBook,
LPWSTR szEntry,
LPRASENTRY lpbEntry,
LPDWORD lpdwEntrySize,
LPBYTE lpb,
LPDWORD lpdwSize
);
Parameters
lpszPhoneBook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
szEntry
Pointer to a null-terminated string that contains an existing entry name. If you specify an empty string, "", the function returns default values in the buffers pointed to by the lpbEntry and lpb parameters.
lpbEntry
Pointer to a RASENTRY structure followed by additional bytes for the alternate phone number list, if there is one. The structure receives the connection data associated with the phone-book entry specified by the szEntry parameter. Before calling the function, set the dwSize member of the structure to sizeof(RASENTRY) to identify the version of the structure. Calling RasGetEntryProperties without specifying a RASENTRY structure returns an error.
lpdwEntrySize
Pointer to a variable that that contains the size, in bytes, of the lpbEntry buffer. On return, the function sets this variable to the number of bytes required.
lpb
Long pointer to a buffer that receives device-specific configuration information. This is opaque TAPI device configuration information that you should not manipulate directly. This parameter can be NULL. For more information about TAPI device configuration, see the lineGetDevConfig function in the Microsoft Win32® Telephony (TAPI) Programmer's Reference.
lpdwSize
Long pointer to a variable that that contains the size, in bytes, of the buffer specified by the lpb parameter. On return, the function sets this variable to the number of bytes required. This parameter can be NULL if the lpb parameter s NULL.
To determine the required buffer size, call RasGetEntryProperties with lpb set to NULL and lpdwSize set to a buffer size such as the 128 bytes required for unimodem. The function returns the required buffer size in lpdwSize.
Return Values
Zero indicates success. ERROR_INVALID_PARAMETER indicates that the function was called with an invalid parameter. ERROR_INVALID_SIZE indicates that the value of the dwSize member of the structure specified in lpbEntry is too small. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpbEntry is invalid. ERROR_BUFFER_TOO_SMALL indicates that the buffer size indicated in lpdwEntrySize is too small. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or is missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.
Include Raserror.h for definitions of the RAS error codes.
Note If the buffer specified in the lpb parameter is too small, RasGetEntryProperties does not return any error. Instead the function assumes that you are trying to determine the size of the buffer and will change the lpdwSize parameter to reflect the number of bytes that are required to return the RASENTRY structure.
Remarks
For Windows CE 2.0 and later, device configuration information can be retrieved by using the lpb and lpdwSize parameters. For Windows CE 1.0 and 1.01, the lpb and lpdwSize parameters are ignored and should be set to NULL.
RasGetEntryProperties can be used to get device specfic configuration information. The proper way to use this API to get that information is to first call the API to determine the buffer size needed and then call again to get the dev config struct.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasGetLinkStatistics
This function retrieves accumulated statistics for the specified link in a RAS multilink connection.
DWORD RasGetLinkStatistics(
HRASCONN hRasConn,
DWORD dwSubEntry,
RAS_STATS* lpStatistics
);
Parameters
hRasConn
Handle to the connection. Use RasDial or RasEnumConnections to obtain this handle.
dwSubEntry
Specifies the subentry that corresponds to the link for which to retrieve statistics.
lpStatistics
Pointer to a RAS_STATS structure to receive the statistics. Set the dwSize member of this structure to sizeof(RAS_STATS) before calling RasGetLinkStatistics. This parameter cannot be NULL.
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes.
|
Value |
Description |
|
E_INVALID_ARG |
At least one of the following is true: the hRasConn parameter is zero, the dwSubEntry parameter is zero, the lpStatistics parameter is NULL, or the value specified by the dwSize member of the RAS_STATS structure specifies a version of the structure that is not supported by the operating system in use. |
|
ERROR_NOT_ENOUGH_MEMORY |
The function could not allocate sufficient memory to complete the operation. |
|
Other |
Use FormatMessage to retrieve the system error message that corresponds to the error code returned. |
Requirements
OS Versions: Windows CE 3.0 and later.
Header: Ras.h.h.
Link Library: Coredll.lib.
RasGetProjectionInfo
This function obtains information about a remote access projection operation for a specified remote access component protocol.
DWORD RasGetProjectionInfo(
HRASCONN hrasconn,
RASPROJECTION rasprojection,
LPVOID lpprojection,
LPDWORD lpcb
);
hrasconn
[in] Handle to the remote access connection of interest. An application obtains a RAS connection handle from the RasDial or RasEnumConnections function.
rasprojection
[in] A RASPROJECTION enumerated type value that specifies the protocol of interest.
lpprojection
[out] Long pointer to a buffer that will receive the information specified by the rasprojection parameter. The information will be in a structure appropriate to the rasprojection value.
|
Rasprojection value |
Data structure |
Definition |
|
RASP_PppIp |
Specifies the IP control protocol. IPCP is a PPP network control protocol used to negotiate the parameters necessary to ship IP packets on a WAN link. |
lpcb
[in, out] Long pointer to a variable that, on entry, specifies the size in bytes of the buffer pointed to by lpprojection. ON exit, this variable contains the size of buffer needed to contain the specified projection information.
Return Values
Zero indicates success. A nonzero error value indicates failure. The function may return a nonzero RAS error code, or one of the following error codes.
|
Value |
Description |
|
ERROR_BUFFER_TOO_SMALL |
The buffer pointed to by lpprojection is not large enough to contain the requested information. |
|
ERROR_INVALID_HANDLE |
The hrasconn parameter is not a valid handle. |
|
ERROR_INVALID_PARAMETER |
One of the parameters is invalid. |
|
ERROR_PROTOCOL_NOT_CONFIGURED |
The control protocol for which information was requested neither succeeded nor failed, because the connection's phone-book entry did not require that an attempt to negotiate the protocol be made. This is a RAS error code. |
Remarks
The remote access projection process negotiates network protocol-specific information between a remote access server and a remote client. A remote access server uses this network protocol-specific information to represent a remote client on the network.
Requirements
OS Versions: Windows CE 3.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasHangUp
This function terminates a remote access connection. The connection is specified with a RAS connection handle. RasHangUp releases all RASAPI32.DLL resources associated with the handle.
DWORD RasHangUp(
HRASCONN Session
);
Parameters
Session
Handle to the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.
Return Values
Zero indicates success. A nonzero error value listed in the RAS header file or ERROR_INVALID_HANDLE indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Remarks
The connection is terminated even if the RasDial call has not yet been completed.
After this call, the Session handle can no longer be used.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasRenameEntry
This function changes the name of an entry in the phone book.
DWORD RasRenameEntry(
LPWSTR lpszPhonebook,
LPWSTR lpszOldEntry,
LPWSTR lpszNewEntry
);
Parameters
lpszPhonebook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
lpszOldEntry
Pointer to a null-terminated string that contains an existing entry name.
lpszNewEntry
Pointer to a null-terminated string that contains the new entry name. Before calling RasRenameEntry, call the RasValidateEntryName function to validate the new entry name.
Return Values
Zero indicates success. ERROR_INVALID_NAME indicates that the lpszNewEntry name is invalid. ERROR_ALREADY_EXISTS indicates that an entry with the lpszNewEntry name already exists. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phone-book entry does not exist.
Include Raserror.h for definitions of the RAS error codes.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasSetEapConnectionData
This function stores connection-specific Extensible Authentication Protocol (EAP) information.
DWORD RasSetEapConnectionData (
LPCTSTR pszPhonebook,
LPCTSTR pszEntry,
PBYTE pbEapData,
PDWORD pdwSizeofEapData
);
Parameters
pszPhonebook
[in] This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
pszEntry
[in] Pointer to a null-terminated string that specifies the full path of the phone-book (PBK) file. If this parameter is NULL, the function will use the system phone book.
pbEapData
[in] Pointer to a buffer that receives the retrieved EAP data for the user. The caller should allocate the memory for this buffer. If the buffer is not large enough, RasSetEapConnectionData will return ERROR_BUFFER_TOO_SMALL, and the pdwSizeofEapData parameter will contain the required size.
pdwSizeofEapData
[in] Pointer to a DWORD variable that specifies the size of the buffer pointed to by the pbEapData parameter.
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
|
Value |
Description |
|
E_INVALIDARG |
The pdwSizeofEapData parameter is NULL. |
|
ERROR_BUFFER_TOO_SMALL |
The buffer pointed to by pbEapData is too small to receive the data. The pdwSizeofEapData contains the required size. |
|
ERROR_CANNOT_OPEN_PHONEBOOK |
RasGetEapConnectionData was unable to open the specified phone-book file. |
|
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY |
RasGetEapConnectionData was unable to find the specified entry in the phone book. |
|
Other |
Use FormatMessage to retrieve the system error message that corresponds to the error code returned. |
If the function fails, the return value is one of the following error codes.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasSetEapUserData
This function stores user-specific Extensible Authentication Protocol (EAP) information for the specified phone-book entry in the registry.
DWORD RasSetEapUserData(
HANDLE hToken,
LPCTSTR pszPhonebook,
LPCTSTR pszEntry,
BYTE* pbEapData,
DWORD dwSizeofEapData
);
Parameters
hToken
[in] This parameter is ignored and should be set to NULL.
pszPhonebook
[in] This parameter is ignored and should be set to NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.
pszEntry
[in] Pointer to a null-terminated string that specifies an existing entry name.
pbEapData
[in] Pointer to the data to store for the user.
dwSizeofEapData
[in] Specifies the size of the data pointed to by the pbEapData parameter.
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes.
|
Value |
Definition |
|
E_INVALIDARG |
The dwSizeofEapData parameter is zero, or the pbEapData parameter is NULL. |
|
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY |
RasSetEapUserData was unable to find the specified entry in the phone book. |
|
ERROR_CANNOT_OPEN_PHONEBOOK |
RasSetEapUserData was unable to open the specified phone-book file. |
|
Other |
Use FormatMessage to retrieve the system error message that corresponds to the error code returned. |
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasSetEntryDialParams
This function changes the connection information saved by the last successful call to the RasDial or RasGetEntryDialParams function for a specified phone book entry.
DWORD RasSetEntryDialParams(
LPWSTR lpszPhoneBook,
LPRASDIALPARAMS lpRasDialParams,
BOOL fRemovePassword
);
Parameters
lpszPhoneBook
This parameter is ignored and should be set to NULL. Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.
lpRasDialParams
|
Member |
Description |
|
dwSize |
Specifies the sizeof(RASDIALPARAMS) to identify the version of the structure. |
|
szEntryName |
Null-terminated string that identifies the phonebook entry to set parameters for. |
|
szPhoneNumber |
Not used; set to NULL. |
|
szCallbackNumber |
Not used; set to NULL. |
|
szUserName |
Null-terminated string that contains the logon name of the user associated with this entry. If szUserName is an empty string, the user name is not changed. |
|
szPassword |
Null-terminated string that contains the password for the user specified by szUserName. If szUserName is an empty string, the password is not changed. If szPassword is an empty string and fRemovePassword is FALSE, the password is set to the empty string. If fRemovePassword is TRUE, the password stored in this phonebook entry for the user specified by szUserName is removed regardless of the that contains of the szPassword string. |
|
szDomain |
Null-terminated string that contains the name of the domain to log on to. If szDomain is an empty string, the domain name is not changed. |
Pointer to a RASDIALPARAMS structure that contains the connection parameters to be associated with the phonebook entry. RasSetEntryDialParams uses the structure's members as follows.
fRemovePassword
Boolean value that specifies whether to remove the phonebook entry's stored password for the user specified by lpRasDialParams->szUserName. If fRemovePassword is TRUE, the password is removed.
Return Values
Zero indicates success. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpRasDialParams is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phonebook is corrupted or missing components. ERROR_CANNOT_FIND_PHONEBOOK_ENTRY indicates that the phonebook entry does not exist.
Include Raserror.h for definitions of the RAS error codes.
Remarks
The szCallBackNumber and szPhoneNumber members of lpRasDialParams are not used and should be set to NULL.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasSetEntryProperties
This function changes the connection information for an entry in the phone book or creates a new phone-book entry.
DWORD RasSetEntryProperties(
LPWSTR lpszPhoneBook,
LPWSTR szEntry,
LPRASENTRY lpbEntry,
DWORD dwEntrySize,
LPBYTE lpb,
DWORD dwSize
);
Parameters
lpszPhoneBook
This parameter is ignored and should be set to NULL. Phonebook entries are stored in the registry rather than in a phone-book file.
szEntry
Pointer to a null-terminated string that contains an entry name.
If the entry name matches an existing entry, RasSetEntryProperties modifies the properties of that entry.
If the entry name does not match an existing entry, RasSetEntryProperties creates a new phone-book entry. For new entries, call the RasValidateEntryName function to validate the entry name before calling RasSetEntryProperties.
lpbEntry
Pointer to a RASENTRY structure that that contains the new connection data to be associated with the phone-book entry specified by the szEntry parameter.
The structure might be followed by an array of null-terminated alternate phone number strings. The last string is terminated by two consecutive null characters. The dwAlternateOffset member of the RASENTRY structure that contains the offset to the first string.
dwEntrySize
Specifies the size, in bytes, of the buffer specified by the lpRasEntry parameter.
lpb
Pointer to a buffer that contains device-specific configuration information. This is opaque TAPI device configuration information. For more information about TAPI device configuration, see the lineGetDevConfig function in the Win32 Telephony (TAPI) Programmer's Reference.
dwSize
Specifies the size, in bytes, of the lpb buffer.
Return Values
Zero indicates success. ERROR_BUFFER_INVALID indicates that the address or buffer specified by lpbEntry is invalid. ERROR_CANNOT_OPEN_PHONEBOOK indicates that the phone book is corrupted or missing components.
Include Raserror.h for definitions of the RAS error codes.
Remarks
For Windows CE 1.0 and 1.01, the lpb and dwSize parameters are ignored and should be set to NULL.
For Windows CE 2.0 and later, device configuration information can be set by using lpb and dwSize parameters.
Windows CE does not use the alternate phone number list.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.
RasValidateEntryName
This function validates the format of a connection entry name. It must contain at least one non-white-space alpha-numeric character.
DWORD RasValidateEntryName(
LPWSTR lpszPhonebook,
LPWSTR lpszEntry
);
Parameters
lpszPhonebook
This parameter is ignored and should be set to NULL. Phone-book entries are stored in the registry rather than in a phone-book file.
lpszEntry
Pointer to a null-terminated string that contains an entry name. For Windows CE, the entry name must include at least one alphanumeric character and be a valid registry key name. The entry name cannot begin with a backslash ("\").
|
Character |
Description |
|
| |
vertical bar |
|
> |
greater than symbol |
|
< |
less than symbol |
|
? |
question mark |
|
* |
asterisk |
|
\ |
backward slash |
|
/ |
forward slash |
|
: |
colon |
Note The entry name must begin with a backquote (`) to appear in the ActiveSync user interface.
Return Values
Zero indicates success. ERROR_INVALID_NAME or ERROR_ALREADY_EXISTS indicates failure.
Include Raserror.h for definitions of the RAS error codes.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Ras.h.
Link Library: Coredll.lib.