Federated Naming Service Programming Guide

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


Operation Code	Meaning
`FN_ATTR_OP_ADD()`	Add an attribute with given attribute identifier and set of values. If an attribute with this identifier already exists, replace the set of values with those in the given set. The set of values can be empty if the target naming system permits.
`FN_ATTR_OP_ADD_EXCLUSIVE()`	Add an attribute with the given attribute identifier and set of values. The operation fails if an attribute with this identifier already exists. The set of values can be empty if the target naming system permits.
`FN_ATTR_OP_ADD_VALUES ()`	Add the given values to those of the given attribute (resulting in the attribute having the union of its prior value set with the given set). Create the attribute if it does not already exist. The set of values can be empty if the target naming system permits.
`FN_ATTR_OP_REMOVE ()`	Remove the attribute with the given attribute identifier and all its values. The operation succeeds even if the attribute does not exist. The values of the attribute supplied with this operation are ignored.
`FN_ATTR_OP_REMOVE_VALUES()`	Remove the given values from those of the given attribute (resulting in the attribute having the set difference of its prior value set and the given set). This succeeds even if some of the given values are not in the set of values that the attribute has. In naming systems that require an attribute to have at least one value, removing the last value removes the attribute as well.

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.