Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

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 Embedded CE, RasDialalways uses the default behaviors for the RASDIALEXTENSIONSoptions.

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 RASDIALPARAMSstructure that specifies calling parameters for the RAS connection.

The caller must set the RASDIALPARAMSstructure's dwSizemember to the sizeof(RASDIALPARAMS)to identify the version of the structure being passed.

NotifierType

Specifies the nature of the notifierparameter. If notifieris NULL, NotifierTypeis ignored. If notifieris not NULL, set NotifierTypeto the following value.

Value Description

0xFFFFFFFF 0xFFFFFFFF

The notifierparameter is a handle to a window to receive progress notification messages. In a progress notification message, wParamindicates the connection state (rasconnstate) which the RAS connection is about to enter, while lParamindicates whether or not an error occurred.

The progress notification message uses the WM_RASDIALEVENT message code.
notifier

Pointer to a window handle to receive RasDialevent notifications. If this parameter is not NULL, RasDialsends the window a message for each RasDialevent. Additionally, the RasDialcall operates asynchronously: RasDialreturns immediately, before the connection is established, and uses the window to communicate its progress.

If notifieris NULL, the RasDialcall operates synchronously: RasDialdoes not return until the connection attempt has completed successfully or failed.

If notifieris 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, dwErroris nonzero.

  • RasHangUpis 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 HRASCONNvariable to NULL before calling RasDial. If RasDialsucceeds, it stores a handle to the RAS connection into pRasConn.

Return Value

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 szCallBackNumberand szPhoneNumbermembers of the structure pointed to by rasDialParamare not used and should be set to NULL.

RasDialwill 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 RasHangUpto hang up the connection.

An application must eventually call RasHangUpwhenever a non-NULL connection handle is stored into pRasConn. This applies even if RasDialreturns a nonzero (error) value.

An application can call RasHangUpfrom a RasDialnotifier 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 PostMessagefunction. PostMessageis 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

Header ras.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also