rasDialDlgA 函数 (rasdlg.h)

项目
08/25/2023

RasDialDlg 函数使用指定的电话簿条目和已登录用户的凭据建立 RAS 连接。函数显示指示连接操作状态的对话框流。

语法

BOOL RasDialDlgA(
  [in] LPSTR        lpszPhonebook,
  [in] LPSTR        lpszEntry,
  [in] LPSTR        lpszPhoneNumber,
  [in] LPRASDIALDLG lpInfo
);

参数

[in] lpszPhonebook

指向以 null 结尾的字符串的指针，该字符串指定电话簿 (PBK) 文件的完整路径和文件名。如果此参数为 NULL，则该函数使用当前默认的电话簿文件。默认电话簿文件是用户在“拨号网络”对话框的“用户首选项”属性表中选择的文件。

[in] lpszEntry

指向以 null 结尾的字符串的指针，该字符串指定要拨号的电话簿条目的名称。

[in] lpszPhoneNumber

指向以 null 结尾的字符串的指针，该字符串指定替代电话簿条目中存储的数字的电话号码。如果此参数为 NULL， 则 RasDialDlg 使用电话簿条目中的数字。

[in] lpInfo

指向 RASDIALDLG 结构的指针，该结构指定其他输入和输出参数。此结构的 dwSize 成员必须指定 size of (RASDIALDLG) 。如果发生错误， dwError 成员将返回错误代码;否则，它将返回零。

返回值

如果函数建立 RAS 连接，则返回值为 TRUE。否则，函数应返回 FALSE。

如果发生错误，RasDialDlg 应将 RASDIALDLG 结构的 dwError 成员设置为路由和远程访问错误代码或 Winerror.h 中的值。

注解

RasDialDlg 函数显示一系列对话框，这些对话框类似于用户选择“拨号”按钮时main拨号网络对话框显示的对话框。使用 RasDialDlg 函数显示连接操作的标准用户界面，而不显示main电话簿对话框。例如，RAS 自动拨打服务使用此函数通过与远程地址关联的电话簿条目建立连接。

RasDialDlg 函数在连接操作期间显示对话框，以向用户提供有关操作进度的反馈。例如，对话框可以指示操作何时拨号、在远程服务器上对用户凭据进行身份验证等。这些对话框还提供了一个 “取消 ”按钮，供用户终止操作。

RasDialDlg 在建立连接或用户取消操作时返回。

以下示例代码拨打变量 lpszEntry 指定的默认电话簿中的条目。

注意此简单示例适用于在 Windows Vista 和更高版本的 Windows 上运行。请注意，调用 sizeof (RASENTRY) 将返回不同的值，具体取决于运行代码的操作系统版本。请采取措施确保妥善处理。

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "rasdlg.h"
#include <tchar.h>
#include "strsafe.h"

#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5

DWORD __cdecl wmain(){

    DWORD dwError = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";
    LPTSTR lpszphonenumber = L"5555555";
    LPTSTR lpszdevicename = L"Modem";
    LPTSTR lpszdevicetype = RASDT_Modem;

    // Allocate heap memory and initialize RASENTRY structure
    LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
    // Allocate heap memory and initialize RASDIALDLG structure
    LPRASDIALDLG lpInfo = (LPRASDIALDLG) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASDIALDLG));
    
    if (lpentry == NULL || lpInfo == NULL){
        wprintf(L"HeapAlloc failed");
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // The RASDIALDLG and RASENTRY dwSize members have to be initialized or the RasDialDlg()
    // RasSetEntryProperties() APIs will fail below.
    lpInfo->dwSize = sizeof(RASDIALDLG);
    lpentry->dwSize = sizeof(RASENTRY);
    lpentry->dwFramingProtocol = RASFP_Ppp;
    lpentry->dwfOptions = 0;
    lpentry->dwType = RASFP_Ppp;
    dwError |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszphonenumber, PHONE_NUMBER_LENGTH);
    dwError |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszdevicename, DEVICE_NAME_LENGTH);
    dwError |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszdevicetype, DEVICE_TYPE_LENGTH);
    
    if (dwError != S_OK){
        wprintf(L"Structure initialization failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // Validate the new entry's name
    dwError = RasValidateEntryName(NULL, lpszEntry);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasValidateEntryName failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // Create and set the new entry's properties
    dwError = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }
    
    // Connect using the new entry
    nRet = RasDialDlg(NULL, lpszEntry, NULL, lpInfo);
    if (nRet != TRUE){
        wprintf(L"RasDialDlg failed: Error = %d\n", lpInfo->dwError);
    }
    
    // Clean up: delete the new entry
    dwError = RasDeleteEntry(NULL, lpszEntry);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasDeleteEntry failed: Error = %d\n", dwError);
    }
    
    HeapFree(GetProcessHeap(), 0, lpentry);
    HeapFree(GetProcessHeap(), 0, lpInfo);

    return 0;
}

注意

rasdlg.h 标头将 RasDialDlg 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	rasdlg.h
Library	Rasdlg.lib
DLL	Rasdlg.dll

另请参阅

通过

rasDialDlgA 函数 (rasdlg.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源