3.2.5.2.7.2 INtmsObjectManagement2::GetNtmsUIOptionsA (Opnum 13)

  • Article

The GetNtmsUIOptionsA method enumerates the list of computer names to which the specified type of UI is being directed for an object, with strings encoded using ASCII.

 HRESULT GetNtmsUIOptionsA(
   [in, unique] const LPNTMS_GUID lpObjectId,
   [in] DWORD dwType,
   [out, size_is(*lpdwBufSize), length_is(*lpdwDataSize)] 
     unsigned  char* 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 NtmsUITypes (section 2.2.5.2) enumeration specifying the type of UI messages to enumerate.

lpszDestination: A buffer of null-terminated 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 MUST be set to 0.

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

0x80070057

ERROR_INVALID_PARAMETER

The 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 of 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 given object.

  •  Return this list to the client.

If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005). 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 ASCII-encoded.