RtmAddRouteToDest-Funktion (rtmv2.h)

Artikel
08/25/2023

Die RtmAddRouteToDest-Funktion fügt der Routingtabelle eine neue Route hinzu oder aktualisiert eine vorhandene Route in der Routingtabelle. Wenn sich die beste Route ändert, wird eine Änderungsbenachrichtigung generiert.

Syntax

DWORD RtmAddRouteToDest(
  [in]      RTM_ENTITY_HANDLE       RtmRegHandle,
  [in, out] PRTM_ROUTE_HANDLE       RouteHandle,
  [in]      PRTM_NET_ADDRESS        DestAddress,
  [in]      PRTM_ROUTE_INFO         RouteInfo,
  [in]      ULONG                   TimeToLive,
  [in]      RTM_ROUTE_LIST_HANDLE   RouteListHandle,
  [in]      RTM_NOTIFY_FLAGS        NotifyType,
  [in]      RTM_NOTIFY_HANDLE       NotifyHandle,
  [in, out] PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parameter

[in] RtmRegHandle

Handle an den Client, der von einem vorherigen Aufruf von RtmRegisterEntity abgerufen wurde.

[in, out] RouteHandle

Wenn der Client über ein Handle (Aktualisieren einer Route) verfügt: Bei der Eingabe ist RouteHandle ein Zeiger auf das Routenhandle. Bei der Ausgabe bleibt RouteHandle unverändert.

Wenn der Client über kein Handle verfügt und ein Handle zurückgegeben werden muss (der Client fügt eine Route hinzu oder aktualisiert sie): Bei der Eingabe ist RouteHandle ein Zeiger auf NULL. Bei der Ausgabe empfängt RouteHandle einen Zeiger auf das Routenhandle. Die Werte in RouteInfo werden verwendet, um die zu aktualisierende Route zu identifizieren.

Wenn kein Handle zurückgegeben werden muss (client fügt eine Route hinzu oder aktualisiert diese): Bei der Eingabe ist RouteHandleNULL. Die Werte in RouteInfo werden verwendet, um die zu aktualisierende Route zu identifizieren.

[in] DestAddress

Zeiger auf die Zielnetzwerkadresse, zu der die Route hinzugefügt oder aktualisiert wird.

[in] RouteInfo

Zeiger auf die Routeninformationen, die hinzugefügt oder aktualisiert werden sollen.

[in] TimeToLive

Gibt die Zeit in Millisekunden an, nach der die Route abgelaufen ist. Geben Sie INFINITE an, um zu verhindern, dass Routen ablaufen.

[in] RouteListHandle

Handle für eine Routenliste, in die die Route verschoben werden soll. Dieser Parameter ist optional und kann auf NULL festgelegt werden.

[in] NotifyType

Legen Sie diesen Parameter auf NULL fest. Dieser Parameter ist für die zukünftige Verwendung reserviert.

[in] NotifyHandle

Legen Sie diesen Parameter auf NULL fest. Dieser Parameter ist für die zukünftige Verwendung reserviert.

[in, out] ChangeFlags

Bei der Eingabe ist ChangeFlags ein Zeiger auf einen RTM_ROUTE_CHANGE_FLAGS Datentyp, der angibt, ob der Routingtabellen-Manager eine neue Route hinzufügen oder eine vorhandene route aktualisieren soll.

In der Ausgabe ist ChangeFlags ein Zeiger auf einen RTM_ROUTE_CHANGE_FLAGS Datentyp, der das Flag empfängt, das den Typ der tatsächlich durchgeführten Änderung angibt, und ob die beste Route geändert wurde. Die folgenden Flags werden verwendet.

Konstante	Bedeutung
RTM_ROUTE_CHANGE_FIRST	Gibt an, dass der Routingtabellen-Manager den Neighbor-Member des RouteInfo-Parameters nicht überprüfen soll, wenn ermittelt wird, ob zwei Routen gleich sind.
RTM_ROUTE_CHANGE_NEW	Wird vom Routingtabellen-Manager zurückgegeben, um anzugeben, dass eine neue Route erstellt wurde.
RTM_ROUTE_CHANGE_BEST	Wird vom Routingtabellen-Manager zurückgegeben, um anzugeben, dass die hinzugefügte oder aktualisierte Route die beste Route war oder dass aufgrund der Änderung eine neue Route die beste Route wurde.

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.

Wert	Bedeutung
ERROR_ACCESS_DENIED	Der aufrufende Client besitzt diese Route nicht.
ERROR_INVALID_HANDLE	Das Handle ist ungültig.
ERROR_INVALID_PARAMETER	Ein Parameter enthält falsche Informationen.
ERROR_NOT_ENOUGH_MEMORY	Es ist nicht genügend Arbeitsspeicher vorhanden, um diesen Vorgang abzuschließen.

Hinweise

Zwei Routen gelten als gleich, wenn die folgenden Werte gleich sind:

Das Zielnetzwerk
Der Besitzer der Route
Der Nachbar, der die Route bereitgestellt hat

Wenn ein Client eine Route aktualisiert, ist es effizienter, ein Handle an die zu aktualisierende Route im RouteHandle-Parameter zu übergeben, da der Routingtabellen-Manager keine Suche nach der Route in der Routingtabelle durchführen muss.

Wenn ein Handle zurückgegeben wurde, geben Sie das Handle frei, wenn es nicht mehr benötigt wird, indem Sie RtmReleaseRoutes aufrufen.

Beispielcode mit dieser Funktion finden Sie unter Hinzufügen und Aktualisieren von Routen mithilfe von RtmAddRouteToDest.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Nicht unterstützt
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	rtmv2.h
Bibliothek	Rtm.lib
DLL	Rtm.dll