Identificadores HINTERNET no WinHTTP

O Microsoft Windows HTTP Services (WinHTTP) 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 de hierarquia
• Explicação da hierarquia de identificador

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 usando o identificador estiver 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 do Microsoft Win32 Internet (WinInet) também usam identificadores HINTERNET. No entanto, os identificadores usados nas funções WinInet não podem ser trocados com os identificadores usados nas funções WinHTTP. Para obter mais informações sobre o WinInet, consulte Sobre o WinINet.

A funçãoWinHttpCloseHandle fecha identificadores HINTERNET do WinHTTP.

Identificadores de nomenclatura

Em toda a documentação do WinHTTP, descrições de funções na API (interface de programação do aplicativo) e código de exemplo mostram a criação e o uso de vários tipos de identificadores HINTERNET. Para controlar 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	Função criando identificador	Identificador
Identificador genérico	WinHttpOpen, WinHttpConnectou 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 é a sessão identificador de HINTERNET. 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 ao longo da vida útil do identificador de sessão. WinHttpConnect especifica um servidor HTTP ou HTTPS de destino e cria uma conexão identificador de HINTERNET. 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 uma solicitação identificador HINTERNET.

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 tiver são indiretamente invalidados, mesmo que não sejam fechados, e as solicitações subsequentes usando-as 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 são normalmente chamadas.

Explicação da hierarquia do identificador

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, WinHttpQueryAuthSchemesou recuperar um recurso com WinHttpQueryDataAvailable e WinHttpReadData.

Soquetes da Web na hierarquia de identificadores

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