This reference documents the internal and external classes and messages of 'libpakt' and [pgstd] relevant to accessors.

Internal classes cannot be instantiated via the 'Access Methods', but are relevant because external classes derive from them and inherit their attributes. External classes are listed here with their XML element name as class name, and are used directly in the serialization/deserialization process.

4.1 p: namespace

The p: namespace contains basic pakt classes and messages. It's URN is "http://subsignal.org/pakt/p/1.0".

4.1.1 Classes in p:

the root of pakt's internal class hierarchy. As an accessor, you will rarely be confronted with a raw pObject, but all objects inherit from it the name attribute.

The name of an object, together with the names of all it's parents, defines its address for pakt's addressing scheme. It must be unique within all of it's parent's children (within it's siblings). If no name attribute is present when a pakt server encounters an object, a name will be made up.

Names should not contain special characters like / or space. To be safe, make up names that consist solely of letters, digits, '-'s and underscores.

Inheritance graph: Object -> GObject
inherited attributes: name

wraps a glib-style object. On creation, it will scan the wrapped object's properties and add them as 'p:property' objects to itself. This is done before the deserialization of children, so delivering valid GProperties with the instantiation of a GObject will set the properties as expected.

see also: 'GObject Interaction'

Inheritance graph: Object -> p:property
inherited attributes: name

wraps a glib-style property of the parent object.

the property value, converted to a string

Inheritance graph: Object -> p:spec
inherited attributes: name

wraps a property's specification (GParamSpec), read-only. Always a child of 'p:property'.

the property data type. Primitive data types are: string, bool, int, uint, long, ulong, int64, uint64, float and double.

the type attribute can contain any other glib-type name, though (for instance, a class name).

the nickname of the property

a short text describing the property

the default value of the property (not present if NULL)

the minimum allowed value for numeric properties (not present for 'string's)

the maximum allowed value for numeric properties (not present for 'string's)

wether the property is readable

wether the property is writable

Inheritance graph: Object -> GObject -> NamedGObject
inherited attributes: name

NamedGObjects wrap the special case of 'GObject's that have a "name" property themselves. The name of the wrapping object and that of the wrapped object are linked bidirectionally: if either one is changed, the other one is updated, too.

Inheritance graph: Object -> Message
inherited attributes: name

a special object that will not really be attached to any other object, but redirect its contents to the specified 'target'. The basic messages are documented in 'Messages in p:'.

If no target attribute is given, the message will be directed to the same target as its parent XML element; if the message has no parent, it will be directed to the root of the server's object space.

see also: 'Messages'

the target this message will be delivered to, following the 'Addressing Scheme'.

the source of this message (optional).

Whenever the server encounters an XML element with a name it cannot relate to any internal class, it will construct a private object to store the given data. This way, you can store arbitrary private data almost anywhere in the server's object space.

Be aware, though, that you cannot manipulate the contents (children and attributes) of a private object using the usual functionality. Doing so will result in errors, data loss, memory leaks and possibly other Bad Stuff(TM).

see also: 'Private Data'

If the server encounters an error during execution of some function, it will reply with an error object containing a descriptive error message as XML string content.

4.1.2 Messages in p:

Inheritance graph: Object -> Message -> p:get
inherited attributes: name target source

sending a 'get' message to some object of the object hierarchy will result in a reply containing the target object.

Inheritance graph: Object -> Message -> p:set
inherited attributes: name target source

a 'set' message will update all attributes, and, recursively, all children of the target object.

note

You don't have to explicitly use 'set' messages, you can also send an updated version of the target object to its parent, as described in 'Deserialization'.

Inheritance graph: Object -> Message -> p:add
inherited attributes: name target source

an 'add' message will deserialize its children and add them to the target object.

note

As with 'p:set', you don't have to explicitly use 'add' messages, you can also just send the new objects to the target object, as described in 'Deserialization'. Add, in this way, is a generic 'Message'. Using add makes things more obvious though.

Inheritance graph: Object -> Message -> p:remove
inherited attributes: name target source

a 'remove' message will remove the target object and all its children from the object space.

Inheritance graph: Object -> Message -> p:monitor
inherited attributes: name target source

'monitor' messages will attach a "watchdog" to the target object, so that you will receive notifications whenever some part of that object is changed. What kind of changes are monitored is determined by the 'what' property. If no 'what' property is given, all possible changes are monitored.

The messages you get sent in response to a change will have a 'source' attribute corresponding to the location of the emitting object. If you set the 'replyto' attribute, its value will fill the 'target' of the message that is sent.

defines which kind of changes are to be monitored. Must be one of the following, or empty:

• "changed" will monitor all changes to data attributes of the target. Changes to any of the attributes will result in 'p:set' messages being sent to you.

• "name_changed" will monitor the special case of the 'name' attribute being changed. When it is changed, a 'p:set' message with the new name will be sent to you, with the old address of the object as 'target'.

• "add" monitors will trigger 'p:add' messages whenever a new object is added to the 'target'.

• "remove", finally, will notify you with a 'p:remove' message when the 'target' is being removed from the object hierarchy.

the 'target' to send the notifications to.

4.2 gst: namespace

The gst: namespace contains classes that wrap gstreamer elements and other gstreamer fuctionality. It's URN is "http://subsignal.org/pakt/pgst/1.0".

4.2.1 Classes in gst:

Inheritance graph: Object -> GObject -> NamedGObject -> Element
inherited attributes: name

wraps a gstreamer element. From this base class, 'dynamic' classes for all available gstreamer elements are constructed. The derived classes will be in the 'gst: namespace' and have the name of the gstreamer element factory, for instance "gst:xvideosink". The element's parameters are added as 'p:property's by the more generic 'GObject' class.

When the element is a gstreamer "bin" (bin, thread, or pipeline), the wrapped gstreamer elements of other 'Element's being added to the element will be added to the bin.

The pads of the gstreamer element will be added as 'gst:pad' objects in a fashion very similar to that of 'p:property's being automatically generated for 'GObject's.

describes the playing state of the element, can be one of:

• STATE_VOID_PENDING
• STATE_NULL
• STATE_READY
• STATE_PAUSED
• STATE_PLAYING

Setting the 'state' attribute will attempt to change the state of the wrapped gstreamer element. The attribute will always reflect the current playing state.

Inheritance graph: Object -> GObject -> NamedGObject -> gst:pad
inherited attributes: name

wraps a gstreamer element pad.

describes the direction of the pad, can be one of:

• DIRECTION_INPUT for gstreamer "sinks"
• DIRECTION_OUTPUT for gstreamer "sources"

'direction' is read-only. Setting it will produce no effect.

the peer (other 'gst:pad') this pad is linked to, in pakt 'Addressing Scheme' notation. Will be empty when the pad is unlinked.

Setting the 'peer' property will unlink the pad if it is already connected, and attempt to link it to the given peer pad. The value of 'peer' will always contain the relative path to the current peer pad.