3.2.5.2.7.1 INtmsObjectManagement2::EnumerateNtmsObjectR (Opnum 12)
The EnumerateNtmsObjectR method enumerates the objects of the container specified by lpContainerId.
-
HRESULT EnumerateNtmsObjectR( [in, unique] const LPNTMS_GUID lpContainerId, [out, size_is(*lpdwListBufferSize), length_is(*lpdwListSize)] LPNTMS_GUID lpList, [in] DWORD* lpdwListBufferSize, [out] DWORD* lpdwListSize, [out] DWORD* lpdwOutputSize, [in] DWORD dwType, [in] DWORD dwOptions );
lpContainerId: A pointer to the identifier of the container for which to enumerate objects. If this parameter is set to NULL, top-level objects MUST be enumerated.
-
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 identifiers for the objects of lpContainerId.
lpdwListBufferSize: A pointer to the size, in bytes, of the lpList buffer.
lpdwListSize: A pointer to the number of elements in lpList.
lpdwOutputSize: A pointer to the required size of the lpdwListSize parameter if more data need to be returned than can fit in the lpList buffer. In such a case, lpdwListSize MUST be set to 0.
dwType: A value from the NtmsObjectsTypes (section 2.2.1.6) enumeration specifying the type of the container.
dwOptions: Enumeration options. This is applicable only when dwType is NTMS_MEDIA_POOL; if dwType is not NTMS_MEDIA_POOL, this MUST be set to NTMS_ENUM_DEFAULT
-
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 parameter is NULL or invalid.
0x800710D8
ERROR_OBJECT_NOT_FOUND
The lpContainerId parameter is invalid.
0x8007007A
ERROR_INSUFFICIENT_BUFFER
The specified buffer size is too small. The required size is returned in the lpdwOutputSize parameter.
Upon receiving this message, the server MUST verify that lpdwListSize is not NULL. If it is NULL, 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, and get the object type code from the RSM object type. If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005).
The server behavior depends upon the value of dwOptions.
|
Value |
Meaning |
|---|---|
|
NTMS_ENUM_DEFAULT 0x00000000 |
Do not include enumeration of the root pool when enumerating the media pools. |
|
NTMS_ENUM_ROOTPOOL 0x00000001 |
Enumerates the root pool, in addition to all other top-level media pools. The root pool MUST be returned as the first GUID in the list. Enumerating the root pool is only required to get or set the security attributes on the object. dwType MUST be NTMS_MEDIA_POOL and lpContainerId MUST be NULL. |
If the total size of available object IDs is greater than the current buffer size, the server MUST return ERROR_INSUFFICIENT_BUFFER (0x0000007A) and set lpdwOutputSize to the required size and set lpdwListSize to 0. The client can then allocate a larger buffer and try again.
Since an ID can be added by another process, it is possible for a subsequent method with a resized list to get an error indicating that the list is too small. If the lpContainerId parameter is set to NULL, RSM 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.