Habilitando 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ção InternetAttemptConnect . Essa função chama a caixa de diálogo discada para iniciar uma conexão com a Internet ou marcar se uma conexão já existir. Se essa função falhar, o aplicativo poderá entrar no modo offline, o que permite que ele acesse informações armazenadas em cache durante conexões anteriores com a Internet.

Use a função InternetCheckConnection para marcar 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 executará ping nesse 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 HINTERNET raiz usado para estabelecer sessões de ftp http. O 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ção InternetConnect para criar uma sessão específica. O InternetConnect inicializa uma sessão para o site especificado usando os argumentos passados para ele e cria um identificador HINTERNET que é um branch fora do identificador raiz. O InternetConnect não tenta acessar nem estabelecer uma conexão com o site especificado, exceto no caso de uma sessão FTP. As funções FtpFindFirstFile, FtpOpenFile e HttpOpenRequest usam o identificador criado pelo InternetConnect para estabelecer uma conexão com o site especificado.

Usando InternetOpen

Para habilitar uma conexão com a Internet, um identificador HINTERNET raiz deve ser criado usando InternetOpen. Informações sobre o agente de usuário (o aplicativo que chama as funções da Internet), o tipo de acesso à Internet, os nomes de proxy, os hosts e endereços que ignoram o proxy e o comportamento são passados para InternetOpen.

Definindo o Agente de Usuário

O aplicativo de chamada deve fornecer uma cadeia de caracteres que contenha o nome do aplicativo ou entidade que acessa a Internet para o parâmetro lpszAgent de InternetOpen. Essa cadeia de caracteres é usada como o agente de usuário no protocolo HTTP. Por exemplo, o Microsoft Internet Explorer usa "Microsoft Internet Explorer".

Configurando tipos de acesso

O InternetOpen dá suporte a três tipos de acesso:

• Use INTERNET_OPEN_TYPE_DIRECT se o sistema no qual o aplicativo está em execução usar 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á em execução usar um ou mais servidores proxy para acessar a Internet. O 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. Normalmente, essa é a melhor opção, pois a maioria dos aplicativos, incluindo navegadores da Web, usa essa opção.

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

Se ProxyEnable for zero, o aplicativo usará INTERNET_OPEN_TYPE_DIRECT. Caso contrário, o aplicativo usa INTERNET_OPEN_TYPE_PROXY e usa as informações proxyServer e ProxyOverride .

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

Listando servidores proxy

O WinINet reconhece dois tipos de proxies: proxies de tipo CERN (somente HTTP) e proxies FTP do TIS (somente FTP). Se o Explorer da Internet estiver instalado, o WinINet também oferecerá suporte a proxies de tipo SOCKS. InternetConnect pressupõe, 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 usado para acessar o proxy.

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

Por padrão, a função pressupõe que o proxy especificado por lpszProxyName seja 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-gw HTTP=https://jericho:99 proxy"", as solicitações FTP serão feitas por meio do proxy ftp-gw, que escuta na porta 21, e as solicitações HTTP são feitas por meio de um proxy CERN chamado jericho, que escuta na porta 99. Caso contrário, as solicitações HTTP seriam feitas por meio do proxy CERN chamado proxy, que escuta na porta 80. Observe que, se o aplicativo estiver usando apenas FTP, por exemplo, ele não precisará especificar ""ftp=ftp://ftp-gw:21"". Ele poderia especificar apenas ""ftp-gw"". Um aplicativo só será necessário para especificar os nomes de protocolo se estiver usando mais de um protocolo por identificador retornado pelo InternetOpen.

Listando o bypass de proxy

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 caracteres curinga, "*", 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 do proxy. Se a macro "<local>" for especificada, a função ignorará o proxy para qualquer nome de host que não contenha um período.

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 resolve esses endereços corretamente.

Internet Explorer 9: você pode remover o computador local da lista de bypass de proxy usando a macro "<-loopback>".

O exemplo a seguir mostra chamadas de exemplo para InternetOpen usando cadeias de caracteres de bypass de proxy diferentes. Os comentários acima de cada chamada descrevem o efeito que a cadeia de caracteres de bypass tem nos nomes de host acessados 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 InternetConnect

Para iniciar uma sessão, a função InternetConnect deve criar um identificador fora do identificador raiz retornado pela função InternetOpen . 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.

O InternetConnect usa o identificador HINTERNET raiz criado pelo InternetOpen para estabelecer um identificador de sessão. Se o sinalizador INTERNET_FLAG_ASYNC foi definido na chamada para InternetOpen, a chamada para InternetConnect deverá 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 protocolo TCP/IP para conexão no servidor. O InternetConnect usará 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 em nulo que contém o nome do usuário que está fazendo logon. 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 uma cadeia de caracteres terminada em nulo que contém a senha de logon. Se lpszUsername e lpszPassword forem NULL, a função usará a senha anônima padrão. No caso de FTP, a senha anônima padrão é o nome de email do usuário. Se lpszUsername não for 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, os sinalizadores e o 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 do serviço usado pelas funções WinINet. Esse sinalizador pode ser definido quando o tipo de serviço é INTERNET_SERVICE_FTP para usar 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 foram estabelecidas definindo o sinalizador INTERNET_FLAG_ASYNC na chamada para InternetOpen, um valor diferente de zero deverá ser fornecido para dwContext. Para obter mais informações sobre operações assíncronas, consulte Configurando operações assíncronas.

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