RasDialFunc
The RasDialFunc
function is an application-defined or library-defined callback function that
the RasDial
function calls when a change of state occurs during a RAS connection process.
VOID WINAPI RasDialFunc(
|
UINT unMsg, |
// type of event
that has occurred |
|
RASCONNSTATE rasconnstate, |
// connection state
about to be entered |
|
DWORD dwError |
// error that may
have occurred |
|
); |
|
Parameters
unMsg
Specifies the
type of event that has occurred. Currently, the only event defined is
WM_RASDIALEVENT.
rasconnstate
Specifies a RASCONNSTATE enumerator value that
indicates the state the RasDial remote access connection process is
about to enter.
dwError
Indicates the
error that has occurred, or zero if no error has occurred.
RasDial calls RasDialFunc with dwError set to
zero upon entry to each connection state. If an error occurs within a state, RasDialFunc
is called again with a nonzero dwError value.
Return Values
None.
Remarks
A RasDial
connection operation is suspended during a call to a RasDialFunc
callback function. For that reason, your RasDialFunc implementation
should generally return as quickly as possible. There are two exceptions to
that rule. Asynchronous (slow) devices such as modems often have time-out periods
measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc
function is generally not a problem. The prompt return requirement also does
not apply when dwError is nonzero, indicating that an error has
occurred. It is safe, for example, to put up an error dialog box and wait for
user input.
Your RasDialFunc
implementation should not depend on the order or occurrence of particular RASCONNSTATE
connection states, because this may vary between platforms.
Do not call
the RasDial function from within a RasDialFunc callback function.
You can call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp functions from within the
callback function. For example, calling RasGetConnectStatus from within
a callback function would be useful for determining the name and type of the
connecting device.
Note that,
for convenience, RasHangUp can be called from within a RasDialFunc
callback function. However, much of the hang-up processing occurs after the RasDialFunc
callback function has returned.
RasDialFunc is a placeholder for the application-defined or
library-defined function name.
See Also