Optionskennzeichnungen

Die folgenden Optionskennzeichnungen werden von WinHttpQueryOption und WinHttpSetOption unterstützt.

WINHTTP_OPTION_ASSURED_NON_BLOCKING_CALLBACKS

Der Standardwert ist FALSE. Wenn dieser Wert auf TRUE festgelegt ist, garantiert WinHTTP keinen Fortschritt, wenn Statusrückrufe von der Clientanwendung blockiert werden.

Die Clientanwendung muss besonders darauf achten, minimale Vorgänge innerhalb des Rückrufs auszuführen, ohne zu blockieren, so schnell wie möglich zurückzugeben und insbesondere nicht auf nachfolgende WinHTTP-Aufrufe warten zu müssen. Wenn diese Richtlinien nicht eingehalten werden, kann es zu einer negativen Leistungsbeeinträchtigung kommen oder eine potenzielle Anwendung hängen. Wenn diese Option auf vorgeschriebene Weise verwendet wird, kann diese Option die Leistung verbessern.

WINHTTP_OPTION_AUTOLOGON_POLICY

Legt einen wert vom Typ "Unsigned long integer" fest, der die Richtlinie für die automatische Anmeldung mit einem der folgenden Werte angibt.

WINHTTP_OPTION_BACKGROUND_CONNECTIONS

Wenn Sie diese Option für ein Sitzungshandle festlegen, müssen Sie die Anzahl der Verbindungen übergeben, die Sie öffnen möchten. Anschließend öffnet WinHttp beim ersten Senden einer Anforderung eine Reihe von Verbindungen parallel, anstatt nur eine einzige Verbindung zu öffnen. Dies kann die Leistung der nachfolgenden Anforderungen an dasselbe Ziel verbessern, was nicht den Aufwand für die Verbindungseinrichtung hat.

WINHTTP_OPTION_CALLBACK

Ruft den Zeiger auf den Rückruffunktionssatz mit WinHttpSetStatusCallback ab.

WINHTTP_OPTION_CLIENT_CERT_CONTEXT

Legt den Clientzertifikatkontext fest. Wenn eine Anwendung ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED empfängt, muss winHttpSetOption aufgerufen werden, um ein Zertifikat anzugeben, bevor Sie die Anforderung erneut versuchen. Als Teil der Verarbeitung dieser Option ruft WinHttp CertDuplicateCertificateContext im vom Aufrufer bereitgestellten Zertifikatkontext auf, damit der Zertifikatkontext vom Aufrufer unabhängig freigegeben werden kann.

Wenn der Server ein Clientzertifikat anfordert, gibt WinHttpSendRequest oder WinHttpReceiveResponse einen ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED Fehler zurück. Wenn der Server das Zertifikat anfordert, aber nicht benötigt, kann die Anwendung diese Option angeben, um anzugeben, dass es kein Zertifikat hat. Der Server kann ein anderes Authentifizierungsschema auswählen oder anonymen Zugriff auf den Server zulassen. Die Anwendung stellt das WINHTTP_NO_CLIENT_CERT_CONTEXT Makro im lpBuffer-Parameter von WinHttpSetOption bereit, wie im folgenden Codebeispiel gezeigt.

BOOL fRet = WinHttpSetOption(hRequest,
                             WINHTTP_OPTION_CLIENT_CERT_CONTEXT,
                             WINHTTP_NO_CLIENT_CERT_CONTEXT,
                             0);

Wenn der Server ein Clientzertifikat benötigt, sendet er möglicherweise einen 403 HTTP-Statuscode als Antwort. Weitere Informationen finden Sie in der Option WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST .

WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST

Ruft eine SecPkgContext_IssuerListInfoEx Struktur ab, wenn der Fehler von WinHttpSendRequest oder WinHttpReceiveResponseERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED ist. Die Ausstellerliste in der Struktur enthält eine Liste der zulässigen Zertifizierungsstellen (Ca) vom Server. Die Clientanwendung kann die Zertifizierungsstelle-Liste filtern, um das Clientzertifikat für die SSL-Authentifizierung abzurufen.

Wenn der Server das Clientzertifikat anfordert, aber nicht benötigt, kann die Anwendung WinHttpSetOption mit der option WINHTTP_OPTION_CLIENT_CERT_CONTEXT aufrufen. Weitere Informationen finden Sie in der option WINHTTP_OPTION_CLIENT_CERT_CONTEXT .

WINHTTP_OPTION_CODEPAGE

Legt die Codeseite fest, die zum Verarbeiten der URL verwendet wird (d. a. Abfragezeichenfolge). Der Standardwert ist UTF8.

WINHTTP_OPTION_CONFIGURE_PASSPORT_AUTH

Legt einen wert vom Typ "Unsigned long integer" fest, der angibt, ob die Passport-Authentifizierung in der WinHTTP-Authentifizierung aktiviert ist. Der Wert kann eine der folgenden Sein:

WINHTTP_OPTION_CONNECT_RETRIES

Dient zum Festlegen oder Abrufen eines Werts ohne vorzeichenlose ganze Zahl, der die Anzahl der Male enthält, mit denenWinHTTP versucht, eine Verbindung mit einem Host herzustellen. Microsoft Windows HTTP Services (WinHTTP) versucht nur einmal pro IP-Adresse (Internet Protocol). Wenn Sie beispielsweise versuchen, eine Verbindung mit einem multihomed-Host herzustellen, der über 10 IP-Adressen verfügt und WINHTTP_OPTION_CONNECT_RETRIES auf 7 festgelegt ist, versucht WinHTTP nur, eine Verbindung mit der ersten sieben IP-Adresse herzustellen. Wenn WINHTTP_OPTION_CONNECT_RETRIES auf 20 festgelegt ist, versucht WinHTTP bei gleicher Anzahl von 10 IP-Adressen nur einmal. Wenn nach der angegebenen Anzahl von Versuchen immer noch ein Verbindungsversuch fehlschlägt oder das Verbindungstimeout vorher abgelaufen ist, wird die Anforderung abgebrochen. Der Standardwert für WINHTTP_OPTION_CONNECT_RETRIES ist fünf Versuche.

WINHTTP_OPTION_CONNECT_TIMEOUT

Legt einen wert vom Typ "Unsigned long integer" fest, der den Timeoutwert in Millisekunden enthält, oder ruft diesen ab. Wenn Sie diese Option auf unendlich (0xFFFFFFFF) festlegen, wird dieser Timer deaktiviert.

Wenn eine TCP-Verbindungsanforderung länger als dieser Timeoutwert dauert, wird die Anforderung abgebrochen. Das Standardtimeout beträgt 60 Sekunden. Wenn Sie versuchen, eine Verbindung mit mehreren IP-Adressen für einen einzelnen Host (ein mehrhomed-Host) herzustellen, gilt das Timeoutlimit für jede einzelne Verbindung.

WINHTTP_OPTION_CONNECTION_INFO

Ruft die Quell- und Ziel-IP-Adresse und den Port der Anforderung ab, die die Antwort generiert hat, wenn WinHttpReceiveResponse zurückgibt. Die Anwendung ruft WinHttpQueryOption mit der option WINHTTP_OPTION_CONNECTION_INFO auf und stellt die WINHTTP_CONNECTION_INFO Struktur im lpBuffer-Parameter bereit. Weitere Informationen finden Sie unter WINHTTP_CONNECTION_INFO.

Gilt für: Windows XP mit SP2 und höher; Windows 2003 mit SP1 und höher.

WINHTTP_OPTION_CONNECTION_GUID

Markieren Sie die verbindung, die dem WinHTTP-Anforderungshandle mit einer GUID zugeordnet ist. Dies ermöglicht eine benutzerdefinierte Kontrolle darüber, welche Gruppen von Verbindungen mit der option WINHTTP_OPTION_MATCH_CONNECTION_GUID verwendet werden.

WINHTTP_OPTION_CONNECTION_STATS_V0

Retreives the TCP_INFO_v0 struct for the underlying connection used by the request. Die zurückgegebene Struktur kann Statistiken von vorherigen Anforderungen enthalten, die über dieselbe Verbindung gesendet wurden.

WINHTTP_OPTION_CONNECTION_STATS_V1

Retreives the TCP_INFO_v1 struct for the underlying connection used by the request. Die zurückgegebene Struktur kann Statistiken von vorherigen Anforderungen enthalten, die über dieselbe Verbindung gesendet wurden.

WINHTTP_OPTION_CONTEXT_VALUE

Dient zum Festlegen oder Abrufen eines DWORD_PTR , das einen Zeiger auf den Kontextwert enthält, der diesem HINTERNET-Handle zugeordnet ist. Der im Puffer gespeicherte Wert wird verwendet, und dem options flag WINHTTP_OPTION_CONTEXT_VALUE wird ein neuer Wert zugewiesen.

WINHTTP_OPTION_DECOMPRESSION

Legt ein DWORD von Flags fest, die bestimmen, ob WinHTTP Antworttexte automatisch mit komprimierten Inhaltscodierungen dekomprimiert. WinHTTP legt auch einen geeigneten Accept-Encoding Header fest, der alle vom Aufrufer bereitgestellten Überschreibungen überschreibt. Unterstützte Werte sind:

Standardmäßig liefert WinHTTP komprimierte Antworten an den Aufrufer, der nicht geändert wurde.

WINHTTP_OPTION_DISABLE_CERT_CHAIN_BUILDING

Wenn Sie diese Option für ein WinHttp-Sitzungshandle festlegen, können Sie aktivieren/deaktivieren, ob die Serverzertifikatkette erstellt wurde.

WINHTTP_OPTION_DISABLE_FEATURE

Legt einen wert vom Typ "Unsigned long integer" fest, der angibt, welche Features mit mindestens einem der folgenden Flags deaktiviert sind. Beachten Sie, dass dieses Feature nur auf Anforderungshandles an WinHttpSetOption übergeben werden sollte, nachdem das Anforderungshandle mit WinHttpOpenRequest erstellt wurde, und bevor die Anforderung mit WinHttpSendRequest gesendet wird.

WINHTTP_OPTION_DISABLE_GLOBAL_POOLING

Deaktiviert das globale, sitzungsübergreifende Pooling. Dies wird empfohlen, da das globale, sitzungsübergreifende Pooling aus Kompatibilitätsgründen standardmäßig vom Legacyverhalten unterstützt wird. Dies wirkt sich auf die spätere Einstellung der maximalen Verbindungen manuell aus.

WINHTTP_OPTION_DISABLE_PROXY_AUTH_SCHEMES

Deaktiviert eine oder mehrere der folgenden Proxyauthentifizierungsmethoden in der WinHTTP-Sitzung, indem alle OR anwendbaren Optionen bereitgestellt werden. Dies sind alle Schemas, mit Ausnahme von WINHTTP_PROXY_DISABLE_AUTH_LOCAL_SERVICE, was die Verwendung des lokalen Computerkontos beim Senden von Anforderungen an eine Loopback- oder lokale Adresse erzwingt. Dadurch wird verhindert, dass Systemanmeldeinformationen an lokale HTTP-Proxys verloren gehen.

WINHTTP_OPTION_DISABLE_SECURE_PROTOCOL_FALLBACK

Verhindert, dass WinHTTP eine Verbindung mit einer niedrigeren Version des Sicherheitsprotokolls erneut versucht, wenn die anfängliche Protokollverhandlung fehlschlägt.

WINHTTP_OPTION_DISABLE_STREAM_QUEUE

Ermöglicht es neuen Anforderungen, eine zusätzliche HTTP/2-Verbindung zu öffnen, wenn der maximale gleichzeitige Datenstromgrenzwert erreicht ist, anstatt auf den nächsten verfügbaren Datenstrom für eine vorhandene Verbindung zu warten.

WINHTTP_OPTION_ENABLE_FEATURE

Legt einen wert vom Typ "Unsigned long integer" fest, der die derzeit aktivierten Features angibt. Dies kann einer der folgenden Werte sein:

WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL

Legt eine DWORD-Bitmaske für akzeptable erweiterte HTTP-Versionen fest. Mögliche Werte:

Ältere Versionen von HTTP (1.1 und früher) können mit dieser Option nicht deaktiviert werden. Der Standardwert ist 0x0.

WINHTTP_OPTION_ENABLE_HTTP2_PLUS_CLIENT_CERT

Diese Option kann für ein WinHttp-Sitzungshandle festgelegt werden, damit WinHttp den vom Aufrufer bereitgestellten Clientzertifikatkontext verwenden kann, wenn HTTP/2 verwendet wird.

WINHTTP_OPTION_ENABLETRACING

Legt einen BOOL-Wert fest, der angibt, ob die Ablaufverfolgung zurzeit aktiviert ist. Diese Option kann nur für ein NULLHINTERNET-Handle festgelegt werden. Siehe auch "Sammeln von WinHTTP-Ablaufverfolgungen".

WINHTTP_OPTION_ENCODE_EXTRA

Aktiviert die URL-Prozentcodierung für Pfad- und Abfragezeichenfolgen.

Alternativ können Sie vor dem Aufrufen von WinHttp die Prozentcodierung ausführen.

WINHTTP_OPTION_EXPIRE_CONNECTION

Diese Option kann nur für ein Anforderungshandle festgelegt werden, das noch aktiv ist (Senden oder Empfangen). Wenn Sie diese Option festlegen, wird WinHttp aufgefordert, die Bereitstellung von Anforderungen für die Verbindung zu beenden, die mit dem übergebenen Anforderungshandle verknüpft ist. Die Verbindung wird geschlossen, nachdem die Anforderungshandle diese Option aufgerufen wird, mit der sie aufgerufen wird. Diese Option verwendet keine Parameter.

WINHTTP_OPTION_EXTENDED_ERROR

Ruft einen nicht signierten ganzzahligen Wert ab, der einen Microsoft Windows Sockets-Fehlercode enthält, der der ERROR_WINHTTP_*-Fehlermeldungen zugeordnet wurde, die zuletzt in diesem Threadkontext zurückgegeben wurden. Sie können NULL als Handlewert übergeben.

WINHTTP_OPTION_FEATURE_SUPPORTED

Überprüfen Sie, ob eine bereitgestellte Optionskennzeichnung von dieser WinHTTP-Version unterstützt wird.

WINHTTP_OPTION_FIRST_AVAILABLE_CONNECTION

Wenn WinHttp standardmäßig eine Anforderung sendet, wenn es keine verfügbaren Verbindungen für die Anforderung gibt, versucht WinHttp, eine neue Verbindung herzustellen, und die Anforderung wird an diese neue Verbindung gebunden. Wenn Sie diese Option festlegen, wird stattdessen eine solche Anforderung für die erste Verbindung bereitgestellt, die verfügbar wird, und nicht unbedingt die, die eingerichtet wird.

WINHTTP_OPTION_GLOBAL_PROXY_CREDS

Verwendet einen Zeiger auf eine WINHTTP_CREDS_EX Struktur, wobei der hInternet-Funktionsparameter auf NULL festgelegt ist. Für diese Option ist der Registrierungsschlüssel HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings erforderlich! ShareCredsWithWinHttp. Wenn dieser Registrierungsschlüssel nicht festgelegt ist, gibt WinHTTP fehler ERROR_WINHTTP_INVALID_OPTION zurück. Dieser Registrierungsschlüssel ist standardmäßig nicht vorhanden. Wenn sie festgelegt ist, sendet WinINet Anmeldeinformationen an WinHTTP. Wenn WinHttp eine Authentifizierungsabfrage erhält und keine Anmeldeinformationen für das aktuelle Handle festgelegt sind, werden die von WinINet bereitgestellten Anmeldeinformationen verwendet. Um zusätzlich zu Proxyanmeldeinformationen Serveranmeldeinformationen freizugeben, müssen Benutzer WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS festlegen.

WINHTTP_OPTION_GLOBAL_SERVER_CREDS

Verwendet einen Zeiger auf eine WINHTTP_CREDS_EX Struktur, wobei der hInternet-Funktionsparameter auf NULL festgelegt ist. Für diese Option ist der Registrierungsschlüssel HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings erforderlich! ShareCredsWithWinHttp. Wenn dieser Registrierungsschlüssel nicht festgelegt ist, gibt WinHTTP fehler ERROR_WINHTTP_INVALID_OPTION zurück. Dieser Registrierungsschlüssel ist standardmäßig nicht vorhanden. Wenn sie festgelegt ist, sendet WinINet Anmeldeinformationen an WinHTTP. Wenn WinHttp eine Authentifizierungsabfrage erhält und keine Anmeldeinformationen für das aktuelle Handle festgelegt sind, werden die von WinINet bereitgestellten Anmeldeinformationen verwendet. Um zusätzlich zu Proxyanmeldeinformationen Serveranmeldeinformationen freizugeben, müssen Benutzer WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS festlegen.

WINHTTP_OPTION_HANDLE_TYPE

Ruft einen unsignierten langen ganzzahligen Wert ab, der den Typ des übergebenen HINTERNET-Handles enthält. Der Rückgabewert kann eine der folgenden Sein:

WINHTTP_OPTION_HTTP_PROTOCOL_REQUIRED

Verhindert, dass andere Protokollversionen als die von WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL für die Anforderung verwendet werden.

WINHTTP_OPTION_HTTP_PROTOCOL_USED

Ruft ein DWORD zurück, das angibt, welche erweiterte HTTP-Version für eine bestimmte Anforderung verwendet wurde. Eine Liste der möglichen Werte finden Sie unter WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL.

WINHTTP_OPTION_HTTP_VERSION

Legt eine HTTP_VERSION_INFO Struktur fest, die die unterstützte ältere HTTP-Version deklariert, oder ruft diese ab. Dies ist eine prozessweite Option; verwenden Sie NULL für den Handle.

WINHTTP_OPTION_HTTP2_KEEPALIVE

Diese Option kann für ein Sitzungshandle festgelegt werden, damit WinHttp HTTP/2-PING-Frames als Keepalive-Mechanismus verwendet. Aufrufer geben ein Timeout in Millisekunden an, und nachdem keine Aktivität für eine Verbindung für diesen Timeoutzeitraum vorhanden ist, beginnt WinHttp mit dem Senden von HTTP/2-PING-Frames. Aufrufer können keinen Timeoutwert unter 5000 Millisekunden festlegen.

WINHTTP_OPTION_HTTP2_PLUS_TRANSFER_ENCODING

Diese Option kann für ein WinHttp-Anforderungshandle festgelegt werden, um zu steuern, wie WinHttp sich verhält, wenn eine HTTP/2-Antwort einen Header "Transfer-Encoding" enthält. In diesem Fall gibt WinHttp einen Fehler zurück, wenn diese Option auf FALSE festgelegt ist.

WINHTTP_OPTION_HTTP2_RECEIVE_WINDOW

Legen Sie die anfängliche GRÖßE des HTTP/2-Datenstroms und den Schwellenwert für das Senden von Fensteraktualisierungen mithilfe der WINHTTP_HTTP2_RECEIVE_WINDOW Struktur fest.

WINHTTP_OPTION_HTTP3_HANDSHAKE_TIMEOUT

Verwendet den Puffer, um das HTTP/3-Handshake-Timeout in Millisekunden als PDWORD festzulegen.

WINHTTP_OPTION_HTTP3_INITIAL_RTT

Konfiguriert das anfängliche RTT in Millisekunden, die von msquic verwendet werden.

WINHTTP_OPTION_HTTP3_KEEPALIVE

Aktiviert die Keep-Alive-Semantik für die Verbindung. Verwendet den Puffer, um das Keep-Alive-Timeout in Millisekunden als PDWORD festzulegen.

WINHTTP_OPTION_HTTP3_STREAM_ERROR_CODE

Ruft den vom Server bereitgestellten Fehler im HTTP/3-Stream ab, der zum Senden der Anforderung verwendet wird.

WINHTTP_OPTION_IGNORE_CERT_REVOCATION_OFFLINE

Ermöglicht sicheren Verbindungen die Verwendung von Sicherheitszertifikaten, für die die Zertifikatsperrliste nicht heruntergeladen werden konnte.

WINHTTP_OPTION_IPV6_FAST_FALLBACK

Aktiviert den schnellen Fallback von IPv6 (Happier Eyeballs) für die Verbindung. Dieses Verhalten ähnelt dem in RFC 6555 beschriebenen Happy Eyeballs-Verhalten zur Verbesserung der Verbindungszeiten in Netzwerken, in denen IPv6 unzuverlässig ist.

• Wenn sowohl IPv6- als auch IPv4-Adressen für einen bestimmten Host aufgelöst werden, beginnt WinHttp mit dem Herstellen einer Verbindung mit der ersten aufgelösten IPv6-Adresse mit einem kurzen Timeout (300 ms).
• Sollte diese Verbindung fehlschlagen, versucht WinHttp, eine Verbindung mit der ersten aufgelösten IPv4-Adresse mit dem Standardtimeout herzustellen.
• Sollte die zweite Verbindung fehlschlagen, wiederholt WinHttp die erste aufgelöste IPv6-Adresse mit dem Standardtimeout.
• Wenn die dritte Verbindung fehlschlägt, wird WinHttp auf das Standardverhalten für alle verbleibenden Adressen zurückgesetzt, wobei versucht wird, eine Verbindung mit jedem mit dem Standardtimeout herzustellen, bis eine Verbindung hergestellt wird oder keine Adressen verbleiben.

WINHTTP_OPTION_IS_PROXY_CONNECT_RESPONSE

Ruft ab, ob eine Proxy Return Connect-Antwort abgerufen werden kann.

WINHTTP_OPTION_MATCH_CONNECTION_GUID

Übernimmt eine WINHTTP_MATCH_CONNECTION_GUID-Anweisung , WinHTTP anzuweisen, die Anforderung für eine übereinstimmende Verbindung zu bedienen. Wenn WINHTTP_MATCH_CONNECTION_GUID_FLAG_REQUIRED festgelegt ist, können nur Verbindungen mit einer übereinstimmenden GUID verwendet werden. Andernfalls können Verbindungen mit übereinstimmenden GUIDs und Verbindungen, die nicht mit einer GUID gekennzeichnet sind, verwendet werden.

WINHTTP_OPTION_MAX_CONNS_PER_1_0_SERVER

Legt fest oder ruft einen nicht signierten langen ganzzahligen Wert, der die maximale Anzahl der zulässigen Verbindungen pro HTTP/1.0-Server enthält. Der Standardwert ist INFINITE.

Gilt für: Windows Vista mit SP1 und höher; Windows Server 2008 und höher.

WINHTTP_OPTION_MAX_CONNS_PER_SERVER

Legt fest oder ruft einen nicht signierten langen ganzzahligen Wert ab, der die maximale Anzahl der pro Server zulässigen Verbindungen enthält. Der Standardwert ist INFINITE.

Wenn diese Option auf Null festgelegt ist, legt WinHTTP den Grenzwert für die Anzahl der Verbindungen auf 2 fest.

WINHTTP_OPTION_MAX_HTTP_AUTOMATIC_REDIRECTS

Legt die maximale Anzahl von Umleitungen fest, die WinHTTP folgt; Der Standardwert ist 10. Dieser Grenzwert verhindert, dass nicht autorisierte Websites den WinHTTP-Client nach einer großen Anzahl von Umleitungen anhalten.

Gilt für: Windows XP mit SP1 und höher; Windows 2000 mit SP3 und höher.

WINHTTP_OPTION_MAX_HTTP_STATUS_CONTINUE

Die maximale Anzahl von Statuscodeantworten von Informational 100-199, die ignoriert werden, bevor der endgültige Statuscode an den WinHTTP-Client zurückgegeben wird. Informational 100-199 status codes can be sent by the server before the final status code, and are described in the specification for HTTP/1.1 (for more information, see RFC 2616). Der Standardwert ist 10.

Gilt für: Windows XP mit SP1 und höher; Windows 2000 mit SP3 und höher.

WINHTTP_OPTION_MAX_RESPONSE_DRAIN_SIZE

Eine Bindung an die Datenmenge, die aus Antworten entwässert wurde, um eine Verbindung wiederzuverwenden, die in Bytes angegeben ist. Der Standardwert ist 1 MB.

Gilt für: Windows XP mit SP1 und höher; Windows 2000 mit SP3 und höher.

WINHTTP_OPTION_MAX_RESPONSE_HEADER_SIZE

Ein gebundener Satz für die maximale Größe des Headerteils der Serverantwort, angegeben in Byte. Diese Bindung schützt den Client vor einem nicht autorisierten Server, der versucht, den Client zu hindern, indem eine Antwort mit einer unendlichen Menge von Headerdaten gesendet wird. Der Standardwert ist 64 KB.

Gilt für: Windows XP mit SP1 und höher; Windows 2000 mit SP3 und höher.

WINHTTP_OPTION_PARENT_HANDLE

Ruft das übergeordnete Handle für dieses Handle ab.

WINHTTP_OPTION_PASSPORT_COBRANDING_TEXT

Ruft eine Zeichenfolge ab, die den vom Passport-Anmeldeserver bereitgestellten Cobrandingtext enthält. Diese Option sollte sofort abgerufen werden, nachdem der Anmeldeserver mit einem Statuscode von 401 reagiert hat. Eine Anwendung sollte in Bytes eine Puffergröße übergeben, die groß genug ist, um die zurückgegebene Zeichenfolge zu enthalten.

WINHTTP_OPTION_PASSPORT_COBRANDING_URL

Ruft eine Zeichenfolge ab, die eine URL für eine Cobranding-Grafik enthält, die vom Passport-Anmeldeserver bereitgestellt wird. Diese Option sollte sofort abgerufen werden, nachdem der Anmeldeserver mit einem Statuscode von 401 reagiert hat. Eine Anwendung sollte in Bytes eine Puffergröße übergeben, die groß genug ist, um die zurückgegebene Zeichenfolge zu enthalten.

WINHTTP_OPTION_PASSPORT_RETURN_URL

Legt eine schreibgeschützte Option für ein Anforderungshandle fest, das die Passport-Rückgabe-URL abruft.

WINHTTP_OPTION_PASSPORT_SIGN_OUT

Legt die Option für ein Sitzungshandle fest, um sich bei jeder Passport-Anmeldung abzumelden. Eine Anwendung sollte die Passport-Rückgabe-URL übergeben, die mit WINHTTP_OPTION_PASSPORT_RETURN_URL abgerufen wurde. Alle Cookies im Zusammenhang mit der Rückgabe-URL werden gelöscht.

WINHTTP_OPTION_PASSWORD

Legt fest oder ruft einen Zeichenfolgenwert ab, der das Kennwort enthält, das einem Anforderungshandle zugeordnet ist.

WINHTTP_OPTION_PROXY

Dient zum Festlegen oder Abrufen einer WINHTTP_PROXY_INFO Struktur, die die Proxydaten in einem vorhandenen Sitzungshandle oder Anforderungshandle enthält. Beim Abrufen von Proxydaten muss eine Anwendung die in dieser Struktur enthaltenen Zeichenfolgen "lpszProxy" und "lpszProxyBypass " freigeben (wenn sie nicht NULL sind) mithilfe der GlobalFree-Funktion . Eine Anwendung kann die globalen Proxydaten (den Standardproxy) abfragen, indem ein NULL-Handle übergeben wird.

WINHTTP_OPTION_PROXY_PASSWORD

Legt einen Zeichenfolgenwert fest, der das Kennwort enthält, das für den Zugriff auf den Proxy verwendet wird, oder ruft diesen ab.

WINHTTP_OPTION_PROXY_SPN_USED

Ruft den Proxyserverprinzipalnamen ab, den WinHTTP während der Authentifizierung an SSPI bereitgestellt hat. Dieser Zeichenfolgenwert wird verwendet, um SspiPromptForCredentials nach einem Authentifizierungsfehler zu übergeben.

WINHTTP_OPTION_PROXY_USERNAME

Legt einen Zeichenfolgenwert fest, der den Benutzernamen enthält, der für den Zugriff auf den Proxy verwendet wird, oder ruft diesen ab.

WINHTTP_OPTION_QUIC_STATS

Ruft eine QUIC_STATISTICS Struktur ab, die Verbindungsinformationen wie RTT und gesendete und empfangene Bytes enthält.

WINHTTP_OPTION_READ_BUFFER_SIZE

Diese Option ist veraltet; es hat keine Wirkung.

WINHTTP_OPTION_RECEIVE_PROXY_CONNECT_RESPONSE

Legt fest, ob die Proxyantwortentität abgerufen werden kann. Diese Option ist standardmäßig deaktiviert.

WINHTTP_OPTION_RECEIVE_RESPONSE_TIMEOUT

Legt fest oder ruft einen nicht signierten langen ganzzahligen Wert ab, der den Timeoutwert in Millisekunden enthält, um zu warten, bis alle Antwortheader an eine Anforderung empfangen werden. Wenn WinHTTP nicht alle Header innerhalb dieses Timeoutzeitraums empfängt, wird die Anforderung abgebrochen. Der Standardtimeoutwert beträgt 90 Sekunden.

Dieses Timeout wird nur überprüft, wenn Daten aus dem Socket empfangen werden. Wenn das Timeout abläuft, wird die Clientanwendung daher erst benachrichtigt, wenn mehr Daten vom Server empfangen werden. Wenn keine Daten vom Server empfangen werden, kann die Verzögerung zwischen dem Ablauf des Timeouts und der Benachrichtigung der Clientanwendung so groß sein, wie der mit dem dwReceiveTimeout-Parameter der WinHttpSetTimeouts-Funktion festgelegte Timeoutwert.

WINHTTP_OPTION_RECEIVE_TIMEOUT

Legt fest oder ruft einen unsignierten langen ganzzahligen Wert ab, der den Timeoutwert in Millisekunden enthält, um eine teilweise Antwort auf eine Anforderung zu erhalten oder einige Daten zu lesen. Wenn die Antwort länger als dieser Timeoutwert dauert, wird die Anforderung abgebrochen. Der Standard-Timeoutwert beträgt 30 Sekunden.

WINHTTP_OPTION_REDIRECT_POLICY

Legt das Verhalten von WinHTTP bezüglich der Behandlung eines 30x-HTTP-Umleitungsstatuscodes fest. Diese Option kann für eine Sitzung oder ein Anforderungshandle auf einen der folgenden Werte festgelegt werden:

WINHTTP_OPTION_REJECT_USERPWD_IN_URL

Lehnt URLs ab, die einen Benutzernamen und ein Kennwort enthalten. Mit dieser Option werden auch URLs abgelehnt, die die Semantik "username:password " enthalten, auch wenn kein Benutzername oder Kennwort angegeben ist. Beispielsweise würden "u:p@hostname", ":@hostname", "u:@hostname" und ":p@hostname" als ungültig gekennzeichnet. Wenn eine ungültige URL an die Funktion übergeben wird, wird ERROR_WINHTTP_INVALID_URL zurückgegeben. Diese Option ist standardmäßig deaktiviert.

WINHTTP_OPTION_REQUEST_ANNOTATION

Aktiviert das Abrufen und Festlegen einer Anforderungsanmerkung für den angegebenen Anmerkungsnamen. Dadurch kann der Aufrufer eine Zeichenfolge an die Anforderung für einen späteren Abruf anfügen, um Anforderungen anhand der benutzerdefinierten Logik zu identifizieren, die der Aufrufer nützlich findet.

WINHTTP_OPTION_REQUEST_PRIORITY

Diese Option ist veraltet; es hat keine Wirkung.

WINHTTP_OPTION_REQUEST_STATS

Gibt Statistiken für die Anforderung zurück. Eine Liste der verfügbaren Statistiken finden Sie unter WINHTTP_REQUEST_STATS.

WINHTTP_OPTION_REQUEST_TIMES

Gibt Die Anzeigedauerinformationen für die Anforderung erneut an. Eine Liste der verfügbaren Anzeigedauern finden Sie unter WINHTTP_REQUEST_TIMES.

WINHTTP_OPTION_REQUIRE_STREAM_END

Diese Option weist WinHttp an, antwortheader "Content-Length" zu ignorieren und den Empfang in einem Datenstrom fortzusetzen, bis das END_STREAM Flag empfangen wird.

WINHTTP_OPTION_RESOLUTION_HOSTNAME

Diese Option kann für ein WinHttp-Anforderungshandle festgelegt werden, bevor sie gesendet wurde. Bei Festlegung verwendet WinHttp die vom Aufrufer bereitgestellte Zeichenfolge als Hostname für die DNS-Auflösung.

WINHTTP_OPTION_RESOLVE_TIMEOUT

Legt fest oder ruft einen nicht signierten langen ganzzahligen Wert, der den Timeoutwert in Millisekunden enthält, um einen Hostnamen aufzulösen. Der Standardtimeoutwert ist INFINITE. Wenn ein nicht standardmäßiger Wert angegeben ist, liegt ein Aufwand für eine Threaderstellung pro Namensauflösung vor.

WINHTTP_OPTION_REVERT_IMPERSONATION_SERVER_CERT

Stellt alle Threadwechsel beim Erstellen der Serverzertifikatkette zurück, wodurch stattdessen die Verwendung des Prozesstokens erzwungen wird.

WINHTTP_OPTION_SECURE_PROTOCOLS

Legt einen wert vom Typ "Unsigned long integer" fest, der angibt, welche Secure (HTTPS)-Protokolle akzeptabel sind. Der Standardwert für diese Einstellung variiert je nach Betriebssystemversion und kann durch installierte Updates beeinträchtigt werden.

• Windows 11. Standardmäßig sind nur TLS1.2 und TLS1.3 aktiviert.
• Windows 10 und Windows 8.1. Standardmäßig sind nur SSL3, TLS1.0, TLS1.1 und TLS1.2 aktiviert.
• Windows 8 und Windows 7. Standardmäßig sind nur SSL3 und TLS1 aktiviert.

Der Wert kann eine Kombination aus einem oder mehreren der folgenden Werte sein.

Wenn Sie die Unterstützung für neuere Protokolle aktivieren müssen, Ihre Anwendung jedoch nicht erneut kompilieren können, um die entsprechenden Werte von WINHTTP_OPTION_SECURE_PROTOCOLS zu verwenden, können Sie stattdessen den DefaultSecureProtocols Registrierungseintrag hinzufügen. Mit diesem Registrierungseintrag können Sie angeben, welche sicheren Protokolle verwendet werden sollen, wenn die Option WINHTTP_OPTION_SECURE_PROTOCOLS nicht festgelegt ist.

Wenn eine Anwendung WinHttpSetOption(WINHTTP_OPTION_SECURE_PROTOCOLS) nicht aufruft, überprüft das System den DefaultSecureProtocols Registrierungseintrag und setzt, falls vorhanden, das vorhandene Betriebssystem standardmäßig mit den im DefaultSecureProtocols Registrierungseintrag angegebenen Protokollen außer Kraft. Die winHTTP-angegebenen Protokolle können von den Konfigurationseinstellungen für einmaligen Kanal (Secure Channel, Schannel) überstimmt werden, die Protokolle deaktivieren können.

Sie können den DefaultSecureProtocols Registrierungseintrag im folgenden Pfad hinzufügen:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp

Auf x64-basierten Computern müssen Sie auch dem Wow6432Node Pfad hinzufügenDefaultSecureProtocols:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp

Der Registrierungswert ist eine DWORD-Bitmap. Der zu verwendende Wert wird durch Hinzufügen der Werte bestimmt, die den gewünschten Protokollen entsprechen.

Wenn Sie beispielsweise die Standardwerte für WINHTTP_OPTION_SECURE_PROTOCOLS überschreiben möchten, um TLS 1.1 und TLS 1.2 anzugeben. Nehmen Sie in diesem Fall den Wert für TLS 1.1 (0x00000200) und den Wert für TLS 1.2 (0x00000800), fügen Sie sie im Rechner (im Programmiermodus) hinzu, und der resultierende Registrierungswert wäre 0x00000A00.

WINHTTP_OPTION_SECURITY_CERTIFICATE_STRUCT

Ruft das Zertifikat für einen SSL/TLS-Server in der WINHTTP_CERTIFICATE_INFO-Struktur ab. Die Anwendung muss die lpszSubjectInfo - und lpszIssuerInfo-Member mit LocalFree freigeben.

WINHTTP_OPTION_SECURITY_FLAGS

Dient zum Festlegen oder Abrufen eines werts vom Typ "Unsigned long integer", der die Sicherheitskennzeichnungen für ein Handle enthält. Dabei kann es sich um eine Kombination dieser Werte handeln:

WINHTTP_OPTION_SECURITY_INFO

Retreives the SChannel connection and cipher information for a request.

WINHTTP_OPTION_SECURITY_KEY_BITNESS

Ruft einen nicht signierten ganzzahligen Wert ab, der die Verschlüsselungsstärke des Verschlüsselungsschlüssels enthält. Eine größere Zahl gibt eine stärkere Verschlüsselung der Verschlüsselungsstärke an.

WINHTTP_OPTION_SEND_TIMEOUT

Legt fest oder ruft einen nicht signierten langen ganzzahligen Wert, der den Timeoutwert in Millisekunden enthält, um eine Anforderung zu senden oder einige Daten zu schreiben. Wenn das Senden der Anforderung länger dauert als das Timeout, wird der Sendevorgang abgebrochen. Der Standardzeitraum bis zum Timeout beträgt 30 Sekunden.

WINHTTP_OPTION_SERVER_CBT

Ruft einen Zeiger auf SecPkgContext_Bindings Struktur ab, die ein Kanalbindungstoken (Channel Binding Token, CBT) angibt.

Ein Kanalbindungstoken ist eine Eigenschaft eines sicheren Transportkanals und wird verwendet, um einen Authentifizierungskanal an den sicheren Transportkanal zu binden. Dieses Token kann nur von dieser Option abgerufen werden, nachdem eine SSL-Verbindung hergestellt wurde.

WINHTTP_OPTION_SERVER_CERT_CHAIN_CONTEXT

Ruft den Kontext der Serverzertifizierungskette ab. WINHTTP_OPTION_SERVER_CERT_CHAIN_CONTEXT können übergeben werden, um einen duplizierten Zeiger auf die CERT_CHAIN_CONTEXT für eine Serverzertifikatkette zu erhalten, die während einer ausgehandelten SSL-Verbindung empfangen wurde. Der Client muss CertFreeCertificateContext für den zurückgegebenen PCCERT_CONTEXT Zeiger aufrufen, der in den Puffer gefüllt ist.

WINHTTP_OPTION_SERVER_CERT_CONTEXT

Ruft den Serverzertifizierungskontext ab. WINHTTP_OPTION_SERVER_CERT_CONTEXT können übergeben werden, um einen duplizierten Zeiger auf den CERT CONTEXT für ein Serverzertifikat zu erhalten, das während einer ausgehandelten SSL-Verbindung empfangen wurde. Der Client muss CertFreeCertificateContext für den zurückgegebenen PCCERT_CONTEXT Zeiger aufrufen, der in den Puffer gefüllt ist.

WINHTTP_OPTION_SERVER_SPN_USED

Ruft den Serverprinzipalnamen ab, den WinHTTP während der Authentifizierung an SSPI bereitgestellt hat. Dieser Zeichenfolgenwert kann nach einem Authentifizierungsfehler an SspiPromptForCredentials übergeben werden.

WINHTTP_OPTION_SPN

Enthält oder entfernt die Serverportnummer, wenn der SPN (Dienstprinzipalname) für Kerberos- oder Aushandeln der Kerberos-Authentifizierung erstellt wird. Dieses Kennzeichen ist einer der folgenden Werte:

WINHTTP_OPTION_STREAM_ERROR_CODE

Diese Option kann auf einem WinHttp-Anforderungshandle abgefragt werden und gibt den fehlercode zurück, der von einem RST_STREAM Frame angegeben wird, der in einem HTTP-Stream empfangen wurde.

WINHTTP_OPTION_TCP_FAST_OPEN

Aktiviert TCP Fast Open für die Verbindung.

WINHTTP_OPTION_TCP_KEEPALIVE

Diese Option kann für ein WinHttp-Sitzungshandle festgelegt werden, um das TCP-Keep-Alive-Verhalten für den zugrunde liegenden Socket zu aktivieren. Übernimmt eine tcp_keepalive Struktur.

WINHTTP_OPTION_TLS_FALSE_START

Aktiviert tls False Start für die Verbindung.

WINHTTP_OPTION_TCP_PRIORITY_STATUS

Fragen Sie die angedeutete Priorität des TCP-Sockets ab, der mit WINHTTP_OPTION_TCP_PRIORITY_HINT festgelegt wurde. Weitere Informationen finden Sie in der Dokumentation zu SIO_SET_PRIORITY_HINT .

WINHTTP_OPTION_TLS_PROTOCOL_INSECURE_FALLBACK

Diese Option kann für ein WinHttp-Sitzungshandle festgelegt werden, um zu steuern, ob Fallback auf TLS 1.0 zulässig ist, wenn ein TLS-Handshake-Fehler mit einer neueren Protokollversion vorhanden ist.

WINHTTP_OPTION_UNLOAD_NOTIFY_EVENT

Übernimmt ein Ereignis, das festgelegt wird, wenn der letzte Rückruf für eine bestimmte Sitzung abgeschlossen wurde. Dieses Flag muss für ein Sitzungshandle verwendet werden. Das Ereignis kann erst geschlossen werden, nachdem es von WinHTTP festgelegt wurde.

WINHTTP_OPTION_UNSAFE_HEADER_PARSING

Diese Option ist für die interne Verwendung reserviert und sollte nicht aufgerufen werden.

WINHTTP_OPTION_UPGRADE_TO_WEB_SOCKET

Weist den Stapel an, einen WebSocket-Handshake-Prozess mit WinHttpSendRequest zu starten. Diese Option akzeptiert keine Parameter.

WINHTTP_OPTION_URL

Ruft einen Zeichenfolgenwert ab, der die vollständige URL einer heruntergeladenen Ressource enthält. Wenn die ursprüngliche URL zusätzliche Daten enthält, z. B. Suchzeichenfolgen oder Anker, oder wenn der Aufruf umgeleitet wurde, unterscheidet sich die zurückgegebene URL vom Original. Die Anwendung sollte einen Puffer übergeben, der in Bytes groß genug ist, um die zurückgegebene URL in breitem Zeichen zu enthalten.

WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS

Akzeptiert ein BOOL und kann nur ein Sitzungshandle festgelegt werden. Sie wird nur an Handles weitergegeben, die aus dem Sitzungshandle erstellt wurden, nachdem die Option festgelegt wurde. Wenn WAHR, verursacht diese Option als letztes Mittel die Verwendung von globalen Serveranmeldeinformationen, die von WinInet gedrückt wurden. Der Standardwert für diese Option ist FALSE. Für diese Option ist der Registrierungsschlüssel HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings erforderlich! ShareCredsWithWinHttp. Dieser Registrierungsschlüssel ist standardmäßig nicht vorhanden. Wenn sie festgelegt ist, sendet WinINet Anmeldeinformationen an WinHTTP. Wenn WinHttp eine Authentifizierungsabfrage erhält und keine Anmeldeinformationen für das aktuelle Handle festgelegt sind, werden die von WinINet bereitgestellten Anmeldeinformationen verwendet.

WINHTTP_OPTION_USE_SESSION_SCH_CRED

Ermöglicht das Festlegen einer einzelnen Anmeldeinformationen, die standardmäßig für alle Endpunkte innerhalb der Sitzung verwendet werden sollen, anstatt standardanmeldeinformationen pro Endpunkt zu verwenden. Dies kann die Leistung verbessern, indem der Aufwand für die Verwaltung von Anmeldeinformationen verringert wird. Beachten Sie, dass diese Standardanmeldeinformationen keine Auswirkungen haben, wenn ein Clientzertifikat explizit bereitgestellt wird.

WINHTTP_OPTION_USER_AGENT

Legt die Benutzer-Agent-Zeichenfolge für Handles fest, die von WinHttpOpen bereitgestellt und in nachfolgenden WinHttpSendRequest-Funktionen verwendet werden, sofern sie nicht von einem Header außer Kraft gesetzt wird, der von WinHttpAddRequestHeaders oder WinHttpSendRequest hinzugefügt wird. Beim Abrufen eines Benutzer-Agents sollte die Anwendung einen Puffer übergeben, der in Bytes groß genug ist, um die zurückgegebene URL in breitem Zeichen zu halten. Beim Festlegen des Benutzer-Agents ist die Puffergröße die Länge der Zeichenfolge in Zeichen sowie der NULL-Terminator .

WINHTTP_OPTION_USERNAME

Legt eine Zeichenfolge fest, die den Benutzernamen enthält, oder ruft diese ab.

WINHTTP_OPTION_WEB_SOCKET_CLOSE_TIMEOUT

Legt die Zeit in Millisekunden fest, die WinHttpWebSocketClose warten soll, um den schließenden Handshake abzuschließen. Der Standardwert ist 10 Sekunden.

WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL

Legt das Intervall in Millisekunden fest, um ein Keep-Alive-Paket über die Verbindung zu senden. Das Standardintervall ist 30000 (30 Sekunden). Das Mindestintervall beträgt 15000 (15 Sekunden). Die Verwendung von WinHttpSetOption zum Festlegen eines Werts unter 15000 wird mit ERROR_INVALID_PARAMETER zurückgegeben.

WINHTTP_OPTION_WEB_SOCKET_RECEIVE_BUFFER_SIZE

Legt fest oder ruft ein DWORD, das die Empfangenpuffergröße angibt, die für WebSocket-Verbindungen verwendet werden soll.

WINHTTP_OPTION_WEB_SOCKET_SEND_BUFFER_SIZE

Legt fest oder ruft ein DWORD, das die Sendepuffergröße angibt, die für WebSocket-Verbindungen verwendet werden soll.

WINHTTP_OPTION_WORKER_THREAD_COUNT

Legt einen wert vom Typ "Unsigned long integer" fest, der die Anzahl der Workerthreads angibt, die der Threadpool für asynchrone Fertigstellungen verwenden soll. Der Standardwert dieser Option ist Null, wodurch angegeben wird, dass die Anzahl der Arbeitsthreads der Anzahl der CPUs im System entspricht. Diese Option kann nur für ein NULLHINTERNET-Handle festgelegt werden, bevor ein asynchroner Vorgang aufgetreten ist. Diese Option kann nur einmal festgelegt werden.

Gilt für: Windows 7 und höher; Windows Server 2008 R2 und höher.

WINHTTP_OPTION_WRITE_BUFFER_SIZE

Diese Option ist veraltet; es hat keine Wirkung.

Bemerkungen

In der folgenden Tabelle sind die Optionskennzeichnungen aufgeführt, indem angegeben wird, auf welche Handles sie reagieren können, ob sie abgefragt und festgelegt werden können, und den verwendeten Datentyp. Ein "X" gibt an, dass das Optionskennzeichnung für die Verwendung mit der Funktion oder dem Handle gültig ist, während ein "-" angibt, dass das Optionsflagge ungültig ist.

Wenn Sie versuchen, ein Optionskennzeichnungszeichen für eine Windows-Version festzulegen oder abzufragen, in der sie nicht unterstützt wird, wird ERROR_WINHTTP_INVALID_OPTION.

Anforderungen

Siehe auch

• WinHTTP-Versionen