RasPhonebookDlgA function (rasdlg.h)

Article
02/09/2023

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.

Syntax

BOOL RasPhonebookDlgA(
  [in]      LPSTR       lpszPhonebook,
  [in]      LPSTR       lpszEntry,
  [in, out] LPRASPBDLGA lpInfo
);

Parameters

[in] 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.

[in] lpszEntry

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.

[in, out] lpInfo

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");
    }else{
        if(lpInfo->dwError != 0){
            printf("RasPhonebookDlg failed: Error = %d\n", lpInfo->dwError);
        }else{
            // 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;
}

Remarks

Note

The rasdlg.h header defines RasPhonebookDlg as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	rasdlg.h
Library	Rasdlg.lib
DLL	Rasdlg.dll