XFN Attribute Model

In the XFN attribute model, a set of zero or more attributes can be associated with a named object. Each attribute in the set has a unique attribute identifier, an attribute syntax, and a set of zero or more distinct attribute values. Each attribute value has an opaque data type. The attribute identifier serves as a name for the attribute. The attribute syntax indicates how the attribute values are encoded.

The operations in the base attribute interface can be used to examine and modify the settings of attributes associated with existing named objects. These objects can be contexts or other types of objects. The attribute operations do not create names or remove names in contexts.

The range of support for attribute operations can vary widely. Some naming systems might not support any attribute operations. Other naming systems might support only read operations or operations on attributes whose identifiers are in some fixed set. A naming system might limit attributes to have single values or might require at least one value. Some naming systems might associate attributes only with context objects, while others might allow associating attributes with non-context objects.

Typically, attributes of an object are manipulated through operations that operate on a single attribute, such as reading or updating a single attribute. Moreover, the client is typically expected to be able to read all attribute values of a single attribute in one call. However, sometimes there is a requirement to manipulate several attributes of a single object or to obtain individual attribute values of a single attribute from the name service. To address these requirements, two kinds of attribute operations are defined:

• Single-attribute operations

• Multiple-value and multiple-attribute operations

Relationship to Naming Operations

An XFN attribute operation might not be equivalently expressed as an independent fn_ctx_lookup() operation followed by an attribute operation in which the caller supplies the resulting reference and an empty name.

This is because some attribute models associate attributes with a named object in the context in which the object is named. In others, an object's attributes are stored in the object itself. XFN accommodates both these models.

Note - Invoking an attribute operation using the target context and the terminal atomic name accesses either the attributes that are associated with the terminal name or the object named by the terminal name--this is dependent upon the underlying attribute model. This document uses the term "attributes associated with a named object" to refer to all of these cases.

XFN does not provide any guarantee about the validity of the relationship between the attributes and the reference associated with a given name. Some naming systems might store the reference bound to a name in one or more attributes associated with a name. Attribute operations might affect the information used to construct a reference.

To avoid undefined results, programmers must use the operations in the context interface and not the attribute operations when manipulating references. Applications should avoid using specific knowledge about how an XFN context implementation over a particular naming system constructs references.

Status Objects

In each attribute operation, the caller supplies an FN_status_t parameter. The called function sets this status object as described in "Status Objects and Status Codes". All status objects are handled in this manner for each operation in the base attribute interface; this will not be restated in the individual operation descriptions.

Single-Attribute Operations

fn_attr_get
fn_attr_modify
fn_attr_get_values
fn_valuelist_next
fn_valuelist_destroy

Each of these operations takes as arguments a context and composite name relative to this context and manipulates the attributes associated with the named object. Each operation sets a status object to describe the status of the operation.

Get Attribute

This operation returns the identifier, syntax, and values of a specified attribute, attribute_id, for the object named name relative to the context ctx. If name is empty, the attribute associated with ctx is returned.

FN_attribute_t *fn_attr_get(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const FN_identifier_t *attribute_id,
    unsigned int follow_link, 
    FN_status_t *status);

fn_attr_get_values() and its related functions are for getting individual values of an attribute and should be used if the combined size of all the values is expected to be too large to be returned in a single invocation of fn_attr_get().

Modify Attribute

This operation modifies according to mod_op the attribute attr associated with the object named name, relative to ctx. If name is empty, the attribute associated with ctx is modified.

int fn_attr_modify(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    unsigned int mod_op,
    const   FN_attribute_t *attr,
    FN_status_t *status);

Table 2-1 XFN Attribute-Modification Operations

Get Attribute Values

This set of operations allows the caller to obtain attribute values associated individually with a single attribute.

FN_valuelist_t *fn_attr_get_values(
    FN_ctx_t *ctx,  
    const   FN_composite_name_t *name,
    const   FN_identifier_t *attribute_id,
    unsigned int follow_link,
    FN_status_t *status);
 
FN_attrvalue_t *fn_valuelist_next(
    FN_valuelist_t, *vl
    FN_identifier_t **attr_syntax,
    FN_status_t *status);
 
void fn_valuelist_destroy(
    FN_valuelist_t *vl);

This set of operations is used to obtain the set of values of a single attribute, identified by attribute_id, associated with name, relative to ctx. If name is empty, the attribute associated with ctx is obtained.

This interface should be used instead of fn_attr_get() if the combined size of all the values is expected to be too large to be returned by fn_attr_get().

The operation fn_attr_get_values() initiates the enumeration process. It returns a handle to an FN_valuelist_t object that can be used for subsequent fn_valuelist_next() calls to enumerate the values requested.

The operation fn_valuelist_next() returns the next attribute value in the enumeration and updates vl to indicate the state of the enumeration.

The operation fn_valuelist_destroy() frees the resources associated with the enumeration. This operation can be invoked at any time to terminate the enumeration.

Multiple-Attribute Operations

fn_attr_get_ids
fn_attr_multiget
fn_multigetlist_next
fn_multigetlist_destroy
fn_attr_multi_modify

These operations allow the caller to specify an operation that handles on multiple attributes using one or more calls.

The failure semantics can vary widely across naming systems. In some systems the single function call can contain multiple individual naming system operations, with no guarantees of atomicity.

Get Attribute Identifiers

This operation gets a list of all the attribute identifiers that are associated with the object named name relative to the context ctx. If name is empty, the attribute identifiers associated with ctx are returned.

FN_attrset_t *fn_attr_get_ids(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    unsigned int follow_link,
    FN_status_t *status);