CreateNtmsMediaPool

[This is preliminary documentation and subject to change.]

The CreateNtmsMediaPool function creates a new application media pool.

DWORD WINAPI CreateNtmsMediaPool(
  HANDLE hSession, 
  LPCTSTR lpPoolName,
  LPNTMS_GUID lpMediaType,
  DWORD dwAction,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  LPNTMS_GUID lpPoolId
);
 

Parameters

hSession

Handle to the session returned by the OpenNtmsSession function.

lpPoolName

Specifies the name of the new media pool. Media pool names must be unique within the scope of a single RSM database.

lpMediaType

Specifies the type of media in this media pool. Use the EnumerateNtmsObject function to get a list of available media types and their attributes. The application can pass a NULL pointer to create a media pool that only contains other media pools.

dwAction

This parameter must be one of the following values.

Value	Meaning
NTMS_OPEN_EXISTING	Opens an existing media pool by name. Returns ERROR_INVALID_PARAMETER if the pool does not exist.
NTMS_OPEN_ALWAYS	Opens an existing media pool or creates the pool if it does not exist.
NTMS_CREATE_NEW	Creates a new media pool. Returns ERROR_ALREADY_EXISTS if the pool exists.

lpSecurityAttributes

Optional. Specifies the security descriptor used to restrict access to the pool.

lpPoolId

Pointer to the unique identifier where the media pool ID is returned after the media pool is successfully created or opened.

Return Values

ERROR_ACCESS_DENIED

NTMS_MODIFY_ACCESS to the parent media pool is denied while trying to create a new media pool.

ERROR_ALREADY_EXISTS

Unable to create a new media pool because one already exists with this name.

ERROR_DATABASE_FAILURE

The database is inaccessible or damaged.

ERROR_DATABASE_FULL

The database is full. Other security errors are also possible, but they would indicate a security subsystem error.

ERROR_INVALID_HANDLE

The session handle is invalid or missing.

ERROR_INVALID_MEDIA

The selected media type is not valid.

ERROR_INVALID_NAME

The pool name syntax is invalid. (The name is too long.)

ERROR_INVALID_PARAMETER

The media pool name or media pool ID pointer is missing.

ERROR_OBJECT_NOT_FOUND

Unable to open existing media pool.

ERROR_SUCCESS

The function was successful.

Remarks

Scratch, Foreign, and Import media pools are created by RSM and cannot be created with the CreateNtmsMediaPool function.

RSM media pools are organized as a hierarchy separated by the "\" character. The Application, Scratch, Foreign, and Import media pools exist at the root of the hierarchy. RSM creates and manages the Scratch, Foreign, and Import pools. RSM creates a Scratch media pool for each media type available.

Application-specific media pools are created by applications. Applications create media pools for their own use under the root application pool. These media pools have file system-like names. Only the end-point of the name contains media and policy. An application can define pools such as \MyApp\Pool1 and \MyApp\Pool2. This conveys the hierarchy to the user interface and avoids duplicate names. Each pool level must be created individually; first MyApp and then Pool1 and Pool2, much like folders and files.

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

Media Services Functions, AllocateNtmsMedia, DeleteNtmsMediaPool, GetNtmsObjectSecurity, SetNtmsObjectSecurity