Função RasDialA (ras.h)

Artigo
08/25/2023

A função RasDial estabelece uma conexão RAS entre um cliente RAS e um servidor RAS. Os dados de conexão incluem informações de retorno de chamada e autenticação do usuário.

Sintaxe

DWORD RasDialA(
  [in]  LPRASDIALEXTENSIONS unnamedParam1,
  [in]  LPCSTR              unnamedParam2,
  [in]  LPRASDIALPARAMSA    unnamedParam3,
  [in]  DWORD               unnamedParam4,
  [in]  LPVOID              unnamedParam5,
  [out] LPHRASCONN          unnamedParam6
);

Parâmetros

[in] unnamedParam1

Ponteiro para uma estrutura RASDIALEXTENSIONS que especifica um conjunto de recursos estendidos rasDial a serem habilitados. Defina esse parâmetro como NULL se não houver necessidade de habilitar esses recursos.

[in] unnamedParam2

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho completo e o nome de 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 catálogo 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] unnamedParam3

Ponteiro para uma estrutura RASDIALPARAMS que especifica parâmetros de chamada para a conexão RAS. Use a função RasGetEntryDialParams para recuperar uma cópia dessa estrutura para uma entrada de catálogo telefônico específica.

O chamador deve definir o membro dwSize da estrutura RASDIALPARAMS como sizeof (RASDIALPARAMS) para identificar a versão da estrutura que está sendo passada.

Se o membro szPhoneNumber da estrutura RASDIALPARAMS for uma cadeia de caracteres vazia, RasDial usará o número de telefone armazenado na entrada do catálogo telefônico.

[in] unnamedParam4

Especifica a natureza do parâmetro lpvNotifier . Se lpvNotifier for NULL, dwNotifierType será ignorado. Se lpvNotifier não for NULL, defina dwNotifierType como um dos valores a seguir.

Valor	Significado
0	O parâmetro lpvNotifier aponta para uma função de retorno de chamada RasDialFunc .
1	O parâmetro lpvNotifier aponta para uma função de retorno de chamada RasDialFunc1 .
2	O parâmetro lpvNotifier aponta para uma função de retorno de chamada RasDialFunc2 .

[in] unnamedParam5

Especifica um identificador de janela ou uma função de retorno de chamada RasDialFunc, RasDialFunc1 ou RasDialFunc2 para receber notificações de evento RasDial . O parâmetro dwNotifierType especifica a natureza de lpvNotifier. Consulte sua descrição anterior para obter mais detalhes.

Se esse parâmetro não for NULL, RasDial enviará uma mensagem à janela ou chamará a função de retorno de chamada para cada evento RasDial . Além disso, a chamada RasDial opera de forma assíncrona: RasDial retorna imediatamente, antes que a conexão seja estabelecida e comunica seu progresso por meio da janela ou função de retorno de chamada.

Se lpvNotifier for NULL, a chamada RasDial funcionará de forma síncrona: RasDial não retornará até que a tentativa de conexão seja concluída com êxito ou falhe.

Se lpvNotifier não for NULL, as notificações para a janela ou função de retorno de chamada poderão ocorrer a qualquer momento após a chamada inicial para RasDial. As notificações terminam quando ocorre um dos seguintes eventos:

A conexão é estabelecida. Em outras palavras, o estado de conexão RAS é RASCS_Connected.
A conexão falha. Em outras palavras, dwError é diferente de zero.
RasHangUp é chamado na conexão.

As notificações de retorno de chamada são feitas no contexto de um thread capturado durante a chamada inicial para RasDial.

[out] unnamedParam6

Ponteiro para uma variável do tipo HRASCONN. Defina a variável HRASCONN como NULL antes de chamar RasDial. Se RasDial for bem-sucedido, ele armazenará um identificador para a conexão RAS em *lphRasConn.

Valor retornado

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS e um identificador para a conexão RAS será retornado na variável apontada por lphRasConn.

Se a função falhar, o valor retornado será de Códigos de Erro de Roteamento e Acesso Remoto ou Winerror.h.

Comentários

Erros que ocorrem após o retorno imediato podem ser detectados por RasGetConnectStatus. Os dados estão disponíveis até que um aplicativo chame RasHangUp para desligar a conexão.

Um aplicativo deve eventualmente chamar RasHangUp sempre que um identificador de conexão não NULL for armazenado em *lphRasConn. Isso se aplica mesmo que RasDial retorne um valor diferente de zero (erro).

Um aplicativo pode chamar RasHangUp com segurança de uma função de retorno de chamada do notificador RasDial . No entanto, se isso for feito, o desligamento não ocorrerá até que a rotina retorne.

Se a estrutura apontada por lpRasDialExtensions habilitar RDEOPT_PausedStates, a função RasDial pausa sempre que entra em um estado no qual o bit RASCS_PAUSED está definido como um. Para reiniciar o RasDial desse estado em pausa, chame RasDial novamente, passando o identificador de conexão retornado da chamada RasDial original em *lphRasConn. O mesmo notificador usado na chamada RasDial original deve ser usado ao reiniciar de um estado em pausa.

O parâmetro lpvNotifier é um identificador para uma janela para receber mensagens de notificação de progresso. Em uma mensagem de notificação em andamento, wParam é o equivalente ao parâmetro rasconnstate de RasDialFunc e RasDialFunc1, e lParam é o equivalente ao parâmetro dwError de RasDialFunc e RasDialFunc1.

A mensagem de notificação de progresso usa um código de mensagem registrado pelo sistema. Você pode obter o valor desse código de mensagem da seguinte maneira:

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

O RAS dá suporte a conexões referenciadas. Se a entrada que está sendo discada já estiver conectada, RasDial retornará SUCCESS e a conexão será referenciada. Para desconectar a conexão, cada RasDial na conexão deve ser correspondido por um RasHangUp.

Como algumas entradas de catálogo telefônico exigem o Protocolo de Autenticação Extensível (EAP) para autenticação, o chamador deve chamar RasGetEapUserIdentity antes de chamar RasDial. Se RasGetEapUserIdentity retornar ERROR_INVALID_FUNCTION_FOR_ENTRY, a entrada do catálogo telefônico não exigirá EAP. No entanto, se RasGetEapUserIdentity retornar NO_ERROR, o chamador deverá copiar as informações de identidade do EAP de RasGetEapUserIdentity para o membro RasEapInfo de RASDIALEXTENSIONS e o membro szUserName de RASDIALPARAMS. Consulte RasGetEapUserIdentity para obter mais informações. Se a entrada do catálogo telefônico exigir EAP, o membro dwfOptions da estrutura RASENTRY para a entrada conterá o sinalizador RASEO_RequireEAP .

Para especificar que RasDial deve inserir um estado RASCS_CallbackSetByCaller, defina lpRasDialParams-szCallbackNumber> como "*" na chamada inicial para RasDial. Quando o manipulador de notificação for chamado com esse estado, defina o número de retorno de chamada como um número fornecido pelo usuário.

Observação

O cabeçalho ras.h define RasDial 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


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	ras.h
Biblioteca	Rasapi32.lib
DLL	Rasapi32.dll