3.2.5.2.7.3 INtmsObjectManagement2::GetNtmsUIOptionsW (Opnum 14)

  • Article

The GetNtmsUIOptionsW method enumerates the list of computer names to which the specified type of UI is being directed for an object. This method encodes strings using Unicode.

 HRESULT GetNtmsUIOptionsW(
   [in, unique] const LPNTMS_GUID lpObjectId,
   [in] DWORD dwType,
   [out, size_is(*lpdwBufSize), length_is(*lpdwDataSize)] 
     wchar_t* lpszDestination,
   [in] DWORD* lpdwBufSize,
   [out] DWORD* lpdwDataSize,
   [out] DWORD* lpdwOutSize
 );

lpObjectId: A pointer to the identifier of a computer or library whose UI is being redirected. To choose all events for this session, set this parameter to NULL.

dwType: A value from the NtmsUIType (section 2.2.5.2) enumeration specifying the type of UI messages to enumerate.

lpszDestination: A buffer of null-terminated Unicode characters denoting destinations, with the buffer terminated by two null characters.

lpdwBufSize: A pointer to the size, in bytes, of lpszDestination.

lpdwDataSize: A pointer to the number of strings in lpszDestination.

lpdwOutSize: A pointer to the required size of the lpdwDataSize parameter if more data needs to be returned than can fit in lpszDestination. In such a case, lpdwDataSize is set to 0.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070005

ERROR_ACCESS_DENIED

Access to an object is denied.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

An allocation failure occurred during processing.

0x80070057

ERROR_INVALID_PARAMETER

A parameter is not valid.

0x8007007A

ERROR_INSUFFICIENT_BUFFER

The specified buffer size is not large enough.

0x800710D8

ERROR_OBJECT_NOT_FOUND

The object was not found.

Upon receiving this message, the server MUST verify that lpszDestination is not NULL, verify that dwType is not equal to NTMS_UITYPE_INVALID, and verify that dwType is not equal to or greater than NTMS_UITYPE_MAX. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

If parameter validation succeeds, the server MUST perform the following actions:

  • Ensure that the client has READ permissions on the object.

  •  Validate the object container.

  •  Allocate a large enough buffer to hold all the destinations.

  •  Traverse through all the available destinations and generate the list of machine names to which the specified type of UI is being directed for the specified object.

  •  Return this list to the client.

If the client does not have the required access rights, NTMS_MODIFY_ACCESS to the library is denied and the server MUST return ERROR_ACCESS_DENIED (0x80070005). Other security errors are possible but indicate a security subsystem error. If the buffer size specified by lpdwBufSize is too small, the server MUST return ERROR_INSUFFICIENT_BUFFER (0x8007007A) with lpdwOutSize set to the required size.

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