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 rasdial para habilitar. Defina esse parâmetro para NULL se não houver a necessidade de habilitar esses recursos.

[in] unnamedParam2

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho completo e o nome do arquivo de um PBK (lista telefônica). 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] 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 lista telefônica específica.

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

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

[in] unnamedParam4

Especifica a natureza do parâmetro lpvNotifier. Se lpvNotifier for NULL, dwNotifierType será ignorado. Se lpvNotifier não estiver 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 umrasDialFunc , RasDialFunc1ou rasDialFunc2 função de retorno de chamada 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 de 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 de rasDial funcionará de forma síncrona: RasDial não retornará até que a tentativa de conexão tenha sido concluída com êxito ou falha.

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

• A conexão é estabelecida. Em outras palavras, o estado de conexão RAS é RASCS_Connected.
• A conexão falha. Em outras palavras, dwError não é 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 para NULL antes de chamar RasDial. Se RasDial for bem-sucedido, ele armazenará um identificador para a conexão RAS em *lphRasConn.

Valor de retorno

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.

Observações

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 de NULL nãofor armazenado em *lphRasConn. Isso se aplica mesmo se rasDial retornar um valor diferente de zero (erro).

Um aplicativo pode chamar com segurança RasHangUp de uma função de retorno de chamada rasDial de . 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 é definido como um. Para reiniciar RasDial de um estado tão pausado, chame rasDial novamente, passando o identificador de conexão retornado da chamada de RasDial de original em *lphRasConn. O mesmo notificador usado no rasDial original chamada 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 é equivalente ao parâmetro rasconnstate de rasDialFunc e RasDialFunc1e RasDialFunc1 elParam é 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 deste 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 correspondida por umRasHangUp .

Como algumas entradas de lista telefônica exigem 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 da lista telefônica não exigirá EAP. No entanto, se RasGetEapUserIdentity retornar NO_ERROR, O chamador deve copiar as informações de identidade do EAP de rasGetEapUserIdentity para o rasEapInfo membro do RASDIALEXTENSIONSe o membro szUserName de RASDIALPARAMS. Consulte rasGetEapUserIdentity para obter mais informações. Se a entrada da lista telefônica exigir EAP, o dwfOptions membro da estrutura RASENTRY para a entrada contém 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.

Nota

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

Consulte 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