3.2.5.2.4.7 INtmsObjectManagement1::EnumerateNtmsObject (Opnum 9)

  • Article

The EnumerateNtmsObject method enumerates the objects of the container specified by the lpContainerId parameter.

 HRESULT EnumerateNtmsObject(
   [in, unique] const LPNTMS_GUID lpContainerId,
   [out, size_is(*lpdwListBufferSize), length_is(*lpdwListBufferSize)] 
     LPNTMS_GUID lpList,
   [in] DWORD* lpdwListBufferSize,
   [out] DWORD* lpdwListSize,
   [in] DWORD dwType,
   [in] DWORD dwOptions
 );

lpContainerId: A pointer to the GUID of the container for which to enumerate objects; can be set to NULL to enumerate all objects of type dwType.

If the lpContainerId parameter is set to NULL, the server MUST enumerate top-level objects (such as libraries). If more than one object is listed, the object can be enumerated from more than one container. The NULL container is the highest-level container, and enumerates all objects in a system. lpContainerId can be an object identifier (for example, a library identifier) which would return the objects associated with it, depending on the type of object chosen in the dwType parameter.

lpList: An array of object identifiers.

lpdwListBufferSize: A pointer to the size, in bytes, of lpList.

lpdwListSize: A pointer to the number of elements in lpList.

dwType: A value from the NtmsObjectsTypes (section 2.2.1.6) enumeration specifying the type of the object.

dwOptions: This parameter is unused. It MUST be 0 and MUST be ignored on receipt.

Return value/code

Description

0x00000000

S_OK

 The call was successful.

0x80070005

ERROR_ACCESS_DENIED

Access to an object was denied.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

 An allocation failure occurred during processing.

0x80070057

ERROR_INVALID_PARAMETER

 The lpdwListSize pointer is NULL, or lpContainerId is not of the object type specified by dwType.

0x8007007A

ERROR_INSUFFICIENT_BUFFER

 The specified buffer size is too small. The required size is returned in the lpdwListSize parameter.

0x800710D8

ERROR_OBJECT_NOT_FOUND

 The lpContainerId is not the identifier of any container in the database.

Upon receiving this message, the server MUST verify that lpdwListSize is not NULL. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

If parameter validation succeeds, the server MUST verify that the user has the required access rights. If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005).

If the available number of IDs specified in the lpdwListSize parameter is greater than the current buffer size, lpdwListSize MUST return the required size in lpdwListSize and ERROR_INSUFFICIENT_BUFFER (0x8007007A). The client MUST then allocate a larger buffer and try again.

If the lpContainerId parameter is set to NULL, the server MUST enumerate top-level objects (such as libraries).

If more than one object is listed, the object can be enumerated from more than one container. The NULL container is the highest-level container, and enumerates all objects in a system.