Função InternetConnectW (wininet.h)

Artigo
11/20/2024

Abre uma sessão FTP (Protocolo de Transferência de Arquivo) ou HTTP para um determinado site.

Sintaxe

HINTERNET InternetConnectW(
  [in] HINTERNET     hInternet,
  [in] LPCWSTR       lpszServerName,
  [in] INTERNET_PORT nServerPort,
  [in] LPCWSTR       lpszUserName,
  [in] LPCWSTR       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 um cadeia de caracteresterminada nula que especifica o nome do host de um servidor da Internet. Como alternativa, a cadeia de caracteres pode conter o número IP do site, no formato ascii pontilhado-decimal (por exemplo, 11.0.1.45).

[in] nServerPort

Protocolo de Controle de Transmissão/Protocolo de Internet (TCP/IP) no servidor. Esses sinalizadores definem apenas a porta usada. O serviço é definido pelo valor de dwService. Esse parâmetro pode ser 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). Observação Windows XP e Windows Server 2003 R2 e somente 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 um cadeia de caracteresterminada nula que especifica o nome do usuário para 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 um cadeia de caracteresterminada nula que contém a senha a ser usada para fazer logon. Se lpszPassword e lpszUsername estiverem 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 estiver NULL, a função usará uma senha em branco.

[in] dwService

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

Valor	Significado
INTERNET_SERVICE_FTP	Serviço FTP.
INTERNET_SERVICE_GOPHER	Serviço Gopher. Observação Windows XP e Windows Server 2003 R2 e somente anteriores.
INTERNET_SERVICE_HTTP	Serviço HTTP.

[in] dwFlags

Opções específicas para o serviço usado. Se
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.

Valor de retorno

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.

Observações

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 para o servidor FTP
NULL	NULL	"anônimo"	Nome de email do usuário
Cadeia de caracteres de NULL não	NULL	lpszUsername	""
NULL	Cadeia de caracteres de NULL não	ERRO	ERRO
Cadeia de caracteres de NULL não	Cadeia de caracteres de NULL não	lpszUsername	lpszPassword

Para sites FTP, 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 a máxima eficiência, 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 retornado de 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.

Observação Quando uma solicitação é enviada em 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á chamado, no entanto, a chamada ainda será executada no modo assíncrono.

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

manipulando de autenticação
de aplicativo de exemplo assíncrono

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

Observaçã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 ou serviços de servidor, use do Microsoft Windows HTTP Services (WinHTTP).

Nota

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 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	wininet.h
biblioteca	Wininet.lib
de DLL	Wininet.dll

Consulte também

habilitando de funcionalidade da Internet

do WinINet Functions

Compartilhar via