Compartilhar via


Função InternetConnectA (wininet.h)

Abre uma sessão FTP (File Transfer Protocol) ou HTTP para um determinado site.

Sintaxe

HINTERNET InternetConnectA(
  [in] HINTERNET     hInternet,
  [in] LPCSTR        lpszServerName,
  [in] INTERNET_PORT nServerPort,
  [in] LPCSTR        lpszUserName,
  [in] LPCSTR        lpszPassword,
  [in] DWORD         dwService,
  [in] DWORD         dwFlags,
  [in] DWORD_PTR     dwContext
);

Parâmetros

[in] hInternet

Identificador retornado por uma chamada anterior para InternetOpen.

[in] lpszServerName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do host de um servidor da Internet. Como alternativa, a cadeia de caracteres pode conter o número de IP do site, no formato ascii pontilhado-decimal (por exemplo, 11.0.1.45).

[in] nServerPort

Porta TCP/IP (Protocolo de Controle de Transmissão)no servidor. Esses sinalizadores definem apenas a porta usada. O serviço é definido pelo valor de dwService. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
INTERNET_DEFAULT_FTP_PORT
Usa a porta padrão para servidores FTP (porta 21).
INTERNET_DEFAULT_GOPHER_PORT
Usa a porta padrão para servidores Gopher (porta 70).
Nota Somente Windows XP e Windows Server 2003 R2 e anteriores.
 
INTERNET_DEFAULT_HTTP_PORT
Usa a porta padrão para servidores HTTP (porta 80).
INTERNET_DEFAULT_HTTPS_PORT
Usa a porta padrão para servidores HTTPS (Secure Hypertext Transfer Protocol) (porta 443).
INTERNET_DEFAULT_SOCKS_PORT
Usa a porta padrão para servidores de firewall SOCKS (porta 1080).
INTERNET_INVALID_PORT_NUMBER
Usa a porta padrão para o serviço especificado por dwService.

[in] lpszUserName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do usuário no qual fazer logon. Se esse parâmetro for NULL, a função usará um padrão apropriado. Para o protocolo FTP, o padrão é "anônimo".

[in] lpszPassword

Ponteiro para uma cadeia de caracteres terminada em nulo que contém a senha a ser usada para fazer logon. Se lpszPassword e lpszUsername forem NULL, a função usará a senha "anônima" padrão. No caso do FTP, a senha padrão é o nome de email do usuário. Se lpszPassword for NULL, mas lpszUsername não for NULL, a função usará uma senha em branco.

[in] dwService

Tipo de serviço a ser acessado. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
INTERNET_SERVICE_FTP
Serviço FTP.
INTERNET_SERVICE_GOPHER
Serviço Gopher.
Nota Somente Windows XP e Windows Server 2003 R2 e anteriores.
 
INTERNET_SERVICE_HTTP
Serviço HTTP.

[in] dwFlags

Opções específicas para o serviço usado. If
dwService é INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE faz com que o aplicativo use semântica de FTP passiva.

[in] dwContext

Ponteiro para uma variável que contém um valor definido pelo aplicativo que é usado para identificar o contexto do aplicativo para o identificador retornado em retornos de chamada.

Retornar valor

Retorna um identificador válido para a sessão se a conexão for bem-sucedida ou NULL caso contrário. Para recuperar informações de erro estendidas, chame GetLastError. Um aplicativo também pode usar InternetGetLastResponseInfo para determinar por que o acesso ao serviço foi negado.

Comentários

A tabela a seguir descreve o comportamento das quatro configurações possíveis de lpszUsername e lpszPassword.

lpszUsername lpszPassword Nome de usuário enviado ao servidor FTP Senha enviada ao servidor FTP
NULL NULL "anonymous" Nome de email do usuário
Cadeia de caracteres não NULL NULL lpszUsername ""
NULL Cadeia de caracteres não NULL ERROR ERROR
Cadeia de caracteres não NULL Cadeia de caracteres não NULL lpszUsername lpszPassword
 

Para sites FTP, o InternetConnect realmente estabelece uma conexão com o servidor; para outras pessoas, a conexão real não é estabelecida até que o aplicativo solicite uma transação específica.

Para obter eficiência máxima, os aplicativos que usam os protocolos HTTP devem tentar minimizar as chamadas para InternetConnect e evitar chamar essa função para cada transação solicitada pelo usuário. Uma maneira de fazer isso é manter um pequeno cache de identificadores retornados do InternetConnect; quando o usuário faz uma solicitação para um servidor acessado anteriormente, esse identificador de sessão ainda está disponível.

Depois que o aplicativo de chamada terminar de usar o identificador HINTERNET retornado por InternetConnect, ele deverá ser fechado usando a função InternetCloseHandle .

Nota Quando uma solicitação é enviada no modo assíncrono (o parâmetro dwFlags de InternetOpen especifica INTERNET_FLAG_ASYNC) e o parâmetro dwContext é zero (INTERNET_NO_CALLBACK), a função de retorno de chamada definida com InternetSetStatusCallback no identificador de conexão não será chamada, no entanto, a chamada ainda será executada no modo assíncrono.

Exemplos de uso de InternetConnect podem ser encontrados nos tópicos a seguir.

Como todos os outros aspectos da API WinINet, essa função não pode ser chamada com segurança de dentro de DllMain ou dos construtores e destruidores de objetos globais.

Nota O WinINet não dá suporte a implementações de servidor. Além disso, ele não deve ser usado de um serviço. Para implementações de servidor ou serviços, use Os Serviços HTTP do Microsoft Windows (WinHTTP).
 

Observação

O cabeçalho wininet.h define InternetConnect 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 wininet.h
Biblioteca Wininet.lib
DLL Wininet.dll

Confira também

Habilitando a funcionalidade da Internet

Funções WinINet