Configuração e recuperação de opções da Internet

Este tópico descreve como definir e recuperar opções da Internet usando as funções InternetSetOption e InternetQueryOption .

As opções da Internet podem ser definidas em ou recuperadas de um identificador especificado de HINTERNET ou das configurações atuais no Microsoft Internet Explorer.

• Etapas de implementação
  • Escolhendo opções da Internet
  • Escolhendo o identificador HINTERNET
  • Definindo ou recuperando as opções
• Escopo do HINTERNET Handle
• Definindo opções individuais
• Recuperando opções individuais
  • Amostra completa
• Definindo opções de conexão
• Recuperando opções de conexão
• Tópicos relacionados

Etapas de implementação

Para definir ou recuperar opções da Internet, preencha o seguinte:

• Escolhendo opções da Internet
• Escolhendo o manipulador HINTERNET
• Definindo ou recuperando as opções

Escolher opções da Internet

Porque existem tantas opções de Internet, escolher as opções certas é importante. Muitas opções da Internet afetam o comportamento das funções WinINet e do Internet Explorer:

Por exemplo, você pode:

• Manipule a autenticação básica de servidor e proxy definindo nomes de usuário e senhas.
• Defina ou recupere a cadeia de caracteres do agente do usuário usada pelos servidores para identificar os recursos do aplicativo cliente ou navegador.
• Recupere o tipo de identificador do identificador deespecificadoHINTERNET.

Para obter mais informações e uma lista das opções da Internet, consulte Sinalizadores de opção.

No Internet Explorer 5 e versões posteriores, algumas opções podem ser definidas ou recuperadas de uma conexão específica com a Internet usando as estruturas INTERNET_PER_CONN_OPTION_LIST e INTERNET_PER_CONN_OPTION. Para obter mais informações e uma lista de opções que podem ser definidas ou recuperadas de uma conexão de Internet específica, consulte o membro dwOptions da estrutura INTERNET_PER_CONN_OPTION.

Escolhendo o identificador HINTERNET

O identificador de HINTERNET usado para definir ou recuperar opções da Internet determina o âmbito da operação. Todas as alças criadas através dessa alça herdarão as opções definidas nessa alça.

Por exemplo, os aplicativos cliente que exigem um proxy com autenticação, provavelmente não exigem a configuração do nome de usuário e senha do proxy toda vez que o aplicativo tenta acessar um recurso da Internet. Se todas as solicitações em uma determinada conexão forem tratadas pelo mesmo proxy, definir o nome de utilizador e a palavra-passe do proxy num identificador de tipo de conexão HINTERNET, ou seja, um identificador criado por uma chamada para InternetConnect, permitirá que quaisquer chamadas derivadas desse identificador HINTERNET usem o mesmo nome de utilizador e palavra-passe do proxy. Definir o nome de utilizador e a senha do proxy sempre que um identificador de HINTERNET é criado por , HttpOpenRequest exigiria sobrecarga extra e desnecessária. Lembre-se de que, se o aplicativo usa um proxy que requer autenticação, ele deve definir as credenciais de proxy em cada nova conexão.

Definindo ou recuperando as opções

Quando você tiver determinado quais opções da Internet e HINTERNET manipulador usar, recupere essas opções da Internet. Para definir ou recuperar opções, chame InternetQueryOption ou InternetSetOption.

Âmbito do HINTERNET Handle

O identificador deHINTERNETusado para definir ou recuperar opções da Internet determina as ações para as quais as opções são válidas.

Estas alças têm três níveis:

• O identificador raiz HINTERNET (criado por uma chamada para InternetOpen) conteria todas as opções da Internet que afetam esta instância do WinINet.
• identificadores de HINTERNET que se conectam a um servidor (criado por uma chamada para InternetConnect)
• HINTERNET manipuladores associados a um recurso ou enumeração de recursos num servidor específico.

Além dos vários identificadores de HINTERNET, um aplicativo também pode usar NULL para definir ou recuperar os valores padrão das opções da Internet utilizadas pelo Internet Explorer e pelas funções WinINet. Definir opções da Internet ao usar NULL como o manipulador altera os valores padrão das opções, que estão atualmente armazenados no registo. Os aplicativos cliente não devem usar funções do Registro para alterar os valores padrão das opções da Internet, porque a implementação de como as opções são armazenadas pode ser alterada no futuro.

A tabela a seguir lista os tipos de manipuladores de HINTERNET e o escopo das opções de Internet associadas a eles.

Definindo opções individuais

Depois de determinar as opções da Internet que você deseja definir e o escopo que você deseja que seja afetado por essas opções, definir as opções da Internet não é complicado. Tudo o que você precisa fazer é chamar o função InternetSetOption com o identificador deHINTERNETdesejado, sinalizador de opção da Internet e um buffer que contém as informações que você deseja definir.

O exemplo a seguir mostra como definir o nome de utilizador e a senha do proxy num identificador de HINTERNET especificado.

// strUsername is a string buffer of cchMax characters or less.
// It contains the proxy user name.
size_t cchMax = 80;
size_t cchUserLength, cchPasswordLength;
HRESULT hr = StringCchLength(strUsername, cchMax, &cchUserLength);

if (SUCCEEDED(hr))
{
   // hOpen is the HINTERNET handle created by InternetConnect.
   InternetSetOption(hConnect, INTERNET_OPTION_PROXY_USERNAME,
      strUsername, DWORD(cchUserLength)+1);
}
else
{
   // Insert error handling code here.
}

// strPassword is the string buffer that contains the proxy password.
hr = StringCchLength(strPassword, cchMax, &cchPasswordLength);

InternetSetOption(hOpen, INTERNET_OPTION_PROXY_PASSWORD,
    strPassword, DWORD(cchPasswordLength)+1);

Recuperando opções individuais

As opções da Internet podem ser recuperadas usando a função InternetQueryOption. Para recuperar opções da Internet:

1. Determine o tamanho do buffer necessário para recuperar as informações de opção da Internet.

   O tamanho do buffer pode ser determinado usando NULL para o endereço do buffer e passando-lhe um tamanho de buffer de zero.

   DWORD dwSize;
   InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);
   

   O valor retornado por InternetQueryOption é a quantidade de memória necessária para recuperar as informações, em bytes.

2. Aloque uma memória para o buffer.

   char *lpszData;
   lpszData = new char[dwSize];
   

3. Recupere os dados.

   InternetQueryOption( NULL, 
                        INTERNET_OPTION_USER_AGENT,
                        lpszData, &dwSize );
   

4. Liberte a memória.

   delete [] lpszData;
   

Amostra completa

A seguir está o exemplo completo usado na seção anterior. Este exemplo mostra como recuperar a cadeia de caracteres padrão do agente do usuário.

// This call determines the required buffer size.
DWORD dwSize;
InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);

// Allocate the necessary memory.
char *lpszData;
lpszData = new char[dwSize];

// Call InternetQueryOption again with the provided buffer.
InternetQueryOption( NULL, 
                     INTERNET_OPTION_USER_AGENT,
                     lpszData, &dwSize );

// Insert code here to use the user agent string data.

// Free the allocated memory.
delete [] lpszData;

Definindo opções de conexão

No Internet Explorer 5 e versões posteriores, as opções da Internet podem ser definidas para uma conexão específica. Anteriormente, todas as conexões compartilhavam as mesmas configurações de opção da Internet. Para definir opções para uma conexão específica:

1. Crie uma estrutura INTERNET_PER_CONN_OPTION_LIST.
2. Aloque a memória para as opções individuais da Internet que você deseja definir para a conexão.
3. Defina as opções nas estruturas INTERNET_PER_CONN_OPTION.
4. Defina as opções usando InternetSetOption.

O exemplo de código a seguir mostra como definir dados de proxy para uma conexão LAN.

BOOL SetConnectionOptions()
{
    INTERNET_PER_CONN_OPTION_LIST list;
    BOOL    bReturn;
    DWORD   dwBufSize = sizeof(list);

    // Fill the list structure.
    list.dwSize = sizeof(list);

    // NULL == LAN, otherwise connectoid name.
    list.pszConnection = NULL;

    // Set three options.
    list.dwOptionCount = 3;
    list.pOptions = new INTERNET_PER_CONN_OPTION[3];

    // Ensure that the memory was allocated.
    if(NULL == list.pOptions)
    {
        // Return FALSE if the memory wasn't allocated.
        return FALSE;
    }

    // Set flags.
    list.pOptions[0].dwOption = INTERNET_PER_CONN_FLAGS;
    list.pOptions[0].Value.dwValue = PROXY_TYPE_DIRECT |
        PROXY_TYPE_PROXY;

    // Set proxy name.
    list.pOptions[1].dwOption = INTERNET_PER_CONN_PROXY_SERVER;
    list.pOptions[1].Value.pszValue = TEXT("https://proxy:80");

    // Set proxy override.
    list.pOptions[2].dwOption = INTERNET_PER_CONN_PROXY_BYPASS;
    list.pOptions[2].Value.pszValue = TEXT("local");

    // Set the options on the connection.
    bReturn = InternetSetOption(NULL,
        INTERNET_OPTION_PER_CONNECTION_OPTION, &list, dwBufSize);

    // Free the allocated memory.
    delete [] list.pOptions;

    return bReturn;
}

Recuperando opções de conexão

No Internet Explorer 5 e posterior, as opções da Internet podem ser recuperadas de uma conexão específica. Para recuperar opções de uma conexão específica:

1. Crie uma estrutura INTERNET_PER_CONN_OPTION_LIST.
2. Aloque a memória para as opções individuais da Internet para recuperar da conexão.
3. Especifique as opções usando estruturas INTERNET_PER_CONN_OPTION.
4. Recupere as opções usando InternetQueryOption.
5. Utilize os dados das opções.
6. Liberte a memória, alocada para armazenar os dados da opção, usando a função GlobalFree.

Tópicos relacionados

Manipulação de autenticação

HINTERNET gerencia