RasDial (Windows Embedded CE 6.0)

1/6/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, 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 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 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 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

See Also

Reference

RAS Functions
RasGetConnectStatus
RasHangUp
RASDIALPARAMS
WM_RASDIALEVENT