CreatePersistentUdpPortReservation-Funktion (iphlpapi.h)

Artikel
03/14/2023

Die CreatePersistentUdpPortReservation-Funktion erstellt eine persistente UDP-Portreservierung für einen aufeinanderfolgenden Block von UDP-Ports auf dem lokalen Computer.

Syntax

IPHLPAPI_DLL_LINKAGE ULONG CreatePersistentUdpPortReservation(
  [in]  USHORT   StartPort,
  [in]  USHORT   NumberOfPorts,
  [out] PULONG64 Token
);

Parameter

[in] StartPort

Die UDP-Startportnummer in Netzwerkbytereihenfolge.

[in] NumberOfPorts

Die Anzahl der zu reservierenden UDP-Portnummern.

[out] Token

Ein Zeiger auf ein Portreservierungstoken, das zurückgegeben wird, wenn die Funktion erfolgreich ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Zugriff verweigert.“ Dieser Fehler wird unter folgenden Bedingungen zurückgegeben: Dem Benutzer fehlen die erforderlichen Administratorrechte auf dem lokalen Computer, oder die Anwendung wird nicht in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausgeführt.
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn null im StartPort- oder NumberOfPorts-Parameter übergeben wird. Dieser Fehler wird auch zurückgegeben, wenn der Parameter NumberOfPorts je nach StartPort-Parameter zu groß ist, dass der zuweisungsfähige Portblock den maximalen Port überschreiten würde, der zugeordnet werden kann.
ERROR_SHARING_VIOLATION	Der Prozess kann nicht auf die Datei zugreifen, da sie bereits von einem anderen Prozess verwendet wird. Dieser Fehler wird zurückgegeben, wenn bereits ein UDP-Port im Block der UDP-Ports verwendet wird, der durch die Parameter StartPort und NumberOfPorts angegeben wird. Dieser Fehler wird auch zurückgegeben, wenn eine persistente Reservierung für einen Block von UDP-Ports, der durch die Parameter StartPort und NumberOfPorts angegeben wird, einer persistenten Reservierung für einen bereits erstellten BLOCK von UDP-Ports entspricht oder sich überschneidet.
Andere	Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die CreatePersistentUdpPortReservation-Funktion ist unter Windows Vista und höher definiert.

Die CreatePersistentUdpPortReservation-Funktion wird verwendet, um eine persistente Reservierung für einen Block von UDP-Ports hinzuzufügen.

Anwendungen und Dienste, die Ports reservieren müssen, fallen in zwei Kategorien. Die erste Kategorie umfasst Komponenten, die einen bestimmten Port als Teil ihres Betriebs benötigen. Solche Komponenten bevorzugen es in der Regel, ihren erforderlichen Port zur Installationszeit anzugeben (z. B. in einem Anwendungsmanifest). Die zweite Kategorie umfasst Komponenten, die zur Laufzeit einen verfügbaren Port oder Portblock benötigen.

Diese beiden Kategorien entsprechen spezifischen Und Wildcard-Portreservierungsanforderungen. Bestimmte Reservierungsanforderungen können persistent oder runtime sein, während Reservierungsanforderungen für Wildcardports nur zur Laufzeit unterstützt werden.

Die CreatePersistentUdpPortReservation-Funktion bietet einer Anwendung oder einem Dienst die Möglichkeit, einen Block von UDP-Ports dauerhaft zu reservieren. Persistente TCP-Reservierungen werden in einem persistenten Speicher für das UDP-Modul in Windows aufgezeichnet.

Ein Aufrufer ruft eine persistente Portreservierung ab, indem er angibt, wie viele Ports erforderlich sind und ob ein bestimmter Bereich benötigt wird. Wenn die Anforderung erfüllt werden kann, gibt die CreatePersistentUdpPortReservation-Funktion ein eindeutiges undurchsichtiges ULONG64 Token zurück, das anschließend die Reservierung identifiziert. Eine persistente UDP-Portreservierung kann durch Aufrufen der DeletePersistentUdpPortReservation-Funktion freigegeben werden. Beachten Sie, dass sich das Token für eine bestimmte persistente UDP-Portreservierung bei jedem Neustart des Systems ändern kann.

Windows implementiert keine komponentenübergreifende Sicherheit für persistente Reservierungen, die mit diesen Funktionen abgerufen werden. Dies bedeutet, dass, wenn einer Komponente die Möglichkeit gewährt wird, persistente Portreservierungen abzurufen, diese Komponente automatisch die Möglichkeit erhält, alle persistenten Portreservierungen zu nutzen, die einer anderen Komponente im System gewährt werden. Die Sicherheit auf Prozessebene wird für Laufzeitreservierungen erzwungen, kann jedoch nicht auf permanente Reservierungen erweitert werden, die mit der CreatePersistentTcpPortReservation - oder CreatePersistentUdpPortReservation-Funktion erstellt wurden.

Nachdem eine persistente UDP-Portreservierung abgerufen wurde, kann eine Anwendung Portzuweisungen von der UDP-Portreservierung anfordern, indem sie einen UDP-Socket öffnet und dann die WSAIoctl-Funktion aufruft , die die SIO_ASSOCIATE_PORT_RESERVATION IOCTL angibt, und das Reservierungstoken übergeben, bevor sie einen Aufruf der Bindfunktion im Socket ausgibt.

Die SIO_ACQUIRE_PORT_RESERVATION IOCTL kann verwendet werden, um eine Laufzeitreservierung für einen Block von TCP- oder UDP-Ports anzufordern. Für Laufzeitportreservierungen erfordert der Portpool, dass Reservierungen aus dem Prozess verwendet werden, für den die Reservierung gewährt wurde. Laufzeitportreservierungen dauern nur so lange wie die Lebensdauer des Sockets, für den die SIO_ACQUIRE_PORT_RESERVATION IOCTL aufgerufen wurde. Im Gegensatz dazu können persistente Portreservierungen, die mit der CreatePersistentUdpPortReservation-Funktion erstellt wurden, von jedem Prozess verwendet werden, der persistente Reservierungen abrufen kann.

Die CreatePersistentUdpPortReservation-Funktion kann nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn CreatePersistentUdpPortReservation von einem Benutzer aufgerufen wird, der kein Mitglied der Gruppe Administratoren ist, schlägt der Funktionsaufruf fehl, und ERROR_ACCESS_DENIED wird zurückgegeben. Diese Funktion kann auch aufgrund der Benutzerkontensteuerung (User Account Control, UAC) unter Windows Vista und höher fehlschlagen. Wenn eine Anwendung, die diese Funktion enthält, von einem Benutzer ausgeführt wird, der als Mitglied der Gruppe Administratoren angemeldet ist, die nicht der integrierten Administratorgruppe angehört, schlägt dieser Aufruf fehl, es sei denn, die Anwendung wurde in der Manifestdatei mit einem requestedExecutionLevel gekennzeichnet, der auf requireAdministrator festgelegt ist. Wenn der Anwendung diese Manifestdatei fehlt, muss ein Benutzer, der sich als Mitglied der Gruppe Administratoren angemeldet hat, als der integrierte Administrator, die Anwendung dann in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausführen, damit diese Funktion erfolgreich ist.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	iphlpapi.h
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll