Функция RasEntryDlgA (rasdlg.h)

Статья
11/20/2024

Функция RasEntryDlg отображает модальные таблицы свойств, позволяющие пользователю управлять записями телефонной книги. При редактировании или копировании существующей записи телефонной книги функция отображает лист свойств записи телефонной книги. Функция RasEntryDlg возвращается, когда пользователь закрывает лист свойств.

Синтаксис

BOOL RasEntryDlgA(
  [in] LPSTR          lpszPhonebook,
  [in] LPSTR          lpszEntry,
  [in] LPRASENTRYDLGA lpInfo
);

Параметры

[in] lpszPhonebook

Указатель на строку null-terminated, указывающую полный путь и имя файла телефонной книги (PBK). Если этот параметр NULL, функция использует текущий файл телефонной книги по умолчанию. Файл телефонной книги по умолчанию — это файл, выбранный пользователем в разделе настройки пользователя свойств диалогового окна "Подключение к сети".

[in] lpszEntry

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

Если вы редактируете или копируете запись, этот параметр является именем существующей записи телефонной книги. При копировании записи задайте флаг RASEDFLAG_CloneEntry в dwFlags член структуры RASENTRYDLG.

Примечание Флаг RASEDFLAG_CloneEntry не рекомендуется использовать по состоянию на Windows Vista и Windows Server 2008. Он может быть изменен или недоступен в последующих версиях. Вместо этого скопируйте запись, вызвав RasGetEntryProperties, чтобы получить запись, а затем вызовите RasSetEntryProperties, чтобы сохранить запись с новым именем.

Если вы создаете запись, этот параметр по умолчанию является новым именем записи, которую пользователь может изменить. Если этот параметр NULL, функция предоставляет имя по умолчанию. Если вы создаете запись, задайте флаг RASEDFLAG_NewEntry в dwFlags член структуры RASENTRYDLG.

[in] lpInfo

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

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

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

Если возникает ошибка, RasEntryDlg задает -элемент объекта rasentryDLG значение от кодов ошибок маршрутизации и удаленного доступа или Winerror.h.

Замечания

Функции RasCreatePhonebookEntry и RasEditPhonebookEntry вызывают функцию RasEntryDl g.

В следующем примере кода создается лист свойств для создания новой записи. Переменная lpszEntry указывает имя по умолчанию для новой записи.

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

DWORD __cdecl wmain(){

    DWORD dwRet = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";

    // Allocate heap memory and initialize RASENTRYDLG structure
    LPRASENTRYDLG lpEntry = (LPRASENTRYDLG)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRYDLG));
    if (lpEntry == NULL){
        wprintf(L"HeapAlloc failed.\n");
        return 0;
    }
    
    // The RASENTRYDLG->dwSize member has to be initialized or the RRAS APIs will fail below.
    lpEntry->dwSize = sizeof(RASENTRYDLG);
    lpEntry->dwFlags |= RASEDFLAG_NewEntry;

    // Create the new entry using a user dialog
    nRet = RasEntryDlg(NULL, lpszEntry, lpEntry);

    // Any error codes are returned in lpEntry
    dwRet = lpEntry->dwError;
    
    if (nRet == TRUE) {
        wprintf(L"New entry created: %s\n", lpEntry->szEntry);

        // Clean up: delete the new entry
        dwRet = RasDeleteEntry(NULL, lpszEntry);
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
        }

    } 
    else {
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasEntryDlg failed: Error = %d\n", dwRet);
        }
        else {
            wprintf(L"User pressed Cancel\n");
        }
    }

    HeapFree(GetProcessHeap(), 0, lpEntry);
    return 0;
}

Заметка

Заголовок rasdlg.h определяет RASENTRYDLG как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	rasdlg.h
библиотеки	Rasdlg.lib
DLL	Rasdlg.dll