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.