LIBPICL(3PICL) PICL Library Functions LIBPICL(3PICL)
NAME
libpicl - PICL interface library
SYNOPSIS
cc [
flag ... ]
file ...
-lpicl [
library ... ]
#include <picl.h>
DESCRIPTION
The PICL interface is the platform-independent interface for clients to
access the platform information. The set of functions and data structures
of this interface are defined in the <
picl.h> header.
The information published through PICL is organized in a tree, where each
node is an instance of a well-defined PICL class. The functions in the
PICL interface allow the clients to access the properties of the nodes.
The name of the base PICL class is
picl, which defines a basic set of
properties that all nodes in the tree must possess. The following table
shows the property set of a
picl class node.
+--------------+-------------------------------------+
|Property Name | Property Value |
+--------------+-------------------------------------+
|
name | The name of the node |
+--------------+-------------------------------------+
|
_class | The PICL class name of the node |
+--------------+-------------------------------------+
|
_parent | Node handle of the parent node |
+--------------+-------------------------------------+
|
_child | Node handle of the first child node |
+--------------+-------------------------------------+
|
_peer | Node handle of the next peer node |
+--------------+-------------------------------------+
Property names with a a leading underscore ('_') are reserved for use by
the PICL framework. The property names
_class,
_parent,
_child, and
_peer are reserved names of the PICL framework, and are used to refer to a
node's parent, child, and peer nodes, respectively. A client shall
access a reserved property by their names only as they do not have an
associated handle. The property
name is not a reserved property, but a
mandatory property for all nodes.
Properties are classified into different types. Properties of type
integer, unsigned-integer, and float have integer, unsigned integer, and
floating-point values, respectively. A
table property type has the handle
to a table as its value. A table is a matrix of properties. A
reference property type has a handle to a node in the tree as its value. A
reference property may be used to establish an association between any
two nodes in the tree. A
timestamp property type has the value of time in
seconds since Epoch. A
bytearray property type has an array of bytes as
its value. A
charstring property type has a nul ('\0') terminated
sequence of ASCII characters. The size of a property specifies the size
of its value in bytes. A
void property type denotes a property that
exists but has no value.
The following table lists the different PICL property types enumerated in
picl_prop_type_t.
+------------------------+----------------------------+
| Property Type | Property Value |
+------------------------+----------------------------+
|
PICL_PTYPE_VOID | None |
+------------------------+----------------------------+
|
PICL_PTYPE_INT | Is an integer |
+------------------------+----------------------------+
|
PICL_PTYPE_UNSIGNED_INT | Is an unsigned integer |
+------------------------+----------------------------+
|
PICL_PTYPE_FLOAT | Is a floating-point number |
+------------------------+----------------------------+
|
PICL_PTYPE_REFERENCE | Is a PICL node handle |
+------------------------+----------------------------+
Reference Property Naming Convention
Reference properties may be used by plug-ins to publish properties in
nodes of different classes. To make these property names unique, their
names must be prefixed by _
picl_class_name_, where
picl_class_name is the
class name of the node referenced by the property. Valid PICL class names
are combinations of uppercase and lowercase letters 'a' through 'z',
digits '0' through '9', and '-' (minus) characters. The string that
follows the '_
picl_class_name_' portion of a reference property name may
be used to indicate a specific property in the referenced class, when
applicable.
Property Information
The information about a node's property that can be accessed by PICL
clients is defined by the
picl_propinfo_t structure.
typedef struct {
picl_prop_type_t type; /* property type */
unsigned int accessmode; /* read, write */
size_t size; /* item size or
string size */
char name[PICL_PROPNAMELEN_MAX];
} picl_propinfo_t;
The
type member specifies the property value type and the
accessmode specifies the allowable access to the property. The plug-in module that
adds the property to the PICL tree also sets the access mode of that
property. The volatile nature of a property created by the plug-in is not
visible to the PICL clients. The
size member specifies the number of
bytes occupied by the property's value. The maximum allowable size of
property value is
PICL_PROPSIZE_MAX, which is set to 512KB.
Property Access Modes
The plug-in module may publish a property granting a combination of the
following access modes to the clients:
#define PICL_READ 0x1 /* read permission */
#define PICL_WRITE 0x2 /* write permission */
Property Names
The maximum length of the name of any property is specified by
PICL_PROPNAMELEN_MAX.
Class Names
The maximum length of a PICL class name is specified by
PICL_CLASSNAMELEN_MAX.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | MT-Safe |
+---------------+-----------------+
SEE ALSO
libpicl(3LIB),
attributes(7) March 28, 2000
LIBPICL(3PICL)