Función WinHttpCloseHandle (winhttp.h)

  • Artículo

La función WinHttpCloseHandle cierra un único identificador HINTERNET (consulte HINTERNET Handles in WinHTTP).

Sintaxis

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

Parámetros

[in] hInternet

Un identificador HINTERNET válido (vea HINTERNET Handles in WinHTTP) que se va a cerrar.

Valor devuelto

TRUE si el identificador se cierra correctamente; de lo contrario, FALSE. Para obtener información de error extendida, llame a GetLastError. Entre los códigos de error devueltos se incluyen los siguientes.

Códigos de error Descripción
ERROR_WINHTTP_SHUTDOWN
 La compatibilidad con la función WinHTTP se está apagando o descargando.
ERROR_WINHTTP_INTERNAL_ERROR
 Se ha producido un error interno.
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.

Si hay una devolución de llamada de estado registrada para el identificador que se está cerrando y el identificador se creó con un valor de contexto distinto de NULL , se realiza una devolución de llamada WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Esta es la última devolución de llamada realizada desde el identificador e indica que el identificador se está destruyendo.

Una aplicación puede finalizar una solicitud asincrónica en curso cerrando el identificador de solicitud HINTERNET mediante WinHttpCloseHandle. No olvides estas cuestiones:

  • Después de que una aplicación llame a WinHttpCloseHandle en un identificador WinHTTP, no puede llamar a ninguna otra función de API de WinHTTP mediante ese identificador desde ningún subproceso.
  • Incluso después de una llamada a WinHttpCloseHandle , la aplicación debe estar preparada para recibir devoluciones de llamada para el identificador cerrado, ya que WinHTTP puede anular el identificador de forma asincrónica. Si la solicitud asincrónica no se pudo completar correctamente, la devolución de llamada recibe una notificación de WINHTTP_CALLBACK_STATUS_REQUEST_ERROR.
  • Si una aplicación asocia una estructura de datos de contexto o un objeto con el identificador, debe mantener ese enlace hasta que la función de devolución de llamada reciba una notificación de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Esta es la última notificación de devolución de llamada que WinHTTP envía antes de eliminar un objeto de identificador de la memoria. Para recibir la notificación de devolución de llamada WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , la aplicación debe habilitar la marca WINHTTP_CALLBACK_FLAG_HANDLES en la llamada WinHttpSetStatusCallback .
  • Antes de llamar a WinHttpCloseHandle, una aplicación puede llamar a WinHttpSetStatusCallback para indicar que no se deben realizar más devoluciones de llamada:

    WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

    Es posible que parezca que la estructura de datos de contexto podría liberarse inmediatamente en lugar de tener que esperar una notificación de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , pero no es el caso: WinHTTP no sincroniza WinHttpSetStatusCallback con devoluciones de llamada que se originan en subprocesos de trabajo. Como resultado, una devolución de llamada ya podría estar en curso desde otro subproceso, y la aplicación podría recibir una notificación de devolución de llamada incluso después de haber eliminado el puntero de la función de devolución de llamada null y eliminar la estructura de datos de contexto del controlador. Debido a esta posible condición de carrera, sea conservador al liberar la estructura de contexto hasta después de haber recibido la notificación de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING .

Una aplicación nunca debe llamar a WinHttpCloseHandle en una solicitud sincrónica. Esto puede crear una condición de carrera. Consulte HINTERNET Handles in WinHTTP (Identificadores HINTERNET en WinHTTP ) para obtener más información.
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.
 

Requisitos

Requisito Value
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.

Consulte también

Acerca de los servicios HTTP de Microsoft Windows (WinHTTP)

Versiones winHTTP

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest