3.1.4.1 LnkSvrMessage (Opnum 0)
The LnkSvrMessage method provides a way to send and receive messages to the DLT Central Manager server to query or update information.
-
HRESULT LnkSvrMessage( [in] handle_t IDL_handle, [in, out] TRKSVR_MESSAGE_UNION* pMsg );
IDL_handle: For information about the handle_t data type, see [MS-DTYP] section 2.1.3.
pMsg: Pointer to a message, in the format of a TRKSVR_MESSAGE_UNION structure. If this method fails, as indicated by a failure return value, the client MUST ignore any changes made by the server to this structure.
Return Values: See the following table and the explanation after it for more information on return values.
Exceptions Thrown: None.
The following table contains failure and success return values that have special behavior in this protocol. All failure values not listed in this table MUST be treated identically. Similarly, all success values not listed in this table MUST be treated identically. Except where otherwise stated, a return value MUST NOT be a value from this table. Except where otherwise specified, the server MUST return a success value.
|
Constant/value |
Description |
|---|---|
|
TRK_E_NOT_FOUND 0x8DEAD01B |
A requested object was not found. |
|
TRK_E_VOLUME_QUOTA_EXCEEDED 0x8DEAD01C |
The server received a CREATE_VOLUME subrequest of a SYNC_VOLUMES request, but the ServerVolumeTable size limit for the RequestMachine value has already been reached. |
|
TRK_E_SERVER_TOO_BUSY 0x8DEAD01E |
The server is busy, and the client is to retry the request at a later time. |
|
TRK_S_OUT_OF_SYNC 0x0DEAD100 |
The VolumeSequenceNumber of a MOVE_NOTIFICATION request is incorrect. See section 3.1.4.2. |
|
TRK_S_VOLUME_NOT_FOUND 0x0DEAD102 |
The VolumeID in a request was not found in the server's ServerVolumeTable. |
|
TRK_S_VOLUME_NOT_OWNED 0x0DEAD103 |
A notification was sent to the LnkSvrMessage method, but the RequestMachine for the request was not the VolumeOwner for a VolumeID in the request. |
|
TRK_S_NOTIFICATION_QUOTA_EXCEEDED 0x0DEAD107 |
The server received a MOVE_NOTIFICATION request, but the FileTable size limit has already been reached. |
The LnkSvrMessage method has only a single parameter, a union of type TRKSVR_MESSAGE_UNION (see section 2.2.12). But that union is defined to hold one of several types of requests, referred to in this protocol specification as messages. The message type for a given request is specified in the MessageType field of the TRKSVR_MESSAGE_UNION. The possible message types are defined in section 2.2.11. The formats of the different messages are defined in the sub-sections of section 2.2.12. The responses by the server to those different messages are specified in the remaining subsections of section 3.1.4, according to the MessageType field of the union.
Except where otherwise noted, the server that receives a request MUST ignore and leave unmodified all fields in the TRKSVR_MESSAGE_UNION structure of the pMsg parameter, as well as the structures referenced by the MessageUnion field of the TRKSVR_MESSAGE_UNION.
For security purposes, the server SHOULD restrict access to clients that are members of the authenticated users built-in security group. The client's identity is determined as described in [MS-RPCE], section 3.3.3.4.3.<4>
The TRKSVR_MESSAGE_UNION structure of the pMsg parameter contains a Priority field. The server MAY use this value to decide to reject some requests with a TRK_E_SERVER_TOO_BUSY return value, but it MUST NOT use this value to change the ordering of processing of messages from a caller.<5>
In this processing of this method call, the MachineID of the client that makes the request MUST be used as the RequestMachine value.<6>
Note During the processing of a LnkSvrMessage call, the server can call back to the client by using the LnkSvrMessageCallback method. See sections 3.1.4.4 and 3.2.4.1 for more information.