Fonction RtmAddRouteToDest (rtmv2.h)

Article
03/01/2024

La fonction RtmAddRouteToDest ajoute un nouvel itinéraire à la table de routage ou met à jour un itinéraire existant dans la table de routage. Si la meilleure route change, une notification de modification est générée.

Syntaxe

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
);

Paramètres

[in] RtmRegHandle

Gérez le client obtenu à partir d’un appel précédent à RtmRegisterEntity.

[in, out] RouteHandle

Si le client a un handle (mise à jour d’un itinéraire) : en entrée, RouteHandle est un pointeur vers le handle d’itinéraire. Sur la sortie, RouteHandle est inchangé.

Si le client n’a pas de handle et qu’un handle doit être retourné (le client ajoute ou met à jour un itinéraire) : En entrée, RouteHandle est un pointeur vers NULL. Lors de la sortie, RouteHandle reçoit un pointeur vers le handle d’itinéraire. Les valeurs dans RouteInfo sont utilisées pour identifier l’itinéraire à mettre à jour.

Si un handle n’a pas besoin d’être retourné (le client ajoute ou met à jour un itinéraire) : en entrée, RouteHandle a la valeur NULL. Les valeurs dans RouteInfo sont utilisées pour identifier l’itinéraire à mettre à jour.

[in] DestAddress

Pointeur vers l’adresse réseau de destination à laquelle l’itinéraire est ajouté ou mis à jour.

[in] RouteInfo

Pointeur vers les informations d’itinéraire à ajouter ou à mettre à jour.

[in] TimeToLive

Spécifie la durée, en millisecondes, après laquelle l’itinéraire a expiré. Spécifiez INFINITE pour empêcher l’expiration des itinéraires.

[in] RouteListHandle

Gérez vers une liste d’itinéraires vers laquelle déplacer l’itinéraire. Ce paramètre est facultatif et peut être défini sur NULL.

[in] NotifyType

Définissez ce paramètre sur NULL. Ce paramètre est réservé à un usage futur.

[in] NotifyHandle

Définissez ce paramètre sur NULL. Ce paramètre est réservé à un usage futur.

[in, out] ChangeFlags

En entrée, ChangeFlags est un pointeur vers un type de données RTM_ROUTE_CHANGE_FLAGS qui indique si le gestionnaire de table de routage doit ajouter un nouvel itinéraire ou mettre à jour un itinéraire existant.

Sur la sortie, ChangeFlags est un pointeur vers un type de données RTM_ROUTE_CHANGE_FLAGS qui reçoit l’indicateur indiquant le type de modification qui a été effectué et si la meilleure route a été modifiée. Les indicateurs suivants sont utilisés.

Constant	Signification
RTM_ROUTE_CHANGE_FIRST	Indique que le gestionnaire de table de routage ne doit pas case activée le membre Neighbor du paramètre RouteInfo pour déterminer si deux itinéraires sont égaux.
RTM_ROUTE_CHANGE_NEW	Retourné par le gestionnaire de table de routage pour indiquer qu’un nouvel itinéraire a été créé.
RTM_ROUTE_CHANGE_BEST	Retourné par le gestionnaire de table de routage pour indiquer que l’itinéraire qui a été ajouté ou mis à jour était le meilleur itinéraire, ou qu’en raison de la modification, un nouvel itinéraire est devenu le meilleur itinéraire.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Valeur	Signification
ERROR_ACCESS_DENIED	Le client appelant n’est pas propriétaire de cet itinéraire.
ERROR_INVALID_HANDLE	Le handle n'est pas valide.
ERROR_INVALID_PARAMETER	Un paramètre contient des informations incorrectes.
ERROR_NOT_ENOUGH_MEMORY	La mémoire est insuffisante pour effectuer cette opération.

Remarques

Deux itinéraires sont considérés comme égaux si les valeurs suivantes sont égales :

Réseau de destination
Propriétaire de l’itinéraire
Voisin qui a fourni l’itinéraire

Lorsqu’un client met à jour un itinéraire, il est plus efficace de passer un handle à l’itinéraire à mettre à jour dans le paramètre RouteHandle , car le gestionnaire de table de routage n’a pas besoin d’effectuer une recherche pour l’itinéraire dans la table de routage.

Si un handle a été retourné, relâchez le handle lorsqu’il n’est plus nécessaire en appelant RtmReleaseRoutes.

Pour obtenir un exemple de code utilisant cette fonction, consultez Ajouter et mettre à jour des routes à l’aide de RtmAddRouteToDest.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Aucun pris en charge
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	rtmv2.h
Bibliothèque	Rtm.lib
DLL	Rtm.dll