2.1 The Pakt Object Model

A pakt server publishes a hierarchy of objects to interested clients. The object hierarchy (also called the object space) has a distinct expression in XML. A basic pakt object consists of its Attributes and Children:

• Attributes, called "Properties" or "Parameters" in some languages, are the data fields of the object.

  There is one special attribute, "name", which defines the (guess what) name of the object, which must be both present (with the exception of messages, see 'Messages') and unique within the object's siblings. If the name attribute is not explicitly given it will be set to the class (element) name, plus possibly an increasing number.

  Attributes that have no value are not serialized.

• Children are other objects that are attached to the object.

An object is instantiated from a snippet of XML by means of the registry ('Registry'). This process is called deserialization. Actual instantiated objects are usually wrappers for some other "proprietary" objects (eg, gstreamer elements), to enable actual functionality by publishing the wrapped object's data and functionality into pakt-accessible attributes. Every instantiated object can be serialized to XML.

note

There is no concept of methods in this object model, but see the section on messages. Most of the functionality is achieved through setting attributes.

Pakt uses the XML namespace mechanism to distinguish objects of various components. You usually don't have to explicitly state the namespaces, but it's more exact and might help avoid name conflicts. Also, when you instantiate objects in a namespace unknown to the server, the XML will be stored verbatim. This way, you can save private data anywhere within the server's object hierarchy (see 'Private Data'). The "official" pakt namespaces and their various objects are documented in the reference section ('Reference') of this manual.

For purposes of this manual, consider the following simple hierarchy:

<t:foo name="myfoo" data="mydata"> <t:bar name="mybar0"/> <t:bar name="mybar1"/> </t:foo>

This XML snippet describes an object of class "foo" with the name "myfoo" and an attribute, named "data", with value "mydata". It has two children of class "bar", named "mybar0" and "mybar1", which have no attributes or further children.

2.1.1 Addressing Scheme

Objects are addressed by means of their "name"-Attribute (from now on just called "the object's name"). A path through the hierarchy is expressed in a directory-like way, with slashes ('/') septing the path components. Considering the simple hierarchy described above, the path "/myfoo/mybar1" will address the second "bar" object (mybar1).

Paths can be relative to some object, so the path "../mybar1", relative to mybar0, will also address the second "bar" object (mybar1).

2.1.2 Deserialization

Using the XML-enabled access methods ('Access Methods'), you can send arbitrary snippets of XML to a certain object (if no target is given, it will be sent to the root object of the hierarchy). Whenever such XML is received, the target object sees if it can find a child object with the given name attribute. If yes, this child is being updated (deserialized) from the received XML. If not, a new object is instantiated (created and deserialized) from that XML. This behaviour is recursive, so if the following XML is sent to the root object of the sample hierarchy described above:

<t:foo name="myfoo" data="mynewdata"> <t:bar name="mybar1" data="somebardata"/> <t:bar name="mybar2"/> </t:foo>

three distinct operations are performed:

• the "data" attribute of "myfoo" is updated to contain "mynewdata"
• the "mybar1" object's "data" attribute is set to "somebardata"
• a new "bar" object, called "mybar2", is created and added to "myfoo".

So, after the update, the object space will look like this:

<t:foo name="myfoo" data="mynewdata"> <t:bar name="mybar0"/> <t:bar name="mybar1" data="somebardata"/> <t:bar name="mybar2"/> </t:foo>

The attributes which are accepted by objects of certain classes are documented in the reference section ('Reference') of this manual. If an object is given a value for an unknown attribute, eg. if the "bar" class in this example didn't really have a "data" attribute, the update will be silently ignored.

2.1.3 Messages

There is one special class of objects that, while being added to the target object on creation, will quite instantly self-destruct again: Messages. Messages are the only objects that dont require a "name" attribute, as they will only very shortly be attached to some parent object. They will also, on creation, not instantiate their children, but save the contained XML to be sent to the message target. Even before the specific message operation is performed, the message object will remove itself from it's (temporary) parent, and afterwards self-destruct. The basic set of message is documented in 'Messages in p:', the message class itself in 'Message'.

2.1.4 Registry

The registry is pakt's internal mechanism to match XML element names to internal class names. For an XML element name to be a valid pakt classname, there is not necessarily a corresponding internal class. In some cases (like, for instance for 'Element's), the coupling is to a certain class with some detail data that defines the instance of the object.

2.1.5 Private Data

When a pakt server encounters an unknown XML element, it will instantiate a 'Private' data object to store the XML verbatim. Using this feature, you can add arbitrary private data to any place of the object space. Note however, that you cannot manipulate the children of a private object like for normal objects. Adding to and removing from a private object will result in data loss and memory leaks, so just dont do it. You can, however, update (and set) a private object like any other.

2.2 GObject Interaction

To understand how pakt works, I will have to tell you some things about the interaction with (glib/gtk) GObjects, because pakt is implemented using this object model. While the pakt objects themselves are implemented using GObjects, with XML attributes corresponding to their properties, those will often be used to wrap other GObjects, and tools to help such wrapping are implemented in libpakt.

When a GObject is wrapped in such a way, the wrapped object's properties (data members) will not relate to the pakt object's attributes, or the XML attributes in any way (with exception of the "name" attribute for 'NamedGObject's). Instead, the wrapped object's properties are expressed in pakt as separate child objects of the wrapper object (see the 'p:property' class). This is to allow metadata (like type and range) of those properties to be expressed as attributes of the property wrapper. To avoid confusion, the wrapper's data fields are called "Attributes", and the wrapped object's data fields "Properties" in this manual.

2.3 Access Methods

Pakt allows for various different methods for accessing the object space. Currently only XML Sockets are implemented, though. OSC will follow soon.

2.3.1 XML Sockets

XML Sockets are raw TCP sockets, over which you send null-terminated XML documents. This concept has been introduced with macromedia's Flash. Each snippet of XML between the zero bytes must constitute a full well-formed XML document; the XML declaration can be missing, but all used namespaces must be declared.

2.3.2 OSC

The Open Sound Control protocol is a simple UDP-based protocol for updating parameters on the server's hierarchy. It is used in many media applications. For pakt, OSC can be used for setting the object's properties and to receive updates when values have changed. OSC is not yet implemented, and will be documented here when it is.