RasDial
The RasDial
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 lpRasDialExtensions, |
// pointer to
function extensions data |
|
LPTSTR lpszPhonebook, |
// pointer to full
path and filename of phone-book file |
|
LPRASDIALPARAMS lpRasDialParams, |
// pointer to
calling parameters data |
|
DWORD dwNotifierType, |
// specifies type
of RasDial event handler |
|
LPVOID lpvNotifier, |
// specifies a
handler for RasDial events |
|
LPHRASCONN lphRasConn |
// pointer to
variable to receive connection handle |
|
); |
|
Parameters
lpRasDialExtensions
Windows
NT:
Points to a RASDIALEXTENSIONS structure that specifies a
set of RasDial extended features to enable. If you do not need to enable
any of the extensions, set this parameter to NULL.
Windows
95:
This
parameter is ignored. On Windows 95, RasDial always uses the default
behaviors for the RASDIALEXTENSIONS options.
lpszPhonebook
Windows
NT: Pointer to a null-terminated
string that specifies the full path and filename 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.
Windows
95: This parameter is ignored.
Dial-up networking stores phone-book entries in the registry rather than in a
phone-book file.
lpRasDialParams
Points 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.
dwNotifierType
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 |
|
0xFFFFFFFF |
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; } |
|
0 |
The lpvNotifier
parameter points to a RasDialFunc callback function. |
|
1 |
The lpvNotifier
parameter points to a RasDialFunc1 callback function. |
|
2 |
Windows
NT: The lpvNotifier
parameter points to a RasDialFunc2 callback function. |
lpvNotifier
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.
lphRasConn
Points 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 *lphRasConn.
Return Values
If the
function succeeds, the immediate return value is zero. In addition, the
function stores a handle to the RAS connection into the variable pointed to by lphRasConn.
If the
function fails, the immediate return value is a nonzero error value, either
from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY.
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 hangup does not occur until
the routine returns.
Windows
NT:
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.
To specify that RasDial should enter a RASCS_CallbackSetByCaller
state, set lpRasDialParams->szCallbackNumber to "*"
on the initial call to RasDial. When your notification handler is called
with this state, you can set the the callback number to a number supplied by
the user.
Windows
95:
Windows 95
does not support the RASCS_CallbackSetByCaller state or any of the other paused
states.
See Also