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
- de jerarquía de identificadores
- explicación del de jerarquía de identificadores
Acerca de los identificadores HINTERNET
Los identificadores creados y usados por WinHTTP se denominan identificadores de HINTERNET. Las funciones WinHTTP devuelven identificadores de 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, no se puede pasar un identificador devuelto por CreateFile 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 de 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 de HINTERNET de Win HTTP.
Identificadores de nomenclatura
A lo largo de 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 HINTERNET identificadores. 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, WinHttpConnecto 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 |
Control de la jerarquía
Los identificadores HINTERNET se mantienen en una jerarquía. El identificador devuelto por winHttpOpen es la sesión identificador de HINTERNET. Al llamar a WinHttpOpen inicializa las funciones winHTTP y comienza 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 una conexión identificador de HINTERNET. 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 una solicitud identificador de HINTERNET.
En el diagrama siguiente se muestra la jerarquía de identificadores de 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 final del WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED 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 primario de cualquier identificador de conexión que 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 de 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. WinHttpOpenRequestcrea 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 que la aplicación establezca credenciales para la autenticación, WinHttpAddRequestHeaders y winHttpSetCredentials se puede llamar mediante este identificador de solicitud. La solicitud se envía mediante WinHttpSendRequest, que usa el identificador de solicitud. Después de enviar la solicitud, se pueden enviar datos adicionales al servidor mediante WinHttpWriteDatao la aplicación puede omitir 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, la solicitud puede cerrarse y el identificador de socket web seguirá funcionando.