RasPhonebookDlg

The RasPhonebookDlg function displays the main Dial-Up Networking dialog box. From this modal dialog box, the user can dial, edit, or delete a selected phone-book entry, create a new phone-book entry, or specify user preferences. The RasPhonebookDlg function returns when the dialog box closes.

BOOL RasPhonebookDlg(
  LPTSTR lpszPhonebook,  // pointer to the full path and file name of 
                         //  the phone-book file
  LPTSTR lpszEntry,      // pointer to the name of the phone-book 
                         //  entry to highlight
  LPRASPBDLG lpInfo      // pointer to a structure that contains 
                         //  additional parameters
);

Parameters

lpszPhonebook

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.

lpszEntry

Pointer to a null-terminated string that contains the name of the phone-book entry to highlight initially. If this parameter is NULL, or if the specified entry does not exist, the dialog box highlights the first entry in the alphabetic list.

lpInfo

Pointer to a RASPBDLG structure that contains additional input and output parameters. On input, the dwSize member of this structure must specify sizeof(RASPBDLG). If an error occurs, the dwError member returns an error code; otherwise, it returns zero.

Return Values

If the user selects the Dial button and the function establishes a connection, the return value is a nonzero value.

If an error occurs, or if the user selects the Close button to close the dialog box, the return value is zero. If an error occurs, the dwError member of the RASPBDLG structure returns a nonzero system error code or RAS error code.

The following sample code brings up the Dial-Up Networking dialog. The dialog will display dialing information for the first entry from the default phone-book file.

lpInfo = (LPRASPBDLG)GlobalAlloc(GPTR, sizeof(RASPBDLG));
// Essential, since garbage values cause the API to fail
ZeroMemory(lpInfo, sizeof(RASPBDLG));
lpInfo->dwSize=sizeof(RASPBDLG);
 
nRet = RasPhonebookDlg(NULL,NULL,lpInfo);
 
if (nRet)
    printf("User pressed Dial\n");
else
{
    if (lpInfo->dwError != 0)
    {
        printf("RasPhonebookDlg failed: Error = %d\n", lpInfo->dwError);
    }
    else
        printf("User pressed Close\n");
}

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Unsupported.
  Header: Declared in Rasdlg.h.
  Library: Use Rasdlg.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASPBDLG