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 |
|---|---|
|
Usa a porta padrão para servidores FTP (porta 21). |
|
Usa a porta padrão para servidores Gopher (porta 70). Nota Somente Windows XP e Windows Server 2003 R2 e anteriores.
|
|
Usa a porta padrão para servidores HTTP (porta 80). |
|
Usa a porta padrão para servidores HTTPS (Secure Hypertext Transfer Protocol) (porta 443). |
|
Usa a porta padrão para servidores de firewall SOCKS (porta 1080). |
|
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 |
|---|---|
|
Serviço FTP. |
|
Serviço Gopher. Nota Somente Windows XP e Windows Server 2003 R2 e anteriores.
|
|
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.
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 |