RtmRegisterEntity function (rtmv2.h)

Article
10/13/2021

The RtmRegisterEntity function registers a client with an instance of the routing table manager for a specific address family. The routing table manager returns a registration handle and a profile of the instance. The profile contains a list of values that are used when calling other functions. Values include the maximum number of destinations returned in a buffer by a single call.

Registration is the first action a client should take.

Syntax

DWORD RtmRegisterEntity(
  [in]  PRTM_ENTITY_INFO           RtmEntityInfo,
  [in]  PRTM_ENTITY_EXPORT_METHODS ExportMethods,
  [in]  RTM_EVENT_CALLBACK         EventCallback,
  [in]  BOOL                       ReserveOpaquePointer,
  [out] PRTM_REGN_PROFILE          RtmRegProfile,
  [out] PRTM_ENTITY_HANDLE         RtmRegHandle
);

Parameters

[in] RtmEntityInfo

Pointer to an RTM_ENTITY_INFO structure. This structure contains information that identifies the client to the routing table manager, such as the routing table manager instance and address family with which to register.

[in] ExportMethods

Pointer to a RTM_ENTITY_EXPORT_METHODS structure that contains a list of methods exported by the client. This parameter is optional and can be set to NULL if the calling client has no methods to export.

[in] EventCallback

A RTM_EVENT_CALLBACK structure that specifies the callback the routing table manager uses to notify the client of events. The events are when a client registers and unregisters, when routes expire, and when changes to the best route to a destination have occurred. Only those changes specified when the client called RtmRegisterForChangeNotification.

[in] ReserveOpaquePointer

Specifies whether to reserve an opaque pointer in each destination for this instance of the protocol. Specify TRUE to reserve an opaque pointer in each destination. Specify FALSE to skip this action. These opaque pointers can be used to point to a private, protocol-specific context for each destination.

[out] RtmRegProfile

On input, RtmRegProfile is a pointer to an RTM_REGN_PROFILE structure.

On output, RtmRegProfile is filled with the requested registration profile structure. The client must use the information returned in other function calls (information returned includes the number of equal-cost next hops and the maximum number of items returned by an enumeration function call).

[out] RtmRegHandle

Receives a registration handle for the client. This handle must be used in all subsequent calls to the routing table manager.

Return value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value	Meaning
ERROR_ALREADY_EXISTS	The specified client has already registered with the routing table manager.
ERROR_BAD_CONFIGURATION	Registry information for the routing table manager is corrupt.
ERROR_FILE_NOT_FOUND	Registry information for the routing table manager was not found.
ERROR_INVALID_DATA	A parameter contains incorrect information.
ERROR_INVALID_PARAMETER	A parameter contains incorrect information.
ERROR_NO_SYSTEM_RESOURCES	There are not enough available system resources to complete this operation.
ERROR_NOT_ENOUGH_MEMORY	There is not enough memory to complete this operation.

Remarks

For sample code using this function, see Register With the Routing Table Manager.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	rtmv2.h
Library	Rtm.lib
DLL	Rtm.dll