Identificadores HINTERNET en WinHTTP

Los servicios HTTP de Microsoft Windows (WinHTTP) usan identificadores para realizar un seguimiento de la configuración y la información necesarias al usar el protocolo HTTP. Cada identificador mantiene información pertinente para una sesión HTTP, una conexión con un servidor HTTP o un recurso específico. En este tema se describen los distintos tipos de identificadores, las convenciones de nomenclatura de estos identificadores y su estructura jerárquica.

• Acerca de los identificadores HINTERNET
• Identificadores de nomenclatura
• Controlar la jerarquía
• Explicación de la jerarquía de identificadores

Acerca de los identificadores HINTERNET

Los identificadores creados y usados por WinHTTP se denominan identificadores HINTERNET . Las funciones WinHTTP devuelven identificadores HINTERNET que no son intercambiables con otros identificadores, por lo que no se pueden usar con funciones como ReadFile o CloseHandle. Del mismo modo, no se pueden usar otros identificadores con funciones WinHTTP. Por ejemplo, un identificador devuelto por CreateFile no se puede pasar a WinHttpReadData. Estos identificadores HINTERNET no se pueden cerrar mientras una llamada API mediante el identificador está en curso. Para evitar una condición de carrera, las aplicaciones deben proteger el identificador y evitar que se cierren mientras la llamada API esté en curso.

Las funciones de Microsoft Win32 Internet (WinInet) también usan identificadores HINTERNET . Sin embargo, los identificadores usados en las funciones de WinInet no se pueden intercambiar con los identificadores usados en las funciones winHTTP. Para obtener más información sobre WinInet, consulte Acerca de WinINet.

La función WinHttpCloseHandle cierra los identificadores winHTTP HINTERNET .

Identificadores de nomenclatura

En la documentación de WinHTTP, las descripciones de las funciones de la interfaz de programación de aplicaciones (API) y el código de ejemplo muestran la creación y el uso de varios tipos de identificadores HINTERNET . Para realizar un seguimiento de los diferentes tipos de identificadores disponibles, la nomenclatura de estos identificadores es coherente. En la tabla siguiente se muestran los identificadores usados por convención en la documentación.

Tipo de identificador	Controlador de creación de funciones	Identificador
Identificador genérico	WinHttpOpen, WinHttpConnect o WinHttpOpenRequest	hInternet
Identificador de sesión	WinHttpOpen	hSession
Identificador de conexión	WinHttpConnect	hConnect
Identificador de solicitud	WinHttpOpenRequest	hRequest
Identificador de socket web	WinHttpWebSocketCompleteUpgrade	hWebSocket

Controlar la jerarquía

Los identificadores HINTERNET se mantienen en una jerarquía. El identificador devuelto por WinHttpOpen es el identificador HINTERNET de sesión. Al llamar a WinHttpOpen , se inicializan las funciones winHTTP y se inicia un contexto de sesión que mantiene la información y la configuración del usuario durante toda la vida útil del identificador de sesión. WinHttpConnect especifica un servidor HTTP o HTTPS de destino y crea un identificador HINTERNET de conexión. De forma predeterminada, el identificador de conexión hereda la configuración del identificador de sesión. A cada recurso especificado con una llamada a WinHttpOpenRequest se le asigna un identificador HINTERNET de solicitud.

En el diagrama siguiente se muestra la jerarquía de identificadores HINTERNET . Cada cuadro del diagrama representa una función WinHTTP que devuelve un identificador HINTERNET .

Después de cerrar un identificador, la aplicación debe estar preparada para recibir notificaciones de devolución de llamada en el identificador hasta que se devuelva el valor de WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED final para indicar que el identificador está completamente cerrado (o hasta que la aplicación realice su propia sincronización equivalente, como el seguimiento y la espera de las devoluciones de llamada de las operaciones asincrónicas pendientes y asegurarse de que no se intente usar ese identificador).

Un identificador de sesión se denomina elemento primario de cualquier identificador de conexión que se usó para crear; del mismo modo, tanto el identificador de conexión como su identificador de sesión primario se denominan elementos primarios de cualquier identificador de solicitud que se use para crear el identificador de conexión.

Cuando se cierra un identificador primario, los elementos secundarios que se han invalidado indirectamente incluso si no se cierran, y las solicitudes posteriores que las usan producen un error ERROR_INVALID_HANDLE. No se puede confiar en solicitudes asincrónicas pendientes para completarse correctamente.

En el diagrama siguiente se muestran las funciones que usan el identificador HINTERNET creado por WinHttpOpenRequest. Los cuadros sombreados representan funciones WinHTTP que crean identificadores y los cuadros sin formato muestran las funciones que usan esos identificadores HINTERNET . El diagrama también se organiza para mostrar el orden en el que se suele llamar a las funciones WinHTTP.

Explicación de la jerarquía de identificadores

En primer lugar, se crea un identificador de sesión con WinHttpOpen. WinHttpConnect requiere el identificador de sesión como primer parámetro y devuelve un identificador de conexión para un servidor especificado. WinHttpOpenRequest crea un identificador de solicitud, que usa el identificador de conexión creado por WinHttpConnect. Si la aplicación decide agregar encabezados adicionales a la solicitud, o si es necesario para que la aplicación establezca credenciales para la autenticación, se puede llamar a WinHttpAddRequestHeaders y WinHttpSetCredentials mediante este identificador de solicitud. WinHttpSendRequest envía la solicitud, que usa el identificador de solicitud. Después de enviar la solicitud, se pueden enviar datos adicionales al servidor mediante WinHttpWriteData o la aplicación puede ir directamente a WinHttpReceiveResponse para especificar que no se envía más información al servidor. En este momento, según el propósito de la aplicación, el identificador de solicitud se puede usar para llamar a WinHttpQueryHeaders, WinHttpQueryAuthSchemes o recuperar un recurso con WinHttpQueryDataAvailable y WinHttpReadData.

Sockets web en la jerarquía de identificadores

Un identificador de socket web hereda de los identificadores de conexión y sesión, y ocupa una posición similar en la jerarquía de identificadores como lo hace un identificador de solicitud. Para crear un identificador de socket web, debe existir un identificador de solicitud; pero una vez creado el identificador de socket web, se puede cerrar la solicitud y el identificador de socket web seguirá funcionando.