Configurando e recuperando 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 ou recuperadas de um identificador HINTERNET especificado ou as configurações atuais no Microsoft Internet Explorer.

• Etapas de implementação
  • Escolhendo opções da Internet
  • Escolhendo o identificador HINTERNET
  • Configurando ou recuperando as opções
• Escopo do identificador HINTERNET
• Definindo opções individuais
• Recuperando opções individuais
  • Exemplo completo
• 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, conclua o seguinte:

• Escolhendo opções da Internet
• Escolhendo o identificador HINTERNET
• Configurando ou recuperando as opções

Escolhendo opções da Internet

Como há tantas opções de Internet, escolher as opções certas é importante. Muitas opções da Internet afetam o comportamento das funções WinINet e da 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 HINTERNET especificado.

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

Na Internet Explorer 5 e posteriores, algumas opções podem ser definidas ou recuperadas de uma conexão de Internet específica 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 HINTERNET usado para definir ou recuperar opções da Internet determina o escopo da operação. Todos os identificadores criados por meio desse identificador herdarão as opções definidas nesse identificador.

Por exemplo, aplicativos cliente que exigem um proxy com autenticação, provavelmente não exigem a configuração do nome de usuário proxy e senha sempre 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 usuário proxy e a senha em um identificador HINTERNET do tipo de conexão, ou seja, um identificador criado por uma chamada para InternetConnect, permitirá que todas as chamadas derivadas desse identificador HINTERNET usem o mesmo nome de usuário proxy e senha. Definir o nome de usuário proxy e a senha sempre que um identificador HINTERNET for 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.

Configurando ou recuperando as opções

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

Escopo do identificador HINTERNET

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

Esses identificadores têm três níveis:

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

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

A tabela a seguir lista o tipo de identificadores HINTERNET e o escopo das opções da Internet associadas a eles.

Definindo opções individuais

Depois de determinar as opções da Internet que você deseja definir e o escopo desejado afetado por essas opções, definir opções da Internet não é complicado. Basta chamar a função InternetSetOption com o identificador HINTERNET desejado, o 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 usuário proxy e a senha em um identificador 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-o 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. Alocar 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. Libere a memória.

   delete [] lpszData;
   

Exemplo completo

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

// 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

Na Internet Explorer 5 e posteriores, as opções de Internet podem ser definidas para em 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 de 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 em estruturas de 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

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

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

Tópicos relacionados

Tratar a autenticação

Identificadores HINTERNET