Función WinHttpQueryOption (winhttp.h)

Artículo
08/27/2023

La función WinHttpQueryOption consulta una opción de Internet en el identificador especificado.

Sintaxis

WINHTTPAPI BOOL WinHttpQueryOption(
  [in]      HINTERNET hInternet,
  [in]      DWORD     dwOption,
  [out]     LPVOID    lpBuffer,
  [in, out] LPDWORD   lpdwBufferLength
);

Parámetros

[in] hInternet

Identificador HINTERNET en el que se va a consultar información. Tenga en cuenta que esto puede ser un identificador de sesión o un identificador de solicitud, dependiendo de la opción que se consulta; consulte el tema Marcas de opción para determinar qué identificador es adecuado para usarlo en la consulta de una opción determinada.

[in] dwOption

Valor entero largo sin signo que contiene la opción internet que se va a consultar. Puede ser uno de los valores de Marcas de opción .

[out] lpBuffer

Puntero a un búfer que recibe la configuración de opción. Las cadenas devueltas por la función WinHttpQueryOption se asignan globalmente, por lo que la aplicación que realiza la llamada debe liberar globalmente la cadena cuando termine de usarla. Establecer este parámetro en NULL hace que esta función devuelva FALSE. La llamada a GetLastError devuelve ERROR_INSUFFICIENT_BUFFER y lpdwBufferLength contiene el número de bytes necesarios para contener la información solicitada.

[in, out] lpdwBufferLength

Puntero a una variable de entero largo sin signo que contiene la longitud de lpBuffer, en bytes. Cuando la función devuelve, la variable recibe la longitud de los datos colocados en lpBuffer. Si GetLastError devuelve ERROR_INSUFFICIENT_BUFFER, este parámetro recibe el número de bytes necesarios para contener la información solicitada.

Valor devuelto

Devuelve TRUE si se ejecuta correctamente o FALSE de lo contrario. Para obtener un mensaje de error específico, llame a GetLastError. Entre los códigos de error devueltos se encuentran los siguientes:

Código de error	Descripción
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	No se puede llevar a cabo la operación solicitada porque el identificador proporcionado no está en el estado correcto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	El tipo de identificador proporcionado es incorrecto para esta operación.
ERROR_WINHTTP_INTERNAL_ERROR	Se ha producido un error interno.
ERROR_WINHTTP_INVALID_OPTION	Se especificó un valor de opción no válido.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows)

Comentarios

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando WINHTTP_FLAG_ASYNC se ha establecido en WinHttpOpen), esta función funciona de forma sincrónica. El valor devuelto indica éxito o error. Para obtener información de error extendida, llame a GetLastError.

GetLastError devuelve el ERROR_INVALID_PARAMETER si se pasa una marca de opción no válida para el tipo de identificador especificado al parámetro dwOption .

Nota Para Windows XP y Windows 2000, consulta la sección Requisitos en tiempo de ejecución de la página de inicio de WinHttp.

Ejemplos

En este ejemplo se muestra cómo recuperar el valor de tiempo de espera de conexión:

    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Requisitos


Cliente mínimo compatible	Windows XP, Windows 2000 Professional con SP3 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003, Windows 2000 Server con SP3 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winhttp.h
Library	Winhttp.lib
Archivo DLL	Winhttp.dll
Redistribuible	WinHTTP 5.0 e Internet Explorer 5.01 o posterior en Windows XP y Windows 2000.