Função RasDialDlgA (rasdlg.h)

Artigo
03/05/2024

A função RasDialDlg estabelece uma conexão RAS usando uma entrada de catálogo telefônico especificada e as credenciais do usuário conectado. A função exibe um fluxo de caixas de diálogo que indicam o estado da operação de conexão.

Sintaxe

BOOL RasDialDlgA(
  [in] LPSTR        lpszPhonebook,
  [in] LPSTR        lpszEntry,
  [in] LPSTR        lpszPhoneNumber,
  [in] LPRASDIALDLG 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 discar.

[in] lpszPhoneNumber

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica um número de telefone que substitui os números armazenados na entrada do catálogo telefônico. Se esse parâmetro for NULL, RasDialDlg usará os números na entrada do catálogo telefônico.

[in] lpInfo

Ponteiro para uma estrutura RASDIALDLG que especifica parâmetros adicionais de entrada e saída. O membro dwSize dessa estrutura deve especificar sizeof(RASDIALDLG). Se ocorrer um erro, o membro dwError retornará um código de erro; caso contrário, ele retornará zero.

Retornar valor

Se a função estabelecer uma conexão RAS, o valor retornado será TRUE. Caso contrário, a função deverá retornar FALSE.

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

Comentários

A função RasDialDlg exibe uma série de caixas de diálogo semelhantes às caixas de diálogo que a caixa de diálogo main caixa de diálogo Rede Discada exibe quando o usuário seleciona o botão Discar. Use a função RasDialDlg para exibir uma interface do usuário padrão para uma operação de conexão sem apresentar a caixa de diálogo main catálogo telefônico. Por exemplo, o serviço de AutoDial ras usa essa função para estabelecer uma conexão usando a entrada do catálogo telefônico associada a um endereço remoto.

A função RasDialDlg exibe caixas de diálogo durante a operação de conexão para fornecer comentários ao usuário sobre o progresso da operação. Por exemplo, as caixas de diálogo podem indicar quando a operação está discando, quando está autenticando as credenciais do usuário no servidor remoto e assim por diante. As caixas de diálogo também fornecem um botão Cancelar para o usuário encerrar a operação.

RasDialDlg retorna quando a conexão é estabelecida ou quando o usuário cancela a operação.

O código de exemplo a seguir disca a entrada no catálogo telefônico padrão especificado pela variável lpszEntry.

Nota Este exemplo simples destina-se a ser executado no Windows Vista e em versões posteriores do Windows. Lembre-se de que a chamada para sizeof (RASENTRY) retornará um valor diferente dependendo de qual versão do sistema operacional o código está sendo executado. Execute as etapas para garantir que isso seja tratado adequadamente.

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

Observação

O cabeçalho rasdlg.h define RasDialDlg 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

Confira também

RASDIALDLG

RasPhonebookDlg

Visão geral do RAS (Serviço de Acesso Remoto)

Funções do serviço de acesso remoto

Compartilhar via

Função RasDialDlgA (rasdlg.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Requisitos

Confira também

Comentários

Recursos adicionais