Ativando a funcionalidade da Internet

Antes de usar as funções WinINet, o aplicativo deve tentar fazer uma conexão com a Internet usando a funçãoInternetAttemptConnect. Esta função chama a caixa de diálogo dial-up para iniciar uma conexão com a Internet ou verificar se já existe uma conexão. Se essa função falhar, o aplicativo pode entrar no modo offline, o que lhe permite acessar informações que foram armazenadas em cache durante conexões anteriores à Internet.

Use a função InternetCheckConnection para verificar a conexão com a Internet. Ele tenta executar ping no servidor designado pela URL que é passada para a função. Se o sinalizador FLAG_ICC_FORCE_CONNECTION estiver definido e a URL for NULL, a função verificará se há uma entrada no banco de dados do servidor para o servidor mais próximo. Se existir, a função pinga esse servidor.

Em seguida, use a função InternetOpen para estabelecer as características da conexão com a Internet que o aplicativo cliente está usando. InternetOpen cria o identificador deraizHINTERNET que é usado para estabelecer httpsessões de ftp. InternetOpen não testa a conexão com a Internet para verificar se as características passadas para a função estão corretas.

Use a funçãoInternetConnect para criar uma sessão específica. InternetConnect inicializa uma sessão para o site especificado usando os argumentos passados para ele e cria um identificador deHINTERNETque é uma ramificação fora do identificador raiz. InternetConnect não tenta acessar ou estabelecer uma conexão com o site especificado, exceto no caso de uma sessão FTP. FtpFindFirstFile, FtpOpenFilee HttpOpenRequest usam o identificador criado por InternetConnect para estabelecer uma conexão com o site especificado.

Usando InternetOpen

Para habilitar uma conexão com a Internet, um identificador de raiz HINTERNET deve ser criado usando InternetOpen. As informações sobre o agente de utilizador (a aplicação que chama as funções da Internet), o tipo de acesso à Internet, os nomes dos proxies, os hosts e endereços que contornam o proxy, e o comportamento são passadas para InternetOpen.

Definindo o agente de usuário

A aplicação que faz a chamada deve fornecer uma cadeia de caracteres que contenha o nome da aplicação ou entidade que acede à Internet para o parâmetro lpszAgent de InternetOpen. Essa cadeia de caracteres é usada como o agente do usuário no protocolo HTTP. Por exemplo, o Microsoft Internet Explorer usa "Microsoft Internet Explorer".

Definindo tipos de acesso

InternetOpen suporta três tipos de acesso:

• Use INTERNET_OPEN_TYPE_DIRECT se o sistema no qual o aplicativo está sendo executado usa uma conexão direta com a Internet. Os parâmetros lpszProxyName e lpszProxyBypass de InternetOpen não são usados e devem ser definidos como NULL.
• Use INTERNET_OPEN_TYPE_PROXY se o sistema no qual o aplicativo está sendo executado usa um ou mais servidores proxy para acessar a Internet. InternetOpen usa os servidores proxy indicados por lpszProxyName e ignora o proxy para quaisquer nomes de host ou endereços IP especificados por lpszProxyBypass.
• Use INTERNET_OPEN_TYPE_PRECONFIG para instruir seu aplicativo a recuperar a configuração do registro. Esta é normalmente a melhor escolha, uma vez que a maioria das aplicações, incluindo navegadores da Web, utilizam esta opção.

INTERNET_OPEN_TYPE_PRECONFIG examina os valores do Registro ProxyEnable, ProxyServere ProxyOverride. Esses valores estão localizados em "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".

Se ProxyEnable for igual a zero, a aplicação usará INTERNET_OPEN_TYPE_DIRECT. Caso contrário, a aplicação usa INTERNET_OPEN_TYPE_PROXY e as informações do ProxyServer e do ProxyOverride.

As funções WinINet fornecem suporte para proxies do tipo SOCKS somente se o Internet Explorer estiver instalado. A instalação do Internet Explorer inclui o arquivo Wsock32n.dll, que é necessário para suportar proxies SOCKS. Wsock32n.dll não é redistribuível.

Listando servidores proxy

O WinINet reconhece dois tipos de proxies: proxies do tipo CERN (somente HTTP) e proxies FTP TIS (somente FTP). Se o Internet Explorer estiver instalado, o WinINet também suporta proxies do tipo SOCKS. InternetConnect assume, por padrão, que o proxy especificado é um proxy CERN. Se o tipo de acesso estiver definido como INTERNET_OPEN_TYPE_DIRECT ou INTERNET_OPEN_TYPE_PRECONFIG, o parâmetro lpszProxyName de InternetOpen deverá ser definido como NULL. Caso contrário, o valor passado para lpszProxyName deve conter os proxies em uma cadeia de caracteres delimitada por espaço. As listagens de proxy podem conter o número da porta que é usado para acessar o proxy.

Para listar um proxy para um protocolo específico, a cadeia de caracteres deve seguir o formato ""<protocolo><protocolo>://<proxy_name>"". Os protocolos válidos são HTTP, HTTPS e FTP. Por exemplo, para listar um proxy FTP, uma string válida seria ""ftp=ftp://ftp_proxy_name:21"", onde ftp_proxy_name é o nome do proxy FTP e 21 é o número da porta que deve ser usado para acessar o proxy. Se o proxy usar o número de porta padrão para esse protocolo, o número da porta poderá ser omitido. Se um nome de proxy é listado por si só, ele é usado como o proxy padrão para quaisquer protocolos que não têm um proxy específico especificado. Por exemplo, ""http=https://http_proxy outro"" usaria http_proxy para quaisquer operações HTTP, enquanto todos os outros protocolos usariam outro.

Por padrão, a função assume que o proxy especificado por lpszProxyName é um proxy CERN. Um aplicativo pode especificar mais de um proxy, incluindo proxies diferentes para os diferentes protocolos. Por exemplo, se você especificar ""ftp=ftp://ftp://ftp-gw HTTP=https://jericho:99 proxy"", as solicitações FTP são feitas através do proxy ftp-gw, que escuta na porta 21, e as solicitações HTTP são feitas através de um proxy CERN chamado jericho, que escuta na porta 99. Caso contrário, as solicitações HTTP seriam feitas através do proxy CERN chamado proxy, que escuta na porta 80. Observe que se o aplicativo estiver usando apenas FTP, por exemplo, ele não precisaria especificar ""ftp=ftp://ftp-gw:21"". Ele poderia especificar apenas ""ftp-gw"". Uma aplicação só precisa especificar os nomes de protocolo se estiver a usar mais de um protocolo por identificador retornado por InternetOpen.

Listando o Proxy Bypass

Nomes de host ou endereços IP que não devem ser enviados para o proxy podem ser listados na lista de bypass de proxy. Essa lista pode conter curingas, "*", que fazem com que o aplicativo ignore o servidor proxy para endereços que se encaixam no padrão especificado. Para listar vários endereços e nomes de host, separe-os com ponto-e-vírgula na cadeia de caracteres de bypass de proxy. Se a macro "<local>" for especificada, a função ignorará o proxy para qualquer nome de host que não contenha um ponto.

Por padrão, o WinINet ignorará o proxy para solicitações que usam os nomes de host "localhost", "loopback", "127.0.0.1" ou "[::1]". Esse comportamento existe porque um servidor proxy remoto normalmente não resolverá esses endereços corretamente.

Internet Explorer 9: Você pode remover o computador local da lista de exceções do proxy usando a macro "<-loopback>".

O exemplo a seguir mostra chamadas de exemplo para InternetOpen usando diferentes cadeias de proxy bypass. Os comentários acima de cada chamada descrevem o efeito que a cadeia de bypass tem sobre os nomes de host que são acessados a partir do identificador HINTERNET que ele cria.

HINTERNET hInternetRoot;

/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);

/* bypass the proxy for any host name that starts with the 
    letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);

/* bypass the proxy for any host name that contains "int", 
    such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);

/* bypass the proxy for the host name "example" and any 
    host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);

/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);

Usando o InternetConnect

Para iniciar uma sessão, a funçãoInternetConnect deve criar um identificador fora do identificador raiz retornado pela funçãoInternetOpen. InternetConnect define o endereço do servidor, o número da porta, o nome de usuário, a senha e o tipo de serviço.

InternetConnect usa o identificador raiz HINTERNET criado por InternetOpen para estabelecer um identificador de sessão. Se o sinalizador INTERNET_FLAG_ASYNC foi definido na chamada para InternetOpen, a chamada para InternetConnect deve incluir um valor de contexto diferente de zero.

O nome do servidor pode conter o nome do host (por exemplo, "www.servername.com") ou o número IP do site no formato decimal pontilhado ASCII (por exemplo, "10.0.1.45").

A porta do servidor é o número da porta TCP/IP (Transmission Control Protocol/Internet Protocol) ao qual se conectar no servidor. InternetConnect usa a porta padrão para o tipo de serviço selecionado se o valor INTERNET_INVALID_PORT_NUMBER for usado. As tabelas a seguir contêm os padrões de porta do servidor para WinINet.

Definindo o nome de usuário e a senha

O valor de lpszUsername é o endereço de uma cadeia de caracteres terminada por um null que contém o nome do utilizador que está a iniciar sessão. Se esse parâmetro for NULL , a função usará um padrão apropriado, exceto para HTTP. Um parâmetro NULL em HTTP faz com que o servidor retorne um erro. Para o protocolo FTP, o padrão é anônimo.

O valor de lpszPassword é o endereço de um null-terminated string que contém a senha de logon. Se lpszUsername e lpszPassword estiverem NULL, a função usará a senha anônima padrão. No caso do FTP, a senha anônima padrão é o nome de e-mail do usuário. Se lpszUsername não estiver NULL e lpszPassword for NULL, a função usará uma senha em branco. Há quatro configurações possíveis de lpszUsername e lpszPassword, que produzem os comportamentos mostrados na tabela a seguir.

Essas informações podem ser alteradas usando as funções InternetSetOption e InternetErrorDlg. InternetSetOption altera os valores de nome de usuário e senha, enquanto InternetErrorDlg exibe uma caixa de diálogo que solicita o nome de usuário e a senha adequados.

Definindo a sessão

Para definir a sessão que está sendo estabelecida, defina o tipo de serviço, sinalizadores e valor de contexto para InternetConnect.

Há dois tipos de serviço disponíveis para InternetConnect: INTERNET_SERVICE_FTP e INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP é usado para sessões HTTP e HTTPS.

INTERNET_FLAG_PASSIVE é o único sinalizador específico de serviço usado pelas funções WinINet. Esse sinalizador pode ser definido quando o tipo de serviço é INTERNET_SERVICE_FTP para usar a semântica FTP passiva.

Para todas as operações síncronas, o valor de dwContext deve ser definido como zero. Se operações assíncronas tiverem sido estabelecidas definindo o sinalizador INTERNET_FLAG_ASYNC na chamada para InternetOpen, um valor não-zero deve ser fornecido para dwContext. Para obter mais informações sobre operações assíncronas, consulte Configurando operações assíncronas.

Para sessões FTP, InternetConnect tenta estabelecer uma conexão com o servidor na Internet. Para sessões HTTP, InternetConnect não estabelece uma conexão até que outra função tente obter informações do servidor.