Configuración y recuperación de opciones de Internet

  • Artículo

En este tema se describe cómo establecer y recuperar opciones de Internet mediante las funciones InternetSetOption e InternetQueryOption .

Las opciones de Internet se pueden establecer o recuperar de un identificador HINTERNET especificado o la configuración actual de Microsoft Internet Explorer.

Pasos de implementación

Para establecer o recuperar opciones de Internet, complete lo siguiente:

Elección de opciones de Internet

Dado que hay tantas opciones de Internet, elegir las opciones adecuadas es importante. Muchas opciones de Internet afectan al comportamiento de las funciones winINet e Internet Explorer:

Por ejemplo, puede:

  • Controle la autenticación básica de servidor y proxy estableciendo nombres de usuario y contraseñas.
  • Establezca o recupere la cadena del agente de usuario utilizada por los servidores para identificar las características de la aplicación cliente o el explorador.
  • Recupere el tipo de identificador del identificador HINTERNET especificado.

Para obtener más información y una lista de las opciones de Internet, vea Marcas de opción.

En Internet Explorer 5 y versiones posteriores, se pueden establecer o recuperar algunas opciones de una conexión a Internet específica mediante las estructuras INTERNET_PER_CONN_OPTION_LIST y INTERNET_PER_CONN_OPTION . Para obtener más información y una lista de opciones que se pueden establecer o recuperar de una conexión a Internet específica, consulte el miembro dwOptions de la estructura INTERNET_PER_CONN_OPTION .

Elección del identificador HINTERNET

El identificador HINTERNET usado para establecer o recuperar opciones de Internet determina el ámbito de la operación. Todos los identificadores creados a través de este identificador heredarán las opciones establecidas en este identificador.

Por ejemplo, las aplicaciones cliente que requieren un proxy con autenticación, probablemente no requieran establecer el nombre de usuario y la contraseña del proxy cada vez que la aplicación intente acceder a un recurso de Internet. Si todas las solicitudes de una conexión determinada se controlan mediante el mismo proxy, establecer el nombre de usuario y la contraseña del proxy en un identificador HINTERNET de tipo de conexión, es decir, un identificador creado por una llamada a InternetConnect, permitiría que las llamadas derivadas de este identificador HINTERNET usen el mismo nombre de usuario y contraseña de proxy. La configuración del nombre de usuario y la contraseña del proxy cada vez que HttpOpenRequest crea un identificador HINTERNET requeriría una sobrecarga adicional e innecesaria. Tenga en cuenta que si la aplicación usa un proxy que requiere autenticación, debe establecer las credenciales de proxy en cada conexión nueva.

Establecer o recuperar las opciones

Cuando haya determinado qué opciones de Internet y HINTERNET usar, recupere esas opciones de Internet. Para establecer o recuperar opciones, llame a InternetQueryOption o InternetSetOption.

Ámbito del identificador HINTERNET

El identificador HINTERNET usado para establecer o recuperar opciones de Internet determina las acciones para las que las opciones son válidas.

Estos identificadores tienen tres niveles:

  • El identificador HINTERNET raíz (creado por una llamada a InternetOpen) contendrá todas las opciones de Internet que afectan a esta instancia de WinINet.
  • HINTERNET controla que se conectan a un servidor (creado por una llamada a InternetConnect)
  • HINTERNET controla asociados a un recurso o enumeración de recursos en un servidor determinado.

Además de los distintos identificadores HINTERNET , una aplicación también puede usar NULL para establecer o recuperar los valores predeterminados de las opciones de Internet usadas por Internet Explorer y las funciones winINet. Al establecer opciones de Internet cuando se usa NULL , el identificador cambia los valores predeterminados de las opciones, que se almacenan actualmente en el registro. Las aplicaciones cliente no deben usar funciones del Registro para cambiar los valores predeterminados de las opciones de Internet, ya que la implementación de cómo se almacenan las opciones se puede modificar en el futuro.

En la tabla siguiente se muestra el tipo de identificadores HINTERNET y el ámbito de las opciones de Internet asociadas a ellas.

Tipo de identificador Ámbito
NULL La configuración de opción predeterminada para Internet Explorer.
INTERNET_HANDLE_TYPE_CONNECT_FTP La configuración de la opción para esta conexión a un servidor FTP. Estas opciones afectan a las operaciones iniciadas desde este identificador HINTERNET , como las descargas de archivos.
INTERNET_HANDLE_TYPE_CONNECT_GOPHER La configuración de la opción para esta conexión a un servidor Gopher. Estas opciones afectan a las operaciones iniciadas desde este identificador HINTERNET , como las descargas de archivos. Nota: Windows XP y Windows Server 2003 R2 y versiones anteriores.
INTERNET_HANDLE_TYPE_CONNECT_HTTP La configuración de la opción para esta conexión a un servidor HTTP. Estas opciones afectan a las operaciones iniciadas desde este identificador HINTERNET , como las descargas de archivos.
INTERNET_HANDLE_TYPE_FILE_REQUEST La configuración de la opción asociada a esta solicitud de archivo.
INTERNET_HANDLE_TYPE_FTP_FILE La configuración de la opción asociada a esta descarga de recursos FTP.
INTERNET_HANDLE_TYPE_FTP_FILE_HTML La configuración de la opción asociada a esta descarga de recursos FTP con formato HTML.
INTERNET_HANDLE_TYPE_FTP_FIND La configuración de opción asociada a esta búsqueda de archivos en un servidor FTP.
INTERNET_HANDLE_TYPE_FTP_FIND_HTML La configuración de opción asociada a esta búsqueda de archivos en un servidor FTP con formato HTML.
INTERNET_HANDLE_TYPE_GOPHER_FILE La configuración de la opción asociada a esta descarga de recursos de Gopher. Nota: Windows XP y Windows Server 2003 R2 y versiones anteriores.
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML La configuración de la opción asociada a esta descarga de recursos de Gopher con formato HTML. Nota: Windows XP y Windows Server 2003 R2 y versiones anteriores.
INTERNET_HANDLE_TYPE_GOPHER_FIND La configuración de opción asociada a esta búsqueda de archivos en un servidor Gopher. Nota: Windows XP y Windows Server 2003 R2 y versiones anteriores.
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML La configuración de opción asociada a esta búsqueda de archivos en un servidor Gopher con formato HTML. Nota: Windows XP y Windows Server 2003 R2 y versiones anteriores.
INTERNET_HANDLE_TYPE_HTTP_REQUEST La configuración de la opción asociada a esta solicitud HTTP.
INTERNET_HANDLE_TYPE_INTERNET La configuración de la opción asociada a esta instancia de las funciones de WinINet.

Establecer opciones individuales

Después de determinar las opciones de Internet que desea establecer y el ámbito que desea que se vea afectado por estas opciones, establecer opciones de Internet no es complicado. Lo único que tendría que hacer es llamar a la función InternetSetOption con el identificador HINTERNET deseado, la marca de opción de Internet y un búfer que contenga la información que desea establecer.

En el ejemplo siguiente se muestra cómo establecer el nombre de usuario proxy y la contraseña en un 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);

Recuperación de opciones individuales

Las opciones de Internet se pueden recuperar mediante la función InternetQueryOption . Para recuperar las opciones de Internet:

  1. Determine el tamaño del búfer necesario para recuperar la información de opciones de Internet.

    El tamaño del búfer se puede determinar mediante NULL para la dirección del búfer y pasarle un tamaño de búfer de cero.

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

    El valor devuelto por InternetQueryOption es la cantidad de memoria necesaria para recuperar la información, en bytes.

  2. Asigne una memoria para el búfer.

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

  3. Recupere los datos.

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

  4. Libere la memoria.

    delete [] lpszData;

Ejemplo completo

A continuación se muestra el ejemplo completo que se usa en la sección anterior. En este ejemplo se muestra cómo recuperar la cadena predeterminada del agente de usuario.

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

Establecer opciones de conexión

En Internet Explorer 5 y versiones posteriores, las opciones de Internet se pueden establecer para en una conexión específica. Anteriormente, todas las conexiones comparten la misma configuración de opciones de Internet. Para establecer las opciones de una conexión determinada:

  1. Cree una estructura de INTERNET_PER_CONN_OPTION_LIST .
  2. Asigne la memoria para las opciones individuales de Internet que desea establecer para la conexión.
  3. Establezca las opciones de INTERNET_PER_CONN_OPTION estructuras.
  4. Establezca las opciones mediante InternetSetOption.

En el ejemplo de código siguiente se muestra cómo establecer datos de proxy para una conexión 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;
}

Recuperación de opciones de conexión

En Internet Explorer 5 y versiones posteriores, las opciones de Internet se pueden recuperar de una conexión específica. Para recuperar opciones de una conexión determinada:

  1. Cree una estructura INTERNET_PER_CONN_OPTION_LIST .
  2. Asigne la memoria para las opciones individuales de Internet que se van a recuperar de la conexión.
  3. Especifique las opciones mediante estructuras de INTERNET_PER_CONN_OPTION .
  4. Recupere las opciones mediante InternetQueryOption.
  5. Utilice los datos de la opción.
  6. Libere la memoria asignada para contener los datos de opción mediante la función GlobalFree .

Nota:

WinINet no admite implementaciones de servidor. Además, no se debe usar desde un servicio. En el caso de las implementaciones de servidor o los servicios, use Servicios HTTP de Microsoft Windows (WinHTTP).

Control de la autenticación

Identificadores HINTERNET