WinHttpConnectionSetPolicyEntries-Funktion

Registriert eine Reihe von Verbindungsroutingrichtlinieneinträgen beim WinHTTP-Autoproxydienst. Richtlinieneinträge definieren, welche Netzwerkverbindungen für bestimmte Host-/Anwendungskombinationen verwendet werden sollen, wodurch verbindungsfähiges HTTP-Routing aktiviert wird.

Syntax

DWORD WINAPI WinHttpConnectionSetPolicyEntries(
    _In_ HINTERNET                              hSession,
    _In_ WINHTTP_CONNECTION_POLICY_TAG          PolicyEntryTag,
    _In_ WINHTTP_CONNECTION_POLICY_ENTRY_LIST  *pPolicyEntryList
);

Parameter

hSession [in]

Ein gültiges WinHTTP-Sitzungshandle, das von WinHttpOpen erstellt wurde. Das Handle muss ein Handle auf Sitzungsebene sein.

PolicyEntryTag [in]

Gibt den Besitzer/die Quelle der Richtlinieneinträge an. Einer der folgenden Werte.

Value Bedeutung
TAG_WINHTTP_CONNECTION_POLICY_TAG_DEFAULT (0) Standard-/nicht markierte Richtlinieneinträge.
TAG_WINHTTP_CONNECTION_POLICY_TAG_CONNECTION_MANAGER (1) Reserviert für Vom Systemverbindungs-Manager verwaltete Einträge. Anwendungen von Drittanbietern sollten TAG_WINHTTP_CONNECTION_POLICY_TAG_WWWPT verwenden, um Konflikte mit Systemeinträgen zu vermeiden.
TAG_WINHTTP_CONNECTION_POLICY_TAG_WWWPT (2) Einträge, die von der WWWPT-Komponente (Windows Web Platform Transport) verwaltet werden.

Tags ermöglichen es mehreren Komponenten, ihre Richtliniensätze unabhängig zu verwalten, ohne einander zu überschreiben.

pPolicyEntryList [in]

Zeigen Sie auf eine WINHTTP_CONNECTION_POLICY_ENTRY_LIST Struktur, die ein Array von Richtlinieneinträgen enthält.

Jede WINHTTP_CONNECTION_POLICY_ENTRY in der Liste enthält:

  • pwszHost – Zielhostmuster, für das diese Richtlinie gilt.
  • pwszAppId – Anwendungsbezeichner (Paketfamilienname oder "*" für alle Apps).
  • cbAppSid / pbAppSid – Optionale App-Container-SID für die Anwendung. Legen Sie cbAppSid auf 0 und pbAppSid auf NULL fest, falls nicht zutreffend.
  • nConnections – Anzahl der Verbindungsnamen in ppwszConnections.
  • ppwszConnections – Array von Verbindungsnamenzeichenfolgen, die Datenverkehr für diese Host-/App-Kombination enthalten können.
  • dwPolicyEntryFlags – Derzeit werden keine Flags unterstützt.

Rückgabewert

Gibt ERROR_SUCCESS (0) bei Erfolg zurück. Gibt einen Systemfehlercode für Fehler zurück, einschließlich der folgenden.

Value Beschreibung
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE hSession ist kein Sitzungshandle.
ERROR_WINHTTP_NOT_INITIALIZED WinHTTP-Globalen werden nicht initialisiert.
ERROR_ACCESS_DENIED Der Aufrufer verfügt nicht über erforderliche Berechtigungen.

Remarks

Hinweis

Diese API ist derzeit nicht in einer SDK-Headerdatei enthalten. Sie müssen die Funktion selbst in Ihrem Code deklarieren.

Richtlinieneinträge weisen WinHTTP an, welche benannten Verbindungen berechtigt sind, Datenverkehr zu übertragen, der für bestimmte Hosts bestimmt ist oder von bestimmten Anwendungen stammt. Dies ist zentral für verbindungsfähige Netzwerke auf Geräten mit mehreren gleichzeitigen Netzwerkverbindungen.

Durch Aufrufen dieser Funktion werden alle zuvor festgelegten Einträge für dasselbe PolicyEntryTag ersetzt. Das typische Muster lautet:

  1. Rufen Sie WinHttpConnectionDeletePolicyEntries auf, um veraltete Einträge zu löschen.
  2. Rufen Sie WinHttpConnectionSetPolicyEntries mit dem vollständigen aktualisierten Satz auf.

Die Windows Verbindungs-Manager verwendet TAG_WINHTTP_CONNECTION_POLICY_TAG_CONNECTION_MANAGER zum Übertragen von Host-zu-Verbindung-Routingregeln, die von der Verbindungsauswahllogik abgeleitet sind.

Für diese API sind erhöhte Rechte (Administrator/SYSTEM) erforderlich.

Example

Im folgenden Beispiel werden vorhandene Verbindungs-Manager-Richtlinieneinträge gelöscht und anschließend eine neue On-Demand-Richtlinie für alle Apps registriert, die eine Verbindung mit Hosts herstellen, die übereinstimmen *.contoso.com.

// First delete existing connection manager policies
WinHttpConnectionDeletePolicyEntries(
    hSession,
    TAG_WINHTTP_CONNECTION_POLICY_TAG_WWWPT);

// Then set new policies
WINHTTP_CONNECTION_POLICY_ENTRY entry = {};
entry.pwszHost = L"*.contoso.com";
entry.pwszAppId = L"*";

PCWSTR connectionName = L"Contoso Cellular";
entry.nConnections = 1;
entry.ppwszConnections = &connectionName;

WINHTTP_CONNECTION_POLICY_ENTRY_LIST list = {};
list.pPolicyEntries = &entry;
list.nEntries = 1;

WinHttpConnectionSetPolicyEntries(
    hSession,
    TAG_WINHTTP_CONNECTION_POLICY_TAG_WWWPT,
    &list);

Anforderungen

Requirement Value
Header N/A
Bibliothek winhttp.lib
DLL winhttp.dll

Siehe auch

  • Last updated on