EnumerateNtmsObject

[This is preliminary documentation and subject to change.]

The EnumerateNtmsObject function enumerates the RSM objects contained in the lpContainerId parameter.

DWORD WINAPI EnumerateNtmsObject(
  HANDLE hSession, 
  LPNTMS_GUID lpContainerId,
  LPNTMS_GUID lpList,
  LPDWORD lpdwListSize,
  DWORD dwType,
  DWORD dwOptions
);
 

Parameters

hSession

Handle to the session returned by the OpenNtmsSession function.

lpContainerId

Specifies the unique identifier of the RSM object container. The type of object identified depends on the type of object being requested. Can be set to Library, Media Pool, Partition ID, Physical Media, Logical Media, or NULL. Set this parameter to NULL to enumerate all objects of the type specified by the dwType parameter.

lpList

Buffer for the array of libraries, drives, media or other RSM object IDs.

lLpdwListSize

Pointer to a DWORD that specifies the maximum number of IDs the function can return through the lpList parameter. At return time, the number of IDs in lpList is returned in lpdwListSizeA

dwType

Specifies the type of objects that you are enumerating in the container. This parameter can be one of the following values.

Value	Meaning
NTMS_CHANGER	Lists changers contained in the library specified by the lpContainerId parameter or all the changers supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_DRIVE	Lists drives contained in a specific library specified by the lpContainerId parameter or all the drives supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_CHANGER_TYPE	Lists changer types supported by RSM. The lpContainerId parameter must be NULL.
NTMS_COMPUTER	Specifies the current computer object. The lpContainerId parameter must be NULL.
NTMS_DRIVE_TYPE	Lists drive types supported by RSM. The lpContainerId parameter must be NULL.
NTMS_IEDOOR	Lists access doors contained in a library specified by the lpContainerId parameter or all the doors supported by RSM if a NULL container ID is specified. Available when lpContainerID is set to NULL or Library.
NTMS_IEPORT	Lists insert/eject ports contained in a library specified by the lpContainerId parameter or all the insert/eject ports supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_LIBRARY	Lists the library objects. These include the physical library units and the offline library. The lpContainerId parameter must be NULL.
NTMS_LIBREQUEST	Lists library active requests (or work items) queued to the library specified by the lpContainerId parameter or all the library work items queued within RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_LOGICAL_MEDIA	Specifies a logical media object. This is a medium allocated to an application that might contain more than one partition or piece of physical media. Available when lpContainerID is set to NULL, Media Pool, or Partition ID.
NTMS_MEDIA_POOL	Specifies a media pool object that contains logical and/or physical media, and configuration parameters to manage them. If NULL is specified as a container ID, only the top-level names are returned. Available when lpContainerID is set to NULL or Media Pool.
NTMS_MEDIA_TYPE	Specifies a media type object that contains the attributes of a type of medium that is supported by RSM. Enumerating with a NULL will give all possible media types, not just those available on the current server. Available when lpContainerID is set to NULL or Library.
NTMS_OPREQUEST	Lists operator requests that are on this RSM server. The lpContainerId parameter must be NULL.
NTMS_PARTITION	Specifies a partition on a piece of physical media. The piece of physical media can contain multiple physical partitions (for example, an optical disk contains two sides). Available when lpContainerID is set to NULL, Physical Media, Logical Media, or Media Pool.
NTMS_PHYSICAL_MEDIA	Specifies a piece of physical media (a tape, optical disk, CD-ROM, or magnetic cartridge). A piece of physical media can contain multiple physical partitions (for example, sides of an optical disk). The container ID contains NULL to get all the physical media, a media pool, logical media, or a library. Available when lpContainerID is set to NULL, Media Pool, or Library
NTMS_STORAGESLOT	Lists media slots contained in a library specified by the lpContainerId parameter or all the storage slots supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.

dwOptions

Option flags. Reserved and must be set to 0.

Return Values

ERROR_INVALID_PARAMETER

The list-size pointer is missing or the object type is invalid.

ERROR_INSUFFICIENT_BUFFER

The buffer provided is too small to return all the entries available. The list is truncated and the actual size is returned in lpdwListSize.

ERROR_INVALID_HANDLE

The session handle is invalid or missing.

ERROR_NOT_ENOUGH_MEMORY

An allocation failure occurred during processing.

ERROR_OBJECT_NOT_FOUND

No objects match the search criteria.

ERROR_SUCCESS

The function was successful.

Remarks

Security functions are also available to get and set specific access rights on RSM objects.

If the available number of IDs specified in the lpdwListSize parameter is greater than the current buffer size, lpdwListSize returns the number of IDs required. The application should then allocate a larger buffer and try again.

Since it is possible for IDs to be added by another process, it is possible for a subsequent function with a resized list to get an error indicating that the list is too small. To avoid this, specify a list in the lpdwListSize parameter that is slightly larger than the required length.

If the lpContainerId parameter is set to NULL, RSM enumerates top-level objects (such as libraries).

If more than one object is listed, the object may be enumerated from more than one container. The NULL container is the highest-level container and enumerates all objects in a system. For example, you can enumerate media in a particular library or all media in the system.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in ntmsapi.h.
  Import Library: Use ntmsapi.lib.

See Also

Object Management Functions, CreateNtmsMediaPool, GetNtmsObjectInformation, SetNtmsObjectInformation