Função RasEntryDlgA (rasdlg.h)

Artigo
11/20/2024

A função RasEntryDlg exibe folhas de propriedades modais que permitem que um usuário manipule entradas de lista telefônica. Se estiver editando ou copiando uma entrada de lista telefônica 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 um cadeia de caracteres nulaterminada que especifica o caminho completo e o nome do arquivo de um arquivo PBK (phone-book). Se esse parâmetro for NULL, a função usará o arquivo de agendamento telefônico padrão atual. O arquivo de lista telefônica padrão é o selecionado pelo usuário na folha de propriedades preferências do usuário da caixa de diálogo rede discada .

[in] lpszEntry

Ponteiro para um cadeia de caracteresterminada nula que especifica o nome da entrada da lista telefônica a ser editada, copiada ou criada.

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

Observação o sinalizador RASEDFLAG_CloneEntry foi preterido, a partir do Windows Vista e do Windows Server 2008. Ele pode estar alterado ou 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.

Valor de retorno

Se o usuário criar, copiar ou editar uma entrada de lista telefônica, o valor retornado será VERDADEIRO. Caso contrário, a função retornará FALSE.

Se ocorrer um erro, RasEntryDlg definirá o membro dwError da estrutura RASENTRYDLG para um valor de códigos de erro de roteamento e acesso remoto ou Winerror.h.

Observações

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

O código de exemplo a seguir apresenta uma folha de propriedades para criar uma nova entrada. A variável lpszEntry especifica o nome padrão da 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;
}

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	rasdlg.h
biblioteca	Rasdlg.lib
de DLL	Rasdlg.dll