SetNtmsUIOptionsA function (ntmsapi.h)

  • Article

[Removable Storage Manager is no longer available as of Windows 7 and Windows Server 2008 R2.]

The SetNtmsUIOptions function modifies the list of computer names to which the specified type of UI is being directed for the given object.

Syntax

DWORD SetNtmsUIOptionsA(
  [in]  HANDLE            hSession,
  [in]  const LPNTMS_GUID lpObjectId,
  [in]  DWORD             dwType,
  [in]  DWORD             dwOperation,
  [out] LPCSTR            lpszDestination
);

Parameters

[in] hSession

Handle to the session returned by the OpenNtmsSession function.

[in] lpObjectId

Unique identifier of the object whose UI is being redirected. The object must be a container that can be a source for events. The object can be either be an application (a mount request triggered by the application), a library (a door open request in response to an eject) or a computer (all UI pertaining to the computer).

To specify the computer container set the lpObjectId pointer to point to a buffer with the Removable Storage Manager's computer object GUID. To specify a particular library set it to point to a buffer with the library's GUID. To specify an application, pass in a NULL pointer. The identity of the application is determined by the session used in hSession. Note that an application can have multiple sessions open simultaneously. In this case, the value set applies only to the hSession session. In the case of a library or computer instance, settings persist until explicitly changed. Application rows are deleted when the session is closed.

[in] dwType

This parameter can have one of the following values.

Value Meaning
NTMS_UITYPE_INFO
 UI messages that provide information. These include the work queue items that indicate progress. For example, mount requests.
NTMS_UITYPE_REQ
 UI messages that are requests. These include the operator requests that handle media. For example, a request to inject new media.
NTMS_UITYPE_ERR
 UI messages that give error information. These include operator requests that are related to error notification. For example, a request to clean the drive.

[in] dwOperation

This parameter can have one of the following values.

Value Meaning
NTMS_UIDEST_ADD
 Add a new destination (computer name) to the list.
NTMS_UIDEST_DELETE
 Remove a destination from the list.
NTMS_UIDEST_DELETEALL
 Clear all destinations from the list. No UI for the object is generated. In this case, the destination argument is ignored.

[out] lpszDestination

Multi-string that returns the names of the computers to which the UI is being redirected. This parameter cannot be NULL.

Return value

This function returns one of the following values.

Value Meaning
ERROR_ACCESS_DENIED
 Access to one or more RSM objects is denied.
ERROR_ALREADY_EXISTS
 The given destination already exists in the list.
ERROR_INVALID_HANDLE
 The session handle is missing or is not valid.
ERROR_INVALID_PARAMETER
 lpdwSize or lpszDestination pointer is NULL, or lpObjectId is not a valid container, or dwType or dwOperation is not one of the three valid values.
ERROR_NOT_ENOUGH_MEMORY
 An allocation failure occurred during processing.
ERROR_OBJECT_NOT_FOUND
 The GUID specified by lpObjectId is not the GUID of any computer or library object in the database.
ERROR_SUCCESS
 The function was successful.

Remarks

A call to SetNtmsUIOptions adds or removes a destination for a particular instance determined by the lpObjectId and dwType parameters.

  NTMS_UITYPE_INFO NTMS_UITYPE_REQ NTMS_UITYPE_ERR
Application Display work item progress UI for work items generated by this application. Display operator request UI for operator requests generated by actions taken by this application. Undefined. Applications cannot cause this sort of error event.
Library Display work item progress UI for work items associated with this library. Display UI for requests associated with this library. Display UI for errors associated with this library.
Computer Display informational UI in this instance of RSM running on this machine. Display a request-type UI in this instance of RSM. Display error-type UI in this instance of RSM.
 

Note that security checks are performed when calling SetNtmsUIOptions. When the computer object is specified you are required to have access with permission to modify the computer. When modifying a library's UI element you are required to have access with permission to modify the library object.

Note that there is no checking of destination strings. A call to with a destination name that's not a computer reachable from the computer on which SetNtmsUIOptions called returns success. A pointer to an empty string is taken to mean the local machine.

Note

The ntmsapi.h header defines SetNtmsUIOptions as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header ntmsapi.h
Library Ntmsapi.lib
DLL Ntmsapi.dll

See also

GetNtmsUIOptions

Library Control Functions