The XML message specifications in this guide are described using tables, similar to the following example:
Name |
Min/Max |
Type |
Description |
|
|
|
|
|
|
|
|
|
|
|
User name. |
|
|
|
Domain. |
|
|
|
Realm ID. |
|
|
|
User password. |
|
|
|
Custom timeout value. |
|
|
|
|
The information in a table is based on a corresponding XML Schema and describes the format of a request or response message, or the format of a data type.
Each row in a table represents an XML element. The elements are displayed in the order they are defined in the XML Schema.
The definitions for the table columns are as follows:
Name. Specifies an XML element name. The curly brackets represent the standard XML Schema xs:sequence
element. This means that the elements inside the brackets are the child elements of the element that precedes the opening bracket. In our example, the name
, domain
, realm
, password
, and expiration
elements are children of the login
element. The following is a sample XML code, built according to this specification:
<login>
<name>bXluYW1l</name>
<domain>bXlkb21haW4=</domain>
<realm>bXlyZWFsbQ==</realm>
<password>bXlwYXNz</password>
<expiration>1000</expiration>
</login>
In addition, we use square brackets to represent the standard XML Schema xs:choice
element, as shown in the following example:
Name |
Min/Max |
Type |
Description |
|
|
|
Device status, |
|
|
|
Denotes a choice between the <up> and the <down> elements. |
|
|
|
Enabled. |
|
|
|
Disabled. |
|
|
|
|
This means that the elements inside the brackets are the child elements of the element that precedes the opening bracket but the elements are mutually exclusive -- only one of them can be present in the request.
Min/Max. Specifies the cardinality of an element (the number of its minimum and maximum occurrences) in the following format:
minOccurs..maxOccurs
0
in the first position indicates that the element is optional.1
in the first position indicates that the element is mandatory and must occur at least once.[]
(square brackets) in the second position indicate that the number of the element occurrences is unbounded, meaning that the element may occur as many times as necessary in the same XML document at the specified position.The following examples demonstrate how an element cardinality may be specified:
0..1
The element is optional and may occur only once if included in the document.1..1
The element is mandatory. One, and only one, occurrence is expected in the document.0..[]
The element is optional but may occur an unlimited number of times if needed.1..[]
The element is mandatory. At least one occurrence is expected but the element may occur an unlimited number of times if needed.Type. Specifies the element type. The following element types are used in the schema:
int, string, base64Binary,
etc.Description. The description column contains the element description and provides information about its usage.
Let's now use the schema example from the beginning of this section and build the Agent request message from it. We already built the message body from it earlier. To make it a fully qualified Agent request message, we must also add the interface name to it and the message header. The following example is a complete Agent message that can be sent to the Agent and be processed by it:
<packet version="4.0.0" id="2">
<target>sessionm</target>
<data>
<sessionm>
<login>
<name>cm9vdA==</name>
<realm>00000000-0000-0000-0000-000000000000</realm>
<password>bXlwYXNz</password>
</login>
</sessionm>
</data>
</packet>