HINTERNET manipula em 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 a HINTERNET lida com
• Alças de nomenclatura
• Manipular hierarquia
• Explicação da hierarquia de identificadores

Sobre os identificadores HINTERNET

Os identificadores que são criados e usados pelo WinHTTP são chamados identificadores de HINTERNET. As funções WinHTTP retornam identificadores de HINTERNET que não são intercambiáveis com outros identificadores, portanto, eles 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 de HINTERNET não podem ser fechados enquanto uma chamada de API usando o identificador estiver em andamento. Para evitar uma condição de corrida, os aplicativos devem proteger a alça e impedir que ela seja fechada enquanto a chamada de API estiver em andamento.

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

A funçãoWinHttpCloseHandle fecha WinHTTP identificadores de HINTERNET.

Alças de nomenclatura

Ao longo da documentação do WinHTTP, descrições de funções na interface de programação de aplicativos (API) e código de exemplo mostram a criação e o uso de vários tipos de identificadores de HINTERNET. Para acompanhar os diferentes tipos de alças disponíveis, a nomenclatura dessas alças é consistente. A tabela a seguir mostra os identificadores usados por convenção na documentação.

Tipo de alça	Alça de criação de função	Identificador
Pega genérica	WinHttpOpen, WinHttpConnectou WinHttpOpenRequest	hInternet
Alça de sessão	WinHttpOpen	hSessão
Alça de conexão	WinHttpConnect	hConnect [en]
Tratamento do pedido	WinHttpOpenRequest	hSolicitar
Identificador de soquete da Web	WinHttpWebSocketCompleteUpgrade	hWebSocket [en]

Hierarquia de manipulação

Os identificadores de 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 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 uma conexão identificador de HINTERNET. Por padrão, o identificador de conexão herda as configurações para o identificador de sessão. Cada recurso especificado com uma chamada para WinHttpOpenRequest recebe uma solicitação identificador de HINTERNET.

O diagrama a seguir ilustra a hierarquia de identificadores de HINTERNET. Cada caixa no diagrama representa uma função WinHTTP que retorna um identificador de 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 outra operação seja tentada usando esse identificador).

Um identificador de sessão é denominado o pai de qualquer identificador de conexão usado para criar; Da mesma forma, tanto o identificador de conexão quanto o identificador de sessão pai são denominados 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. As solicitações assíncronas pendentes não podem ser consideradas para serem concluídas corretamente.

O diagrama a seguir mostra as funções que usam o identificador de HINTERNET criado por WinHttpOpenRequest. As caixas sombreadas representam funções WinHTTP que criam identificadores e as caixas simples mostram as funções que usam essas identificadores de HINTERNET. O diagrama também é organizado para mostrar a ordem em que as funções WinHTTP são normalmente 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 pelo 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 para o aplicativo definir credenciais para autenticação, WinHttpAddRequestHeaders e WinHttpSetCredentials pode ser chamado 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 mais nenhuma informação é enviada para o 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 identificadores como um identificador de solicitação. Para criar um identificador de soquete da Web, um identificador de solicitação deve existir; Mas uma vez que o identificador de soquete da Web é criado, a solicitação pode ser fechada e o identificador de soquete da Web continuará a funcionar.