Функция 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

Указатель на строку, завершающуюся нулевым значением, которая указывает имя записи телефонной книги для набора.

[in] lpszPhoneNumber

Указатель на строку, завершающуюся значением NULL, которая указывает номер телефона, который переопределяет номера, хранящиеся в записи телефонной книги. Если этот параметр имеет значение NULL, RasDialDlg использует номера в записи телефонной книги.

[in] lpInfo

Указатель на структуру RASDIALDLG , которая задает дополнительные входные и выходные параметры. Элемент dwSize этой структуры должен указывать sizeof(RASDIALDLG). При возникновении ошибки член dwError возвращает код ошибки; в противном случае возвращается ноль.

Возвращаемое значение

Если функция устанавливает соединение RAS, возвращается значение TRUE. В противном случае функция должна возвращать значение FALSE.

При возникновении ошибки RasDialDlg следует задать для члена dwError структуры RASDIALDLG значение из кода ошибок маршрутизации и удаленного доступа или Winerror.h.

Функция RasDialDlg отображает ряд диалоговых окон, аналогичных диалоговым окнам, которые отображаются в диалоговом окне main Коммутируемое подключение, когда пользователь нажимает кнопку Набрать. Используйте функцию RasDialDlg для отображения стандартного пользовательского интерфейса для операции подключения без отображения диалогового окна main телефонной книги. Например, служба autoDial 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	rasdlg.h
Библиотека	Rasdlg.lib
DLL	Rasdlg.dll

См. также раздел

RASDIALDLG

RasPhonebookDlg

Общие сведения о службе удаленного доступа (RAS)

Функции службы удаленного доступа