3.2.5.2.2.10 INtmsMediaServices1::CreateNtmsMediaPoolW (Opnum 13)

The CreateNtmsMediaPoolW method creates a new application media pool whose name is composed of a sequence of Unicode characters.

 HRESULT CreateNtmsMediaPoolW(
   [in, string] const wchar_t* lpPoolName,
   [in, unique] LPNTMS_GUID lpMediaType,
   [in] DWORD dwOptions,
   [in, unique] LPSECURITY_ATTRIBUTES_NTMS lpSecurityAttributes,
   [out] LPNTMS_GUID lpPoolId
 );

lpPoolName: A null-terminated sequence of Unicode characters, encoded using UTF-16, that constitute the name of the new media pool; MUST be unique among all the media pools present in the server.

lpMediaType: Pointer to a unique identifier for the type of media in this media pool. INtmsObjectManagement1::EnumerateNtmsObject produces a list of available media types and their attributes. Use of a NULL pointer creates a media pool that contains only other media pools.

dwOptions: A value from the NtmsCreateOptions (section 2.2.3.2) enumeration specifying the type of creation to undertake.

lpSecurityAttributes: A pointer to an optional SECURITY_ATTRIBUTES_NTMS (section 2.2.3.5) structure used to restrict access to the pool.

lpPoolId: A pointer to the identifier of the new media pool.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070005

ERROR_ACCESS_DENIED

NTMS_MODIFY_ACCESS to the library is denied; other security errors are possible, but indicate a security subsystem error.

0x80070057

ERROR_INVALID_PARAMETER

The media pool name or identifier is missing.

0x8007007B

ERROR_INVALID_NAME

The pool name syntax is invalid or the name is too long.

0x800700B7

ERROR_ALREADY_EXISTS

A new media pool could not be created because one already exists with this name.

0x800710CC

ERROR_INVALID_MEDIA

The selected media type is not valid.

0x800710D8

ERROR_OBJECT_NOT_FOUND

Unable to open an existing media pool.

0x800710D9

ERROR_DATABASE_FAILURE

The database is inaccessible or damaged.

0x800710DA

ERROR_DATABASE_FULL

The database is full; other security errors are possible, but indicate a security subsystem error.

Upon receiving this message, the server MUST verify that lpPoolName, lpMediaType, and lpPoolId are 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, and check whether lpPoolName is present. If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005).

If the media pool specified by lpPoolName is present, and dwOptions is not set to NTMS_CREATE_NEW, the server MUST open the existing media pool and return success.

If the media pool specified by lpPoolName is present, and dwOptions is set to NTMS_CREATE_NEW, the server MUST return ERROR_ALREADY_EXISTS (0x800700B7).

If the media pool specified by lpPoolName is not present, and the parent media pool of lpPoolName is also not present, the server MUST return ERROR_OBJECT_NOT_FOUND (0x800710D8).

If the media Pool that is specified by lpPoolName is not present, and the parent media pool of lpPoolName is present, the server MUST create a new pool under the parent pool, open the newly created media pool, and return success.

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 names like those of file systems. Only the endpoint 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; for example, first MyApp and then Pool1 and Pool2, in much the same way as folders and files.

Strings sent to this method as parameters MUST be Unicode-encoded.