Previous page

Next page

Locate page in Contents

Print this page

Optional Elements

Many parameters that you supply to Agent API calls or receive from Agent are defined in the XML schema as optional elements. This means that when composing a request message, you include an element or omit it depending on the operation that you are trying to perform. In response messages, an optional element may be similarly included or not. Unfortunately, unlike the XML Schema optional elements, the class members in traditional programming languages cannot be "optional" and therefore are handled differently in this respect. The proxy classes generated from WSDL will have optional elements as primitive types (int, bool, etc.), complex types (strings, classes, structures), and arrays. The following describes how to handle each element type in your code.

Primitive Types

A primitive type member is usually flagged by a corresponding member of type bool declared just below it. The name of the boolean variable is made of the name of the principal member with an added Specified suffix.

As an illustration, let's take a look at the userType class.

public class userType {

    /// <remarks/>

    public userTypeInitial_group initial_group;

    /// <remarks/>

    [System.Xml.Serialization.XmlElementAttribute("group")]

    public userTypeGroup[] group;

    /// <remarks/>

    public int uid;

    /// <remarks/>

    [System.Xml.Serialization.XmlIgnoreAttribute()]

    public bool uidSpecified;

    /// <remarks/>

    public string shell;

    /// <remarks/>

    [System.Xml.Serialization.XmlElementAttribute(DataType="base64Binary")]

    public System.Byte[] password;

    /// <remarks/>

    public string home_dir;

    /// <remarks/>

    public string name;

    /// <remarks/>

    public string comment;

    // ...

}

Note that the uid and uidSpecified class members form a pair. The value of the uidSpecified member indicates whether the uid is present or not in the data, meaning if it contains a meaningful value or not.

Before you try to read the value of the uid member, you have to check whether its value was set when the response was generated on the server side. You do that by looking at the corresponding boolean flag first, i.e. the value of the uidSpecified member. If the value is true then uid was set and it contains a meaningful value. If the value is false then uid was not set and therefore must be ignored.

When you assign a value to an "optional" member, you will have to set the corresponding boolean flag to true in order for the element to be included in the packet. Here's an example:

uid = 100;

uidSpecified = true;

If you don't set the xxxSpecified flag to true then the receiving code will evaluate the corresponding optional element as "not included in the request" and will ignore its value.

Complex Types

The XML schema complex types are represented in C# by strings, classes, and structures. An example of such an element is the initial_group member from the code example above. To determine whether the element is present or not in the packet, check if the value of the object is null:

if (initial_group == null)

{

    // The element is absent ...

}

Arrays

Finally, arrays (e.g. the group member in the example above) are considered optional if they have a null value or are empty.

Please send us your feedback on this help page