Função RasDialA (ras.h)
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 |
|---|---|
|
O parâmetro lpvNotifier aponta para uma função de retorno de chamada RasDialFunc . |
|
O parâmetro lpvNotifier aponta para uma função de retorno de chamada RasDialFunc1 . |
|
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.
[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 |
Confira também
Visão geral do RAS (Serviço de Acesso Remoto)
Funções do serviço de acesso remoto