RtmGetEnumDests function (rtmv2.h)

Article
02/22/2024

The RtmGetEnumDests function retrieves the next set of destinations in the specified enumeration.

Syntax

DWORD RtmGetEnumDests(
  [in]      RTM_ENTITY_HANDLE RtmRegHandle,
  [in]      RTM_ENUM_HANDLE   EnumHandle,
  [in, out] PUINT             NumDests,
  [out]     PRTM_DEST_INFO    DestInfos
);

Parameters

[in] RtmRegHandle

Handle to the client obtained from a previous call to RtmRegisterEntity.

[in] EnumHandle

Handle to the destination enumeration.

[in, out] NumDests

On input, NumDests is a pointer to a UINT value specifying the maximum number of destinations that can be received by DestInfos. On output, NumDests receives the actual number of destinations received by DestInfos.

[out] DestInfos

On input, DestInfos is a pointer to an RTM_DEST_INFO structure.

On output, DestInfos receives an array of handles to destinations.

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_INVALID_PARAMETER	The value pointed to by NumRoutes is larger than the maximum number of routes a client is allowed to retrieve with one call. Check RTM_REGN_PROFILE for the maximum number of destinations that the client is allowed to retrieve with one call.
ERROR_NO_MORE_ITEMS	There are no more destinations to enumerate.

Remarks

The structure pointed to by DestInfos is a variable-sized structure. If the client specifies more than one view with TargetViews, the size of DestInfos increases for each view. Use the RTM_SIZE_OF_DEST_INFO macro to determine how large a DestInfos structure to allocate before calling this function. Use the value specified for TargetViews as a parameter to RTM_SIZE_OF_DEST_INFO.

When the destinations are no longer required, release them by calling RtmReleaseDests.

For sample code using this function, see Enumerate All Destinations.

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