3.2.5.2.2.9 INtmsMediaServices1::CreateNtmsMediaPoolA (Opnum 12)

The CreateNtmsMediaPoolA method creates a new application media pool, with strings encoded using ASCII.

 HRESULT CreateNtmsMediaPoolA(
   [in, string] const char* 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 ASCII characters that constitute the name of the new media pool; MUST be unique among all the media pool 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 that specifies the type of creation to undertake.

lpSecurityAttributes: A pointer to an optional SECURITY_ATTRIBUTES_NTMS structure that is 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 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.

When the server receives this message, it MUST verify that lpPoolName, lpMediaType, lpPoolId, and lpSecurityAttributes are not NULL. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

If lpSecurityAttributes is not NULL, the server MUST verify that the SECURITY_ATTRIBUTES_NTMS structure is valid. If validation fails, the server MUST return ERROR_INVALID_PARAMENTER (0x800750057) else the server MUST restrict access to the pool as per client input.

If parameter validation succeeds, the server MUST verify that the user has the required access rights, and check if 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 that is specified by lpPoolName is present, and if dwOptions is not NTMS_CREATE_NEW, the server MUST open the existing media pool and return success.

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

If the media pool that is 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 creates a new pool under the parent pool, opens the newly created media pool, and return success (S_OK).

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 that are sent to this method as parameters MUST be ASCII-encoded.