Função WinHttpWriteData (winhttp.h)
A função WinHttpWriteData grava dados de solicitação em um servidor HTTP.
Sintaxe
WINHTTPAPI BOOL WinHttpWriteData(
[in] HINTERNET hRequest,
[in] LPCVOID lpBuffer,
[in] DWORD dwNumberOfBytesToWrite,
[out] LPDWORD lpdwNumberOfBytesWritten
);
Parâmetros
[in] hRequest
Identificador HINTERNET válido retornado por WinHttpOpenRequest. Aguarde até que WinHttpSendRequest seja concluído antes de chamar essa função.
[in] lpBuffer
Ponteiro para um buffer que contém os dados a serem enviados para o servidor. Certifique-se de que esse buffer permaneça válido até que WinHttpWriteData seja concluído.
[in] dwNumberOfBytesToWrite
Valor inteiro longo sem sinal que contém o número de bytes a serem gravados no arquivo.
[out] lpdwNumberOfBytesWritten
Ponteiro para uma variável de inteiro longo sem sinal que recebe o número de bytes gravados no buffer. A função WinHttpWriteData define esse valor como zero antes de fazer qualquer verificação de erro ou trabalho. Ao usar WinHTTP de forma assíncrona, esse parâmetro deve ser definido como NULL e recuperar as informações na função de retorno de chamada. Não fazer isso pode causar uma falha de memória.
Valor retornado
Retorna TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão:
| Código do Erro | Descrição |
|---|---|
|
A conexão com o servidor foi redefinida ou encerrada ou um protocolo SSL incompatível foi encontrado. Por exemplo, o WinHTTP versão 5.1 não dá suporte ao SSL2, a menos que o cliente o habilite especificamente. |
|
A operação solicitada não pode ser executada porque o identificador fornecido não está no estado correto. |
|
O tipo de identificador fornecido está incorreto para esta operação. |
|
Ocorreu um erro interno. |
|
A operação foi cancelada, geralmente porque o identificador no qual a solicitação estava operando foi fechado antes da conclusão da operação. |
|
O tempo limite da solicitação foi atingido. |
|
Não havia memória suficiente disponível para concluir a operação solicitada. (Código de erro do Windows) |
Comentários
Mesmo quando WinHTTP é usado no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC foi definido no WinHttpOpen), essa função pode operar de forma síncrona ou assíncrona. Se essa função retornar FALSE, você poderá chamar GetLastError para obter informações de erro estendidas. Se essa função retornar TRUE, use o WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE conclusão para determinar se essa função foi bem-sucedida e o valor dos parâmetros. A conclusão do WINHTTP_CALLBACK_STATUS_REQUEST_ERROR indica que a operação foi concluída de forma assíncrona, mas falhou.
Se uma função de retorno de chamada status tiver sido instalada com WinHttpSetStatusCallback, as seguintes notificações que foram definidas no parâmetro dwNotificationFlags de WinHttpSetStatusCallback indicam progresso no envio de dados para o servidor:
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_DATA_WRITTEN
- WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
- WINHTTP_CALLBACK_STATUS_REQUEST_SENT
- WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE
Em segundo lugar, NTLM e Negotiate podem exigir vários handshakes para concluir a autenticação, o que exige que os dados sejam re-POST'ed para cada etapa de autenticação. Isso pode ser muito ineficiente para carregamentos de dados grandes.
Para contornar esses dois problemas, uma solução é enviar uma solicitação de aquecimento idempotente, como HEAD para o v-dir de autenticação primeiro, lidar com os desafios de autenticação associados a essa solicitação e, em seguida, apenas dados POST. Desde que o mesmo soquete seja reutilizado para lidar com o POST'ing, nenhum desafio de autenticação adicional deve ser encontrado e todos os dados podem ser carregados de uma só vez. Como um soquete autenticado só pode ser reutilizado para solicitações subsequentes na mesma sessão, o POST deve sair no mesmo soquete, desde que o soquete não seja agrupado com solicitações simultâneas competindo por ele.
Exemplos
Este exemplo mostra o código que grava dados em um servidor HTTP. O nome do servidor fornecido no exemplo, www.wingtiptoys.com, é fictício e deve ser substituído pelo nome de um servidor para o qual você tem acesso de gravação.
PCSTR pszData = "WinHttpWriteData Example";
DWORD dwBytesWritten = 0;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"A WinHTTP Example Program/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
// Specify an HTTP server.
if (hSession)
hConnect = WinHttpConnect( hSession, L"www.wingtiptoys.com",
INTERNET_DEFAULT_HTTP_PORT, 0);
// Create an HTTP Request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"PUT",
L"/writetst.txt",
NULL, WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
0);
// Send a Request.
if (hRequest)
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0, WINHTTP_NO_REQUEST_DATA, 0,
(DWORD)strlen(pszData), 0);
// Write data to the server.
if (bResults)
bResults = WinHttpWriteData( hRequest, pszData,
(DWORD)strlen(pszData),
&dwBytesWritten);
// End the request.
if (bResults)
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Report any errors.
if (!bResults)
printf("Error %d has occurred.\n",GetLastError());
// Close any open handles.
if (hRequest) WinHttpCloseHandle(hRequest);
if (hConnect) WinHttpCloseHandle(hConnect);
if (hSession) WinHttpCloseHandle(hSession);
Requisitos
| Cliente mínimo com suporte | Windows XP, Windows 2000 Professional com SP3 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003, Windows 2000 Server com SP3 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winhttp.h |
| Biblioteca | Winhttp.lib |
| DLL | Winhttp.dll |
| Redistribuível | WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000. |