RasDial

This function establishes a RAS connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.

At a Glance

Header file:	Ras.h
Windows CE versions:	1.0 and later

Syntax

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.

pphoneBook

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.

rasDialParams

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 parameterIf notifier is NULL, NotifierType is ignored. If notifier is not NULL, set NotifierType to the following value:

Value	Description
0xFFFFFFFF 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 notificationsIf this parameter is not NULL, RasDial sends the window a 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.

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 Remote Networking application. Applications are responsible for getting the information from the user.

Windows CE does not support the ERROR_CANNOT_FIND_PHONEBOOK_ENTRY return value.

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 safely call RasHangUp from a RasDial notifier handler. If this is done, however, the hangup does not occur until the routine returns.