Identificadores HINTERNET no WinHTTP

O WinHTTP (Microsoft Windows HTTP Services) usa identificadores para controlar as configurações e as informações necessárias ao usar o protocolo HTTP. Cada identificador mantém informações pertinentes a uma sessão HTTP, uma conexão com um servidor HTTP ou um recurso específico. Este tópico descreve os vários tipos de identificadores, as convenções de nomenclatura para esses identificadores e sua estrutura hierárquica.

• Sobre identificadores HINTERNET
• Identificadores de nomenclatura
• Manipular hierarquia
• Explicação da hierarquia de identificadores

Sobre identificadores HINTERNET

Os identificadores criados e usados pelo WinHTTP são chamados de identificadores HINTERNET . As funções WinHTTP retornam identificadores HINTERNET que não são intercambiáveis com outros identificadores, portanto, não podem ser usados com funções como ReadFile ou CloseHandle. Da mesma forma, outros identificadores não podem ser usados com funções WinHTTP. Por exemplo, um identificador retornado por CreateFile não pode ser passado para WinHttpReadData. Esses identificadores HINTERNET não podem ser fechados enquanto uma chamada à API que usa o identificador está em andamento. Para evitar uma condição de corrida, os aplicativos devem proteger o identificador e impedir que ele seja fechado enquanto a chamada à API estiver em andamento.

As funções wininet (Internet) do Microsoft Win32 também usam identificadores HINTERNET . No entanto, os identificadores usados em funções WinInet não podem ser trocados com os identificadores usados em funções WinHTTP. Para obter mais informações sobre o WinInet, consulte Sobre o WinINet.

A função WinHttpCloseHandle fecha identificadores WINHTTP HINTERNET .

Identificadores de nomenclatura

Em toda a documentação do WinHTTP, as descrições das funções na API (interface de programação do aplicativo) e no código de exemplo mostram a criação e o uso de vários tipos de identificadores HINTERNET . Para acompanhar os diferentes tipos de identificadores disponíveis, a nomenclatura desses identificadores é consistente. A tabela a seguir mostra os identificadores usados pela convenção na documentação.

Tipo de identificador	Identificador de criação de função	Identificador
Identificador genérico	WinHttpOpen, WinHttpConnect ou WinHttpOpenRequest	Hinternet
Identificador de sessão	WinHttpOpen	hSession
Identificador de conexão	WinHttpConnect	hConnect
Identificador de solicitação	WinHttpOpenRequest	hRequest
Identificador de soquete da Web	WinHttpWebSocketCompleteUpgrade	hWebSocket

Manipular hierarquia

Os identificadores HINTERNET são mantidos em uma hierarquia. O identificador retornado por WinHttpOpen é o identificador HINTERNET da sessão. Chamar WinHttpOpen inicializa as funções WinHTTP e inicia um contexto de sessão que mantém as informações e as configurações do usuário durante toda a vida útil do identificador de sessão. WinHttpConnect especifica um servidor HTTP ou HTTPS de destino e cria um identificador HINTERNET de conexão. Por padrão, o identificador de conexão herda as configurações do identificador de sessão. Cada recurso especificado com uma chamada para WinHttpOpenRequest recebe um identificador HINTERNET de solicitação.

O diagrama a seguir ilustra a hierarquia de identificadores HINTERNET . Cada caixa no diagrama representa uma função WinHTTP que retorna um identificador HINTERNET .

Depois de fechar um identificador, o aplicativo deve estar preparado para receber notificações de retorno de chamada no identificador até que o valor final do WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED seja retornado para indicar que o identificador está completamente fechado (ou até que o aplicativo faça sua própria sincronização equivalente, como rastrear e aguardar quaisquer retornos de chamada de operações assíncronas pendentes e garantir que nenhuma operação adicional seja tentada usando esse identificador).

Um identificador de sessão é chamado de pai de qualquer identificador de conexão usado para criar; da mesma forma, o identificador de conexão e seu identificador de sessão pai são chamados de pais de qualquer identificador de solicitação que o identificador de conexão é usado para criar.

Quando um identificador pai é fechado, todos os filhos que ele tem são invalidados indiretamente, mesmo que não sejam fechados, e as solicitações subsequentes que os usam falham com o erro ERROR_INVALID_HANDLE. Solicitações assíncronas pendentes não podem ser confiadas para serem concluídas corretamente.

O diagrama a seguir mostra as funções que usam o identificador HINTERNET criado por WinHttpOpenRequest. As caixas sombreadas representam funções WinHTTP que criam identificadores e as caixas simples mostram as funções que usam esses identificadores HINTERNET . O diagrama também é organizado para mostrar a ordem na qual as funções WinHTTP normalmente são chamadas.

Explicação da hierarquia de identificadores

Primeiro, um identificador de sessão é criado com WinHttpOpen. WinHttpConnect requer o identificador de sessão como seu primeiro parâmetro e retorna um identificador de conexão para um servidor especificado. Um identificador de solicitação é criado por WinHttpOpenRequest, que usa o identificador de conexão criado por WinHttpConnect. Se o aplicativo optar por adicionar cabeçalhos adicionais à solicitação ou se for necessário que o aplicativo defina credenciais para autenticação, WinHttpAddRequestHeaders e WinHttpSetCredentials poderão ser chamados usando esse identificador de solicitação. A solicitação é enviada por WinHttpSendRequest, que usa o identificador de solicitação. Depois de enviar a solicitação, dados adicionais podem ser enviados para o servidor usando WinHttpWriteData ou o aplicativo pode pular diretamente para WinHttpReceiveResponse para especificar que nenhuma outra informação é enviada ao servidor. Neste ponto, dependendo da finalidade do aplicativo, o identificador de solicitação pode ser usado para chamar WinHttpQueryHeaders, WinHttpQueryAuthSchemes ou recuperar um recurso com WinHttpQueryDataAvailable e WinHttpReadData.

Soquetes da Web na hierarquia de identificadores

Um identificador de soquete da Web herda dos identificadores de conexão e sessão e ocupa uma posição semelhante na hierarquia de identificador como um identificador de solicitação faz. Para criar um identificador de soquete da Web, um identificador de solicitação deve existir; mas depois que o identificador de soquete da Web for criado, a solicitação poderá ser fechada e o identificador de soquete da Web continuará funcionando.