Função RasEntryDlgA (rasdlg.h)

Artigo
08/25/2023

A função RasEntryDlg exibe folhas de propriedades modais que permitem que um usuário manipule entradas de catálogo telefônico. Se estiver editando ou copiando uma entrada de catálogo telefônico existente, a função exibirá uma folha de propriedades de entrada do catálogo telefônico. A função RasEntryDlg retorna quando o usuário fecha a folha de propriedades.

Sintaxe

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

Parâmetros

[in] lpszPhonebook

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho completo e o nome do arquivo de um arquivo de catálogo telefônico (PBK). Se esse parâmetro for NULL, a função usará o arquivo de catálogo telefônico padrão atual. O arquivo de agendamento telefônico padrão é aquele selecionado pelo usuário na folha de propriedades Preferências do Usuário da caixa de diálogo Rede Discada .

[in] lpszEntry

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome da entrada do catálogo telefônico para editar, copiar ou criar.

Se você estiver editando ou copiando uma entrada, esse parâmetro será o nome de uma entrada de catálogo telefônico existente. Se você estiver copiando uma entrada, defina o sinalizador RASEDFLAG_CloneEntry no membro dwFlags da estrutura RASENTRYDLG .

Nota O sinalizador RASEDFLAG_CloneEntry foi preterido, a partir do Windows Vista e do Windows Server 2008. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. Em vez disso, copie uma entrada chamando RasGetEntryProperties para obter a entrada e, em seguida, chamando RasSetEntryProperties para salvar a entrada com um novo nome.

Se você estiver criando uma entrada, esse parâmetro será um novo nome de entrada padrão que o usuário pode alterar. Se esse parâmetro for NULL, a função fornecerá um nome padrão. Se você estiver criando uma entrada, defina o sinalizador RASEDFLAG_NewEntry no membro dwFlags da estrutura RASENTRYDLG .

[in] lpInfo

Ponteiro para uma estrutura RASENTRYDLG que especifica parâmetros adicionais de entrada e saída. O membro dwSize dessa estrutura deve especificar sizeof(RASENTRYDLG). Use o membro dwFlags para indicar se você está criando, editando ou copiando uma entrada. Se ocorrer um erro, o membro dwError retornará um código de erro; caso contrário, ele retornará zero.

Retornar valor

Se o usuário criar, copiar ou editar uma entrada de catálogo telefônico, o valor retornado será TRUE. Caso contrário, a função retornará FALSE.

Se ocorrer um erro, RasEntryDlg definirá o membro dwError da estrutura RASENTRYDLG como um valor de Códigos de Erro de Roteamento e Acesso Remoto ou Winerror.h.

Comentários

As funções RasCreatePhonebookEntry e RasEditPhonebookEntry chamam a função RasEntryDlg .

O código de exemplo a seguir traz uma folha de propriedades para criar uma nova entrada. A variável lpszEntry especifica o nome padrão para a nova entrada.

#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;
}

Observação

O cabeçalho rasdlg.h define RASENTRYDLG como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	rasdlg.h
Biblioteca	Rasdlg.lib
DLL	Rasdlg.dll