WinHttpAddRequestHeaders-Funktion (winhttp.h)
Die WinHttpAddRequestHeaders-Funktion fügt dem HTTP-Anforderungshandle einen oder mehrere HTTP-Anforderungsheader hinzu.
Syntax
WINHTTPAPI BOOL WinHttpAddRequestHeaders(
[in] HINTERNET hRequest,
[in] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in] DWORD dwModifiers
);
Parameter
[in] hRequest
Ein HINTERNET-Handle , das von einem Aufruf der WinHttpOpenRequest-Funktion zurückgegeben wird.
[in] lpszHeaders
Ein Zeiger auf eine Zeichenfolgenvariable, die die Header enthält, die an die Anforderung angefügt werden sollen. Jeder Header mit Ausnahme des letzten muss durch einen Wagenrücklauf/Zeilenvorschub (CR/LF) beendet werden.
[in] dwHeadersLength
Ein ganzzahliger Wert ohne Vorzeichen, der die Länge von pwszHeaders in Zeichen enthält. Wenn dieser Parameter -1L ist, geht die Funktion davon aus, dass pwszHeaders null-terminated (ASCIIZ) ist, und die Länge wird berechnet.
[in] dwModifiers
Ein ganzzahliger Wert ohne Vorzeichen, der die Flags enthält, die zum Ändern der Semantik dieser Funktion verwendet werden. Dies kann ein oder mehrere der folgenden Flags sein.
Rückgabewert
Gibt TRUE zurück, wenn erfolgreich, andernfalls FALSE . Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Zu den zurückgegebenen Fehlercodes gehören die folgenden.
| Fehlercode | BESCHREIBUNG |
|---|---|
|
Der angeforderte Vorgang kann nicht ausgeführt werden, weil sich das angegebene Handle nicht im richtigen Zustand befindet. |
|
Der Typ des angegebenen Handles ist für diesen Vorgang falsch. |
|
Ein interner Fehler ist aufgetreten. |
|
Es war nicht genügend Arbeitsspeicher verfügbar, um den angeforderten Vorgang abzuschließen. |
Hinweise
Header werden über Umleitungen übertragen. Dies kann ein Sicherheitsproblem sein. Um zu vermeiden, dass Header übertragen werden, wenn eine Umleitung erfolgt, verwenden Sie den WINHTTP_STATUS_CALLBACK Rückruf, um die spezifischen Header zu korrigieren, wenn eine Umleitung auftritt.
Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), wird diese Funktion synchron ausgeführt. Der Rückgabewert gibt Erfolg oder Fehler an. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Die WinHttpAddRequestHeaders-Funktion fügt zusätzliche Header im freien Format an das HTTP-Anforderungshandle an und ist für die Verwendung durch anspruchsvolle Clients vorgesehen, die eine detaillierte Kontrolle über die genaue Anforderung benötigen, die an den HTTP-Server gesendet wird.
Der Name und wert der Anforderungsheader, die mit dieser Funktion hinzugefügt wurden, werden überprüft. Header müssen wohlgeformt sein. Weitere Informationen zu gültigen HTTP-Headern finden Sie unter RFC 2616. Wenn ein ungültiger Header verwendet wird, schlägt diese Funktion fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück. Der ungültige Header wird nicht hinzugefügt.
Wenn Sie einen Date:-Anforderungsheader senden, können Sie die WinHttpTimeFromSystemTime-Funktion verwenden, um eine Struktur für den Header zu erstellen.
Bei einfachen WinHttpAddRequestHeaders kann die Anwendung mehrere Header in einem einzelnen Puffer übergeben.
Eine Anwendung kann winHttpSendRequest auch verwenden, um dem HTTP-Anforderungshandle zusätzliche Header hinzuzufügen, bevor eine Anforderung gesendet wird.
Beispiele
Das folgende Codebeispiel enthält einen If Modified-Since-Header in einer Anforderung. Der Antwortheader wird interpretiert, um zu bestimmen, ob das Zieldokument aktualisiert wurde.
DWORD dwSize = sizeof(DWORD);
DWORD dwStatusCode = 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.microsoft.com",
INTERNET_DEFAULT_HTTP_PORT,
0 );
// Create an HTTP Request handle.
if( hConnect )
hRequest = WinHttpOpenRequest( hConnect,
L"GET",
NULL,
NULL,
WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
0 );
// Add a request header.
if( hRequest )
bResults = WinHttpAddRequestHeaders( hRequest,
L"If-Modified-Since: Mon, 20 Nov 2000 20:00:00 GMT",
(ULONG)-1L,
WINHTTP_ADDREQ_FLAG_ADD );
// Send a Request.
if( bResults )
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0,
WINHTTP_NO_REQUEST_DATA,
0,
0,
0 );
// End the request.
if( bResults )
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Use WinHttpQueryHeaders to obtain the header buffer.
if( bResults )
bResults = WinHttpQueryHeaders( hRequest,
WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
NULL,
&dwStatusCode,
&dwSize,
WINHTTP_NO_HEADER_INDEX );
// Based on the status code, determine whether
// the document was recently updated.
if( bResults )
{
if( dwStatusCode == 304 )
printf( "Document has not been updated.\n" );
else if( dwStatusCode == 200 )
printf( "Document has been updated.\n" );
else
printf( "Status code = %u.\n",dwStatusCode );
}
// Report any errors.
if( !bResults )
printf( "Error %d has occurred.\n", GetLastError( ) );
// Close open handles.
if( hRequest ) WinHttpCloseHandle( hRequest );
if( hConnect ) WinHttpCloseHandle( hConnect );
if( hSession ) WinHttpCloseHandle( hSession );
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winhttp.h |
| Bibliothek | Winhttp.lib |
| DLL | Winhttp.dll |
| Verteilbare Komponente | WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000. |