NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

SecurityElement class

The SecurityElement class is defined to represent the XML object model for encoding security objects. The design is intended to be a lightweight implementation of a simple XML object model for use within the security system, and not intended for use as a general XML object model.

XML object model

The simple XML object model for an element consists of the following parts:

The following XML forms summary the corresponding XML forms that are supported:

Elements with a NULL text string are represented in the <tag/> form, otherwise text is delimited by <tag> … </tag> tokens. Both forms may or may not be combined with attributes, which are shown if present or omitted otherwise.

Attributes that appear as <tag name> instead of <tag name=value> are designated by the distinguished object SecurityElement.NoValue. The attribute name must be non-NULL and of one character or longer.

The tags, attributes, and text of elements are always case-sensitive.

The XML form will contain quotations and escapes where necessary. String values that include characters that are invalid for use in tag/name/value/text will result in ArgumentException being raised. The above rules apply to all properties and methods.

NOTE: for performance reasons character validity is only checked when the element is encoded into XML text form, and not on every possible set of a property or method. Static methods allow explicit checking where needed.

Constructors

Constructor Void SecurityElement (String tag)

Creates an element corresponding to:

<tag/>
Constructor Void SecurityElement (String tag, String text)

Creates an element corresponding to (or text==NULL is equivalent to above):

<tag>text</tag>

Properties

Properties of the SecurityElement class are described in terms of a general XML element.

<tag name=value …>
   text…
   <child … />
   …
</tag>
Property String Tag; {get;set;}

Get/set the string tag of the element. A tag is required to be a valid element.

Property Int Attributes; {get;}

Get the number of attributes on the element.

Property Int Children; {get;}

Get the number of child elements of the element.

Property String Text; {get;set;}

Get/set the string text of the element. A NULL value specifies <tag … /> form, where “” string value is <tag …></tag> form, which are considered distinct.

Basic Methods

Void AddAttribute (String name, String value)

Adds attribute of the form “name=value” to the element. If an attribute of the same name (case sensitive) exists it is changed to the new value. You cannot have more than one attribute of a given name.

Void AddChild (SecurityElement)

Adds the element as the last child of the element. Duplicate child elements are allowed. Use the Children property for more complex manipulations.

SecurityElement GetChild (Int index)

Returns the index-th child of the element. Valid for values 0 = index < Children.

Boolean Equal (SecurityElement other)

Compares the element to the other and returns true if the tag, attributes, text, and all child elements are equal. Child elements must be equal in number and are compared one to one in order they exist. Attributes must be in the same order to compare as equal: that is, the following will not be considered equal.

<tag attr1=x attr2=y>

<tag attr2=y attr1=x>

static Boolean IsValidTag (String)
static Boolean IsValidName (String)
static Boolean IsValidValue (String)
static Boolean IsValidText (String)

These methods test if the string is valid for use as tag/name/value/text in an element.

Text encoding Methods

void ToStream (Stream stream)

Writes a textual representation of the SecurityElement to the stream, including its attributes, text, and children. Indentation and line breaks are unspecified.

void ToStream (Stream stream, Int indent, Int LineLength)

Writes a “pretty” textual representation of the SecurityElement to the stream, including its attributes, text, and children. The top element is indented by the specified amount of whitespace.

The LineLength parameter gives a desired maximum line length. The formatted output will attempt to keep line lengths shorter than this many characters, however if indenting or long tag/attribute/text words may cause this limit to be exceeded where necessary to produce a true representation of the element.

static SecurityElement FromStream (Stream stream)

Creates an equivalent SecurityElement to the one that wrote its textual representation with ToStream method.

String ToString ()

Return string representation of the SecurityElement and its attributes, text, and children.

static SecurityElement FromString (String s)

Creates an equivalent SecurityElement to the one that made the string representation with ToString method.

Searching Methods

String Attribute (String name)

Returns the string value of attribute by name, or NULL if none.

SecurityElement SearchForChildByTag (String name)

Returns element of any immediate child element that has a matching tag. This is useful for representations of the form <tag><child1/><child2/>…</tag>.

String SearchForTextOfTag (String tag)

Searches for the text of an element with the given tag, beginning with the element (this) itself, then SearchForTextOfTag() on each child in order, which searches the child’s child and so forth, depth-first.

Other details

Errors parsing XML cause XMLSyntaxException to be raised.

XML is case sensitive.