Objects and their Attributes

The QNX PPS service uses an object-based system; that is, a system with objects whose properties a publisher can modify. Clients that subscribe to an object receive updates when that object changes — when the publisher has modified it.

Thus, users can:

• publish to modify objects
• subscribe to receive notifications when objects have changed
• publish and subscribe to both modify objects, and receive notifications when objects have changed

For more information about publishing and subscribing, see the chapters Publishing and Subscribing.

---

The QNX PPS design is in many ways similar to many process control systems where the objects are control values updated by hardware or software. Subscribers can be alarm handling code, displays, and so on.

---

Object files

PPS objects are implemented as files in a special PPS filesystem. By default, PPS objects appear under /pps. These objects contain attributes.

There is never more than one instance of a PPS object, so persistence is a natural property that can be applied to PPS objects.

You can:

• Create directories and populate them with PPS objects by creating files in the directories.
• Use the open(), then the read() and write() functions to query and change PPS objects.
• Use standard utilities as simple debugging tools.

For example:

Display all objects in the system:

ls -lR /pps/

Display the current state of an object:

cat /pps/media/PlayCurrent

cat /pps/flash/apps/youtube

Monitor all changes to attributes in objects in the media directory, by opening the .all special object:

cat /pps/media/.all?wait

For information about .all, see “Special objects” below; for information about ?wait, see the chapter Options and Qualifiers.

Change the attribute of an object:

echo "attr::value" >>/pps/objectfilename

---

In order to avoid possible confusion or conflict in the event that applications from different organizations are integrated to use the same PPS filesystem, we recommend that you use your organization's web domain name to create your directory inside the PPS directory. Thus, QNX, whose internet web domain name is “qnx.com” should use /pps/qnx, while an organization with the domain name “example.net” should use /pps/example.

---

Object and directory sizes

PPS holds its objects in memory, and therefore these objects are small:

• the default size for a PPS object is 16 kilobytes
• the maximum size for a PPS object is 64 kilobytes

The number of PPS directories and objects is limited only by available memory. The depth of PPS directories is limited by the fact that the full pathnames of objects are stored in the persistent directory as files; the size of these pathnames is limited by the maximum filename size supported by the persistent filesystem used.

---

PPS objects should not be used as a dumping ground for large amounts of data. The size of most PPS objects should be measured in hundreds of bytes, and not in kilobytes. PPS has been tested with fs-qnx6, using the default PPS options. This configuration supports a total pathname length of 517 bytes, with no individual pathname element longer than 508 bytes. That is, a nesting depth of 50 is possible on fs-qnx6, providing that the total length of the path is less than 517 bytes.

---

Special objects

PPS directories can include special objects that you can open to facilitate subscription behavior. The table below lists these special objects:

For more information about these objects, see “Subscribing to multiple objects” the chapter Subscribing.

Object syntax

In PPS, the first line of a file names the object. This line is prefixed with an “@” character to identify it as the object name. The lines that follow define the object's attributes. These lines have no special prefix.

For example, in the PPS filesystem under the directory /pps/media/, the PPS object “PlayCurrent” contains the metadata for the currently playing song in a multimedia application. Let us assume that the metadata has the following schema:

@PlayCurrent
author::[Presentation text for track author]
album::[Presentation text for album name]
title::[Presentation text for track title]
duration::[Track duration, floating point number of seconds]
time::[Track position, floating point number of seconds]

An open() call followed by a read() call on this file would return the name of the object (the filename, with an “@” prefix), followed by the object's attributes with their values:

@PlayCurrent
author::Beatles
album::Abbey Road
title::Come Together
duration::3.45
time::1.24

---

Object names may not contain any of the following: “@” (at sign), “?” (question mark), “/” (forward slash), linefeed (ASCII LF), or ASCII NUL. Every line in the PPS object is terminated with a linefeed (“\n” in C, or hexadecimal 0A), so you must encode this character in a manner agreed upon by cooperating client applications. That is, any values containing ASCII LF or NUL characters must be encoded. The encoding field can be used to assist cooperating applications in determining what encoding is used in the value field.

---

Objects in filesystem listings

In listings of the PPS filesystem, PPS objects have no special identifiers. That is, they will appear just like any other file in a listing. Thus, the PPS object “PlayCurrent” used in the example above will appear in a listing as simply /pps/media/PlayCurrent.

Change notification

When PPS creates, deletes or truncates an object (a file or a directory), it places a notification string into the queue of any subscriber or publisher that has open either that object or the .all special object for the directory with the modified object.

The syntax for this notification string is a special character prefix, followed by the object identifier “@”, then the object name, as follows:

Responding to an object deletion

A deleted object is no longer visible in the filesystem (POSIX behavior), and only those processes with open file descriptors can continue accessing it. Therefore, typical behavior for an application receiving notification that an object has been deleted would be to close the file.

Attributes

PPS objects have user-defined attributes. Attributes are listed in a PPS object after the object name.

Attribute names may be composed of alpha-numeric characters, underscores and periods, but must begin with a letter or underscore. Attribute lines in a PPS object are of the form attrname:encoding:value\n, where attrname is the attribute name, and encoding defines the encoding type for value. The end of the attribute name and the end of the encoding are marked by colons (“:”). Subsequent colons are ignored.

PPS does not interpret the encoding; it simply passes the encoding through from publisher to subscriber. Thus, publishers and subscribers are free to define their own encodings to meet their needs. The table below describes possible encoding types:

An attribute's value can be any sequence of characters, except:

• a null (“\0” in C, or hexadecimal 0x00)
• a linefeed character (“\n” in C, or hexadecimal 0x0A).