CUT_RAS::Dial
int Dial(LPCSTR szEntry,LPCSTR szUserName = NULL, LPCSTR szPassword = NULL,LPCSTR szNumber = NULL)
Parameters
|
szEntry |
The name of the phone-book entry to dial. |
|
szUserName |
A string containing the user's username. This string is used to authenticate the user's access to the remote access server. |
|
szPassword |
A string containing the user's password. The password is used to authenticate the user's access to the remote access server. |
|
szNumber |
A string containing an overriding phone number. An empty string ("") indicates that the phone-book entry's phone number should be used. NOTE: If szEntry is "" then szNumber cannot be NULL. |
Return Value
|
UTE_SUCCESS |
Operation completed successfully. |
|
UTE_ERROR |
Operation failed. |
|
UTE_RAS_DIALINIT_ERROR |
Error occurred when the dialing process was initiated (see GetLastRASError for more details). |
|
UTE_RAS_DIAL_ERROR |
Error occurred during the dialing process. Use the GetDialState function to retrieve more detailed information. |
|
UTE_RAS_LOAD_ERROR |
Unable to load the RAS DLLs. |
Remarks
Dials a given phonebook entry. The szUserName, szPassword and szNumber parameters are optional and can be NULL. To override information located in the dialup entry you would then specify these parameters (the phonebook entry itself will not be modified).
Under Win98 and NT this function can dial without a phonebook entry by using the given information and the first available dial-up device. Although a dialup connection can be made without specifying a phonebook entry it is recommended that you do so for reliability purposes.
This function does not return until the dialing has either been successfully completed or an error occurs.
To monitor the connection use the SetDialStatusCallback function to send dial status information (as a message) to a given window. To retrieve more information when this function returns use the GetDialState function.
See also: DoesEntryExist
Example
/**********************************
In the following example we will enumerate the available phonebook entries and then we will attempt to connect to the first available entry.
**********************************/
#include "stdafx.h" // this header includes nothing but the #include <windows.h> statement
#include "ut_ras.h" // the header files for the CUT_RAS class
// resource header for a dialog (IDD_DIALOG1) that contains a read only edit box (IDC_EDIT1) , Dial button (IDC_DIAL) and a cancel button (IDCANCEL)
#include "resource.h"
// our user defined window message for dialup status
#define WM_CUT_RAS_DIALSTATUS WM_USER+1
// prototype of the only dialog procedure
BOOL CALLBACK DialupDlgProc(HWND hwndDlg, UINT message, WPARAM wParam, LPARAM lParam);
// windows main entry point
int CALLBACK WinMain(HINSTANCE hInstance,HINSTANCE ,LPSTR ,int)
{
// create modal dialog box
DialogBox(hInstance,MAKEINTRESOURCE(IDD_DIALOG1),NULL, (DLGPROC )DialupDlgProc);
return 0;
}
// enumerate the available phonebook entries and attempt to connect to the first one available
BOOL CALLBACK DialupDlgProc(HWND hwndDlg, UINT message, WPARAM wParam, LPARAM lParam)
{
// static instance of the CUT_RAS class
static CUT_RAS ras;
// dispatch the window messages
switch (message) {
// initializing the dialog
case WM_INITDIALOG:
{
// we want the CUT_RAS class to send us the WM_CUT_RAS_DIALSTATUS window message
// informing us of the progress of the dialup attempt
ras.SetDialStatusCallback (hwndDlg,WM_CUT_RAS_DIALSTATUS);
return 1;
}
// if the message is the one we have asked the CUT_RAS to use
// then inform us of the dialup attempt progress
case WM_CUT_RAS_DIALSTATUS :
{
// Update the edit box with the string passed by the CUT_RAS class.
// The lower word of the message parameter is the string describing the current dialup state.
SetDlgItemText(hwndDlg, IDC_EDIT1,(LPCSTR)(LPARAM)lParam);
return 1;
}
// if the message is a user command
case WM_COMMAND:
switch (LOWORD(wParam))
{
// the user clicked on the Cancel button
case IDCANCEL:
{
// cancel any pending new dialup attempt on this instance of the CUT_RAS class
ras.CancelDial ();
// hang-up the current connection
ras.HangUp ();
// cLose the dialog
EndDialog(hwndDlg, IDOK);
break;
}
// the user pressed the Dial button
case IDC_DIAL:
{
LPRASENTRYNAME ren = new RASENTRYNAME [sizeof(RASENTRYNAME)+1];
// get the first entry
ras.EnumEntries();
memset(ren,0,sizeof(RASENTRYNAME));
ras.GetEntry (ren,0);
// dial the first entry
ras.Dial(ren->szEntryName);
break;
}
}
break;
case WM_CLOSE:
{
ras.CancelDial ();
ras.HangUp ();
EndDialog(hwndDlg, IDOK);
break;
}
}
return 0;
}