Compartilhar via


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
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

Confira também

Endereços Discáveis

RASDIALEXTENSIONS

RASDIALPARAMS

RasDialDlg

RasDialFunc

RasDialFunc1

RasDialFunc2

Rasgetconnectstatus

Rashangup

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

Funções do serviço de acesso remoto

Conexões de Rede Virtual Privada

WM_RASDIALEVENT