The two main sections of any Agent XML message is the header and the body. The header provides message routing and control information. The body of the message contains the actual request (or response) parameters and data. The packet
element is the root element of every message. Both the header and the body of a message reside within the same parent packet
element.
The following table contains the Agent message header specification, as defined in XML Schema.
Message header specification:
Name |
Min..Max |
Type |
Description |
|
|
|
The root element of an Agent XML message. |
|
|
|
|
|
|
|
User-defined information describing the message, or any other type of information. The data specified here remains unchanged during the request/response operation, i.e. if you put some data into this element in the request message, the response message will contain the same data. |
|
|
|
In request messages, this element must contain the name of the operator to which the request should be sent for processing. Note: When using the The name of the operator is always the same as the name of the corresponding interface that you are using. For example, if you are using a call from the Multiple targets may be specified if you are including multiple calls in a single request. In response messages, this element contains the name of the client that originated the request (the value is generated and used internally by Agent). |
|
|
|
The name of the operator that generated the response. Included in response messages only. |
|
|
|
The source routing information. This field is automatically populated by the director on the server side when a message is routed from the corresponding operator to it. The same information is also duplicated in the |
|
|
|
|
|
|
|
The name of the director to which the target operator belongs. |
|
|
|
The Agent host ID. Used by Agent to determine the host address. Should be either contained in the Agent configuration (global mapping) or be a result of exclusive connect. |
|
|
|
For on-demand operators, specifies a particular target. |
|
|
|
Contains the origin information when a packet is sent remotely. |
|
|
|
|
|
|
|
The destination routing information. In request messages, use this structure to specify the server to which you want to forward the request. For example, if you are sending a request to the Agent on the Hardware Node but would like the request to be processed inside a Virtuozzo Container, specify the Server ID for the Container using the In the response messages, this information is automatically populated by the director on the server side. |
|
|
|
|
|
|
|
The name of the director to which the target operator belongs. Populated automatically by the director. |
|
|
|
Destination Server ID. When using the message forwarding feature, it is used for specifying the ID of the target server. |
|
|
|
For on-demand operators, specifies a particular target. Populated automatically by the director. |
|
|
|
Contains the origin information when a packet is sent remotely. Populated automatically by Agent. |
|
|
|
|
|
|
string |
Session ID. In the request messages, this field is used to specify the session that should be used to process the request. In the response messages, the ID indicates the session that was used to process the request. The session ID is obtained from the response message of the |
} |
|
|
|
The packet
element may optionally contain attributes described in the following table.
Attributes of the <packet> element:
Attribute |
Type |
Description |
|
|
Parallels Agent protocol version number. The current protocol version number is 4.0.0. The older 3.0.3 protocol is also supported in Virtuozzo Containers 4.0. |
|
|
Packet ID. If included in a request message, the response will contain the same ID. This allows the response to be correlated with the original request. The attribute must also be included if you want to be notified in case of the request timeout, or if the packet was dropped on the server side for any reason. As a rule of thumb, you should always include this element in all of your outgoing packets. The value should normally be a string containing an integer value, but it can also contain other characters if needed. |
|
|
Packet priority. Specifies the significance of the message when it is placed into a message queue. The higher the priority value, the less significant the packet is. The value of zero is the default priority. Priorities range from -3000 to 3000. -3000 to -1000 for heavy messages. -999 to 999 for normal messages. 1000 to 3000 for urgent messages. |
|
|
The time when the packet was sent; in the ISO-8601 format: (e.g. "2007-02-04T08:55:51+0000"). |
|
|
Use this attribute to enable the progress reporting for long operations if you would like to receive intermediate results and to keep track of the request processing. Please note that not all operations actually generate progress reports. The possible values are:
When you turn the progress reporting on, you must also include the |
|
|
When present, the automatic progress reporting is logged for the operations supporting it. Switch this to "on" if you're planning to start an operation and disconnect from Agent before the operation is completed. By doing so, you'll be able to reconnect later and check the log files for the results of your operation. The requests marked as Logged Operation in the XML API Reference support this feature. Possible values are:
|
|
|
*** INTERNAL *** Bit field for the internal type of the message. #define UNFINISHED 0x00000001 #define RESPONSE 0x00000002 #define RESCHEDULE 0x00000004 #define TIMEOUT 0x00000008 |
|
|
The timeout value which will be used for handling this request. The value can be specified in the incoming packet or it can be sent back from the operator, notifying the director about the time it is going to handle it. |
|
|
*** INTERNAL *** Timeout limit for message processing. Used by an operator in determining the validity of its timeout. |
|
|
*** INTERNAL *** UID of the user sending this packet. |
Example:
The following is an example of an Agent message header, built according to the specifications above. In a real message, the values of the XML elements would be substituted with the appropriate names, IDs, etc.
<packet version="4.0.0" id="500">
<cookie>I'm a cookie holding some text</cookie>
<target>operator_name</target>
<dst>
<host>target_server_ID</host>
</dst>
<session>session_id</session>
</packet>