3.2.5.2.5.4 INtmsSession1::SubmitNtmsOperatorRequestW (Opnum 6)

The SubmitNtmsOperatorRequestW method submits an operator request, with strings encoded using Unicode.

 HRESULT SubmitNtmsOperatorRequestW(
   [in] DWORD dwRequest,
   [in, string, unique] const wchar_t* lpMessage,
   [in, unique] LPNTMS_GUID lpArg1Id,
   [in, unique] LPNTMS_GUID lpArg2Id,
   [out] LPNTMS_GUID lpRequestId
 );

dwRequest: A value from the NtmsOpreqCommand (section 2.2.1.7) enumeration specifying the type of operation requested. If dwRequest is set to NTMS_OPREQ_UNKNOWN, the server MUST return ERROR_INVALID_PARAMETER and take no action.

lpMessage: An optional null-terminated message string to send to the user.

lpArg1Id: This parameter MUST be set according to the value of dwRequest.

Value of dwRequest	lpArg1Id
NTMS_OPREQ_NEWMEDIA 0x00000001	MUST be set to a pointer to the identifier of the media pool from which to retrieve the new media.
NTMS_OPREQ_CLEANER 0x00000002	Must be set to the pointer to the identifier of the device (library or slot).
NTMS_OPREQ_DEVICESERVICE 0x00000003	MUST be set to a pointer to the identifier of the device that needs service.
NTMS_OPREQ_MOVEMEDIA 0x00000004	MUST be set to a pointer to the identifier of the piece of physical media to move.
NTMS_OPREQ_MESSAGE 0x00000005	MUST be set to NULL.

lpArg2Id: This parameter MUST be set according to the value of dwRequest.

Value of dwRequest	lpArg2Id
NTMS_OPREQ_NEWMEDIA 0x00000001	MUST be set to a pointer to the identifier of the media library to which the new media MUST be added.
NTMS_OPREQ_CLEANER 0x00000002	MUST be set to NULL.
NTMS_OPREQ_DEVICESERVICE 0x00000003	MUST be set to NULL.
NTMS_OPREQ_MOVEMEDIA 0x00000004	MUST be set to a pointer to the identifier of the target library to which the media MUST be moved.
NTMS_OPREQ_MESSAGE 0x00000005	MUST be set to NULL.

lpRequestId: A pointer to the identifier of the created operator request.

Return value/code	Description
0x00000000 S_OK	The call was successful.
0x80070005 ERROR_ACCESS_DENIED	Access to one or more objects is denied.
0x80070057 ERROR_INVALID_PARAMETER	An invalid parameter was found.
0x800708CA ERROR_NOT_CONNECTED	Unable to connect to the service.
0x800710D8 ERROR_OBJECT_NOT_FOUND	Unable to find the source or destination object.
0x800710D9 ERROR_DATABASE_FAILURE	The database query or update failed.

The SubmitNtmsOperatorRequestW method submits an operator request, and returns the status of the request (Satisfied or Canceled), or times out (if the operator does not act upon the request). Operator requests are used to request media, to request that the specified medium be moved from one library to another, or to request the server device service.

Upon receiving this message, the server MUST verify that lpRequestId and lpMessage are not NULL. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

The NTMS_OPEREQ_MESSAGE value (in the dwRequest parameter) is the request type most often used by applications. The server cannot use NTMS_OPEREQ_MESSAGE. RSM uses the other request types as needed.

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