3.2.5.2.9.2 IRobustNtmsMediaServices1::GetNtmsMediaPoolNameWR (Opnum 22)

  • Article

The GetNtmsMediaPoolNameWR method retrieves the full name hierarchy of a media pool, with strings encoded using Unicode.

 HRESULT GetNtmsMediaPoolNameWR(
   [in] LPNTMS_GUID lpPoolId,
   [out, size_is(*lpdwNameSizeBuf), length_is(*lpdwNameSize)] 
     wchar_t* lpBufName,
   [in] DWORD* lpdwNameSizeBuf,
   [out] DWORD* lpdwNameSize,
   [out] DWORD* lpdwOutputSize
 );

lpPoolId: A pointer to the identifier of the media pool for which to retrieve the name.

lpBufName: The null-terminated buffer that contains the name of the media pool.

lpdwNameSizeBuf: A pointer to the size, in bytes, of lpBufName.

lpdwNameSize: A pointer to the length of the string in lpBufName, including the terminating null character.

lpdwOutputSize: A pointer to the buffer size required to return the name.

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 error occurred during processing.

0x80070057

ERROR_INVALID_PARAMETER

The parameter is missing or invalid.

0x8007007A

ERROR_INSUFFICIENT_BUFFER

The specified buffer size is too small. The required size is returned in lpdwOutputSize.

0x800710CE

ERROR_INVALID_MEDIA_POOL

The media pool identifier is missing or invalid.

Upon receiving this message, the server MUST:

  • Verify that lpPoolId is not NULL.

  • Verify that lpdwNameSize is not NULL.

  • Verify that lpBufName is not NULL.

  • Verify that lpdwOutputSize is not NULL.

If parameter validation fails, the server MUST fail the operation immediately and return ERROR_INVALID_PARAMETER (0x80070057).

If parameter validation succeeds, the server MUST verify that the user has the required access rights, retrieve all the name hierarchy for the given media pool, and return it to the caller in the buffer lpBufName. If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005).

If the output data size is bigger than the size of the buffer pointed to by lpBufName, the server MUST copy the required buffer size in lpdwOutputSize and return ERROR_INSUFFICIENT_BUFFER (0x8007007A). Otherwise, the server MUST copy the name hierarchy in the lpBufName and return this to the user.

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