WinHttpOpenRequest-Funktion (winhttp.h)

Artikel
08/27/2023

Die WinHttpOpenRequest-Funktion erstellt ein HTTP-Anforderungshandle.

Syntax

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Parameter

[in] hConnect

HINTERNET-Verbindungshandle zu einer von WinHttpConnect zurückgegebenen HTTP-Sitzung.

[in] pwszVerb

Zeiger auf eine Zeichenfolge, die das in der Anforderung zu verwendende HTTP-Verb enthält. Wenn dieser Parameter NULL ist, verwendet die Funktion GET als HTTP-Verb. Hinweis Diese Zeichenfolge sollte ganz groß geschrieben sein. Viele Server behandeln HTTP-Verben als sensitiv, und die Internet Engineering Task Force (IETF) Requests for Comments (RFCs) schreibt diese Verben nur mit Großbuchstaben.

[in] pwszObjectName

Zeiger auf eine Zeichenfolge, die den Namen der Zielressource des angegebenen HTTP-Verbs enthält. Dies ist in der Regel ein Dateiname, ein ausführbares Modul oder ein Suchbezeichner.

[in] pwszVersion

Zeiger auf eine Zeichenfolge, die die HTTP-Version enthält. Wenn dieser Parameter NULL ist, verwendet die Funktion HTTP/1.1.

[in] pwszReferrer

Zeiger auf eine Zeichenfolge, die die URL des Dokuments angibt, aus dem die URL in der Anforderung pwszObjectName abgerufen wurde. Wenn dieser Parameter auf WINHTTP_NO_REFERER festgelegt ist, wird kein verweisendes Dokument angegeben.

[in] ppwszAcceptTypes

Zeiger auf ein NULL-beendetes Array von Zeichenfolgenzeigern, das vom Client akzeptierte Medientypen angibt. Wenn dieser Parameter auf WINHTTP_DEFAULT_ACCEPT_TYPES festgelegt ist, werden keine Typen vom Client akzeptiert. In der Regel behandeln Server einen Mangel an akzeptierten Typen als Hinweis, dass der Client nur Dokumente vom Typ "text/*" akzeptiert. d. h. nur Textdokumente – keine Bilder oder andere Binärdateien. Eine Liste der gültigen Medientypen finden Sie unter Von der IANA definierte Medientypen unter http://www.iana.org/assignments/media-types/.

[in] dwFlags

Ganzzahlwert ohne Vorzeichen, der die Werte des Internetflags enthält. Dies kann einen der folgenden Werte annehmen:

Wert	Bedeutung
WINHTTP_FLAG_BYPASS_PROXY_CACHE	Dieses Flag bietet das gleiche Verhalten wie WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE	Unsichere Zeichen in der URL, die für pwszObjectName übergeben werden, werden nicht in Escapesequenzen konvertiert.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY	Unsichere Zeichen in der Abfragekomponente der URL, die für pwszObjectName übergeben wurde, werden nicht in Escapesequenzen konvertiert.
WINHTTP_FLAG_ESCAPE_PERCENT	Die für pwszObjectName übergebene Zeichenfolge wird von einer LPCWSTR in eine LPSTR konvertiert. Alle unsicheren Zeichen werden in eine Escapesequenz einschließlich des Prozentsymbols konvertiert. Standardmäßig werden alle unsicheren Zeichen mit Ausnahme des Prozentsymbols in eine Escapesequenz konvertiert.
WINHTTP_FLAG_NULL_CODEPAGE	Es wird davon ausgegangen, dass die für pwszObjectName übergebene Zeichenfolge aus gültigen ANSI-Zeichen besteht, die von WCHAR dargestellt werden. Es wird keine Überprüfung auf unsichere Zeichen durchgeführt. Windows 7: Diese Option ist veraltet.
WINHTTP_FLAG_REFRESH	Gibt an, dass die Anforderung an den Ursprungsserver weitergeleitet werden soll, anstatt eine zwischengespeicherte Version einer Ressource von einem Proxyserver zu senden. Wenn dieses Flag verwendet wird, wird dem Anforderungshandle ein Header "Pragma: no-cache" hinzugefügt. Beim Erstellen eines HTTP/1.1-Anforderungsheaders wird auch ein "Cache-Control: no-cache" hinzugefügt.
WINHTTP_FLAG_SECURE	Verwendung eine sichere Transaktionssemantik. Dies bedeutet die Verwendung von SSL (Secure Sockets Layer)/Transport Layer Security (TLS).

Rückgabewert

Gibt bei erfolgreicher Ausführung ein gültiges HTTP-Anforderungshandle oder andernfalls NULL zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Fehlercode	BESCHREIBUNG
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Der Typ des angegebenen Handles ist für diesen Vorgang falsch.
ERROR_WINHTTP_INTERNAL_ERROR	Ein interner Fehler ist aufgetreten.
ERROR_WINHTTP_INVALID_URL	Die URL ist ungültig.
ERROR_WINHTTP_OPERATION_CANCELLED	Der Vorgang wurde abgebrochen, in der Regel, weil der Handle, an dem die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Die URL hat ein anderes Schema als "http:" oder "https:" angegeben.
ERROR_NOT_ENOUGH_MEMORY	Für den angeforderten Vorgang war nicht genügend Arbeitsspeicher verfügbar. (Windows-Fehlercode)

Hinweise

Der Rückgabewert weist auf Erfolg oder Fehler hin. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Die WinHttpOpenRequest-Funktion erstellt ein neues HTTP-Anforderungshandle und speichert die angegebenen Parameter in diesem Handle. Ein HTTP-Anforderungshandle enthält eine Anforderung zum Senden an einen HTTP-Server und enthält alle RFC822/MIME/HTTP-Header, die als Teil der Anforderung gesendet werden sollen.

Wenn pwszVerb auf "HEAD" festgelegt ist, wird der Content-Length-Header ignoriert.

Wenn eine status Rückruffunktion mit WinHttpSetStatusCallback installiert wurde, gibt eine WINHTTP_CALLBACK_STATUS_HANDLE_CREATED Benachrichtigung an, dass WinHttpOpenRequest ein Anforderungshandle erstellt hat.

Nachdem die aufrufende Anwendung das von WinHttpOpenRequest zurückgegebene HINTERNET-Handle verwendet hat, muss es mit der WinHttpCloseHandle-Funktion geschlossen werden.

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie im Abschnitt Laufzeitanforderungen der WinHttp-Startseite .

Beispiele

In diesem Beispiel wird gezeigt, wie Sie ein HINTERNET-Handle abrufen, eine HTTP-Sitzung öffnen, einen Anforderungsheader erstellen und diesen Header an den Server senden.


    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, 
                                       0, 0);

    // PLACE ADDITIONAL CODE HERE.

    // 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);

Anforderungen

Anforderung	Wert
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.

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)

WinHTTP-Versionen

WinHttpConnect

WinHttpOpen