UID

title

description

helpviewer_keywords

old-location

tech.root

ms.assetid

ms.date

ms.keywords

req.header

req.include-header

req.target-type

req.target-min-winverclnt

req.target-min-winversvr

req.kmdf-ver

req.umdf-ver

req.ddi-compliance

req.unicode-ansi

req.idl

req.max-support

req.namespace

req.assembly

req.type-library

req.lib

req.dll

req.irql

targetos

req.typenames

req.redist

ms.custom

f1_keywords

dev_langs

topic_type

api_type

api_location

api_name

NF:ras.RasDialA

RasDialA function (ras.h)

The RasDial function establishes a RAS connection between a RAS client and a RAS server. The connection data includes callback and user-authentication information. (ANSI)

0

1

2

RasDialA

ras/RasDialA

rras\rasdial.htm

RRAS

579a9038-8216-4948-a065-fd45b97da73a

12/05/2018

0, 1, 2, RasDial, RasDial function [RAS], RasDialA, RasDialW, _ras_rasdial, ras/RasDial, ras/RasDialA, ras/RasDialW, rras.rasdial

ras.h

Windows

Windows 2000 Professional [desktop apps only]

Windows 2000 Server [desktop apps only]

RasDialW (Unicode) and RasDialA (ANSI)

Rasapi32.lib

Rasapi32.dll

Windows

19H1

RasDialA

ras/RasDialA

c++

APIRef

kbSyntax

DllExport

Rasapi32.dll

Ext-MS-Win-ras-rasapi32-l1-1-0.dll

Ext-MS-Win-ras-rasapi32-l1-1-1.dll

RasDial

RasDialA

RasDialW

RasDialA function

-description

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

-parameters

-param unnamedParam1 [in]

Pointer to a RASDIALEXTENSIONS structure that specifies a set of RasDial extended features to enable. Set this parameter to NULL if there is not a need to enable these features.

-param unnamedParam2 [in]

Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

-param unnamedParam3 [in]

Pointer to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection. Use the RasGetEntryDialParams function to retrieve a copy of this structure for a particular phone-book entry.

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

If the szPhoneNumber member of the RASDIALPARAMS structure is an empty string, RasDial uses the phone number stored in the phone-book entry.

-param unnamedParam4 [in]

Specifies the nature of the lpvNotifier parameter. If lpvNotifier is NULL, dwNotifierType is ignored. If lpvNotifier is not NULL, set dwNotifierType to one of the following values.

Value	Meaning
0	The lpvNotifier parameter points to a RasDialFunc callback function.
1	The lpvNotifier parameter points to a RasDialFunc1 callback function.
2	The lpvNotifier parameter points to a RasDialFunc2 callback function.

-param unnamedParam5 [in]

Specifies a window handle or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function to receive RasDial event notifications. The dwNotifierType parameter specifies the nature of lpvNotifier. Please refer to its description preceding for further detail.

If this parameter is not NULL, RasDial sends the window a message, or calls the callback function, for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and communicates its progress via the window or callback function.

If lpvNotifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.

If lpvNotifier is not NULL, notifications to the window or callback function 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.

-param unnamedParam6 [out]

Pointer to a variable of type HRASCONN. Set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into *lphRasConn.

-returns

If the function succeeds, the return value is ERROR_SUCCESS and a handle to the RAS connection is returned in the variable pointed to by lphRasConn.

If the function fails, the return value is from Routing and Remote Access Error Codes or Winerror.h.

-remarks

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 *lphRasConn. This applies even if RasDial returns a nonzero (error) value.

An application can safely call RasHangUp from a RasDial notifier callback function. If this is done, however, the hang-up does not occur until the routine returns.

If the structure pointed to by lpRasDialExtensions enables RDEOPT_PausedStates, the RasDial function pauses whenever it enters a state in which the RASCS_PAUSED bit is set to one. To restart RasDial from such a paused state, call RasDial again, passing the connection handle returned from the original RasDial call in *lphRasConn. The same notifier used in the original RasDial call must be used when restarting from a paused state.

The lpvNotifier parameter is a handle to a window to receive progress notification messages. In a progress notification message, wParam is the equivalent of the rasconnstate parameter of RasDialFunc and RasDialFunc1, and lParam is the equivalent of the dwError parameter of RasDialFunc and RasDialFunc1.

The progress notification message uses a system registered message code. You can obtain the value of this message code as follows:

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS supports referenced connections. If the entry being dialed is already connected, RasDial returns SUCCESS and the connection is referenced. To disconnect the connection, each RasDial on the connection should be matched by a RasHangUp.

Because some phone-book entries require Extensible Authentication Protocol (EAP) for authentication, the caller should call RasGetEapUserIdentity before calling RasDial. If RasGetEapUserIdentity returns ERROR_INVALID_FUNCTION_FOR_ENTRY, the phone-book entry does not require EAP. However, if RasGetEapUserIdentity returns NO_ERROR, the caller should copy the EAP identity information from RasGetEapUserIdentity into the RasEapInfo member of RASDIALEXTENSIONS, and the szUserName member of RASDIALPARAMS. See RasGetEapUserIdentity for more information. If the phone-book entry requires EAP, the dwfOptions member of the RASENTRY structure for the entry contains the RASEO_RequireEAP flag.

To specify that RasDial should enter a RASCS_CallbackSetByCaller state, set lpRasDialParams->szCallbackNumber to "*" on the initial call to RasDial. When the notification handler is called with this state, set the callback number to a number supplied by the user.

Note

The ras.h header defines RasDial as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.