WinHttpOpenRequest-Funktion (winhttp.h)

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 HTTP-Verb enthält, das in der Anforderung verwendet werden soll. Wenn dieser Parameter NULL ist, verwendet die Funktion GET als HTTP-Verb. Hinweis Diese Zeichenfolge sollte alle Großbuchstaben sein. Viele Server behandeln HTTP-Verben als Groß-/Kleinschreibung, und die Internet Engineering Task Force (IETF)-Anforderungen für Kommentare (RFCs) verwenden 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 im Allgemeinen 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 referenzierendes Dokument angegeben.

[in] ppwszAcceptTypes

Zeiger auf ein null-beendetes Array von Zeichenfolgenzeigern, die Medientypen angibt, die vom Client akzeptiert werden. Wenn dieser Parameter auf WINHTTP_DEFAULT_ACCEPT_TYPES festgelegt ist, werden vom Client keine Typen akzeptiert. In der Regel behandeln Server einen Mangel an akzeptierten Typen als Hinweis darauf, dass der Client nur Dokumente vom Typ "Text/*" akzeptiert; das heißt, nur Textdokumente – keine Bilder oder andere Binärdateien. Eine Liste gültiger Medientypen finden Sie unter "Medientypen", die von IANA definiert http://www.iana.org/assignments/media-types/sind.

[in] dwFlags

Unsigned long integer value that contains the Internet flag values. Dies kann einen der folgenden Werte annehmen:

Wert Bedeutung
WINHTTP_FLAG_BYPASS_PROXY_CACHE
Dieses Kennzeichen bietet das gleiche Verhalten wie WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE
Unsichere Zeichen in der URL, die für pwszObjectName übergeben wird, werden nicht in Escapesequenzen konvertiert.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY
Unsichere Zeichen in der Abfragekomponente der url, die für pwszObjectName übergeben wird, werden nicht in Escapesequenzen konvertiert.
WINHTTP_FLAG_ESCAPE_PERCENT
Die für pwszObjectName übergebene Zeichenfolge wird von einem LPCWSTR in ein LPSTR konvertiert. Alle unsicheren Zeichen werden in eine Escapesequenz konvertiert, einschließlich des Prozentsymbols. Standardmäßig werden alle unsicheren Zeichen außer dem Prozentsymbol in eine Escapesequenz konvertiert.
WINHTTP_FLAG_NULL_CODEPAGE
Die für pwszObjectName übergebene Zeichenfolge wird angenommen, dass sie aus gültigen ANSI-Zeichen besteht, die durch WCHAR dargestellt werden. Es werden keine Überprüfungen für unsichere Zeichen durchgeführt.

Windows 7: Diese Option ist veraltet.

WINHTTP_FLAG_REFRESH
Gibt an, dass die Anforderung an den ursprünglichen Server 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 übersetzt die Verwendung von Secure Sockets Layer (SSL)/Transport Layer Security (TLS).

Rückgabewert

Gibt einen gültigen HTTP-Anforderungshandpunkt zurück, falls erfolgreich oder NULL . Rufen Sie getLastError für erweiterte Fehlerinformationen auf. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Fehlercode BESCHREIBUNG
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
Der typ des bereitgestellten 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, normalerweise weil der Handle, auf dem die Anforderung ausgeführt wurde, geschlossen wurde, bevor der Vorgang abgeschlossen wurde.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
Die URL hat ein anderes Schema als "http:" oder "https:" angegeben.
ERROR_NOT_ENOUGH_MEMORY
Nicht genügend Arbeitsspeicher war verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode)

Hinweise

Der Rückgabewert gibt Erfolg oder Fehler an. 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 Header "Inhaltslänge" ignoriert.

Wenn eine Statusrückruffunktion mit WinHttpSetStatusCallback installiert wurde, gibt eine WINHTTP_CALLBACK_STATUS_HANDLE_CREATED Benachrichtigung an, dass WinHttpOpenRequest einen Anforderungshandpunkt erstellt hat.

Nachdem die aufrufende Anwendung die Verwendung des von WinHttpOpenRequest zurückgegebenen HINTERNET-Handles abgeschlossen hat, muss sie mithilfe 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 einen 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

   
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 Services (WinHTTP)

WinHTTP-Versionen

WinHttpConnect

WinHttpOpen