RasPhonebookDlg function

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(
  _In_    LPTSTR     lpszPhonebook,
  _In_    LPTSTR     lpszEntry,
  _Inout_ LPRASPBDLG lpInfo


lpszPhonebook [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.

lpszEntry [in]

Pointer to a null-terminated string that specifies 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 [in, out]

Pointer to the RASPBDLG structure that specifies additional input and output parameters.

On input, the dwSize member of this structure must specify the sizeof( RASPBDLG).

If an error occurs, the dwError member of the structure receives, on output, an error code; otherwise, it receives zero.

Return value

If the user selects the Connect button and the function establishes a connection, the return value is TRUE. Otherwise, the function returns FALSE.

If an error occurs, the dwError member of the RASPBDLG structure returns a value from Routing and Remote Access Error Codes or Winerror.h.

The following sample code brings up the Dial-Up Networking dialog. The dialog displays dialing information for the first entry from the default phonebook file.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "rasdlg.h"
#pragma comment(lib, "rasapi32.lib")

int main (){
    // Initialize the return code
    BOOL nRet = TRUE;

    // Allocate heap memory for the RASPBLDG structure
    RASPBDLG * lpInfo = (LPRASPBDLG)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASPBDLG));
    // The dwsize member of lpInfo must contain the structure size, or the 
    // call to RasPhonebookDlg will fail
    lpInfo->dwSize = sizeof(RASPBDLG);
    // Open a user dialog box  
    nRet = RasPhonebookDlg(NULL,NULL,lpInfo);
    if(nRet == TRUE){
        // The user dialed a connection successfully
        printf("User pressed Connect\n");
        if(lpInfo->dwError != 0){
            printf("RasPhonebookDlg failed: Error = %d\n", lpInfo->dwError);
            // The user closed the dialog box manually
            printf("User pressed Close\n");

    // Free the heap memory for the RASPBLDG structure
    HeapFree(GetProcessHeap(), 0, lpInfo);
    return 0;


Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]







Unicode and ANSI names

RasPhonebookDlgW (Unicode) and RasPhonebookDlgA (ANSI)

See also

Remote Access Service (RAS) Overview
Remote Access Service Functions



Community Additions