Extended Attribute Interface (Preliminary Specification)

fn_attr_search
fn_searchlist_next
fn_searchlist_destroy
fn_attr_ext_search
fn_ext_searchlist_next
fn_ext_searchlist_destroy

The XFN extended attribute interface consists of operations that perform searching and creation of objects in the namespace with attributes. The operations in this interface are considered "preliminary," in that they are not yet standard and might change in the next revision of the specification.

Attribute Search Interface

The search interface contains several operations: a basic search operation, which performs associative lookup in a single context, and an extended search operation that allows the search criteria to be specified using an expression . It also allows the scope of the search to encompass a wider scope than only a single context.

Basic Search

This set of operations is used to enumerate names of objects bound in the target context named name relative to the context ctx with attributes whose values match all those specified by match_attrs. Using return_ref specifies whether to return the references of named objects in the search, while return_attr_ids specifies the attributes to be returned in the search.

FN_searchlist_t *fn_attr_search(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const FN_attrset_t *match_attrs,
    unsigned int return_ref,
    const FN_attrset_t *return_attr_ids,
    FN_status_t *status);
 
FN_string_t *fn_searchlist_next(
    FN_searchlist_t *sl,
    FN_ref_t **returned_ref,
    FN_attrset_t **returned_attrs,
    FN_status_t *status);
 
void fn_searchlist_destroy(
    FN_searchlist_t *sl);

The call to fn_attr_search() initiates the search in the target context. It returns a handle to an FN_searchlist_t object that is used to enumerate the names of the objects whose attributes match match_attrs.

fn_searchlist_next() returns the next name in the enumeration identified by sl. The reference of the name, if requested, is returned in returned_ref. The attributes specified by return_attr_ids are returned in returned_attrs. Successive calls to fn_searchlist_next() using sl return successive names, and optionally, references and attributes in the enumeration and further update the state of the enumeration.

fn_searchlist_destroy() releases resources used during the enumeration. It can be called at any time to terminate the enumeration.

Extended Search

This set of operations is used to list names of objects whose attributes satisfy the filter expression filter. The control argument encapsulates the option settings for the search.

FN_ext_searchlist_t *fn_attr_ext_search(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,,
    const FN_search_control_t *control
    FN_status_t *status);
 
FN_composite_name_t *fn_ext_searchlist_next(
    FN_ext_searchlist_t *esl,
    FN_ref_t **returned_ref,
    FN_attrset_t **returned_attrs,
    FN_status_t *status);
 
void fn_ext_searchlist_destroy(
    FN_ext_searchlist_t *esl);

These options are:

1. The scope of the search. This can be any of the following:

   • Search the named object

   • sSearch the context named by name

   • Search the entire subtree rooted at the context named by name

   • Ssearch the context implementation-defined subtree rooted at the context named by name.

2. Whether XFN links are followed during the search

3. A limit on the number of names returned

4. Whether the reference associated with the named object is returned

5. Which attributes associated with the named object are returned

The filter expression is evaluated against the attributes of the objects bound in the scope of the search. The filter evaluates to either true or false.

The call to fn_attr_ext_search() initiates the search and, if successful, returns a handle to an FN_ext_searchlist_t object, esl, that is used to enumerate the names of the objects that satisfy the filter.

fn_ext_searchlist_next() returns the next name, and optionally, its reference and attributes, in the enumeration identified by esl. The name returned is a composite name, to be resolved relative to the starting context for the search. The starting context is the context named name relative to ctx, unless the scope of the search is only the named object. If the scope of the search is only the named object, the teriminal atomic name is returned. Successive calls to fn_ext_searchlist_next() using esl return successive names, and optionally, references and attributes, in the enumeration and further update the state of the enumeration.

fn_ext_searchlist_destroy() releases resources used during the search and enumeration. It can be called at any time to terminate the enumeration.

Object Creation with Attributes

fn_attr_bind
fn_attr_create_subcontext

At times it is useful or necessary to associate attributes with an object at the time the object is created. The XFN extended attribute interface contains functions that provide these capabilities. The two functions in this interface, fn_attr_bind() and fn_attr_create_subcontext(), are analogous to their counterparts in the base context interface, fn_ctx_bind() and fn_ctx_create_subcontext(), respectively, except that the versions in the extended attribute interface allow an extra parameter for specifying attributes to be associated with the new binding.

Bind with Attributes

This operation binds the supplied reference ref to the supplied composite name name relative to ctx, and associates the attributes specified in attrs with the named object. The binding is made in the target context--that context named by all but the terminal atomic part of name. The operation binds the terminal atomic part of name to the supplied reference in the target context. The target context must already exist.

int fn_attr_bind(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const FN_ref_t *ref,
    unsigned int exclusive,
    FN_status_t *status);

The value of exclusive determines what happens if the terminal atomic part of the name is already bound in the target context. If exclusive is non-zero and name is already bound, the operation fails. If exclusive is zero, the new binding replaces any existing binding, and attrs, if not NULL, replaces any existing attributes associated with the named object.

Create Subcontext with Attributes

This operation creates a new XFN context of the same type as the target context--that named by all but the terminal atomic component of name--and binds it to the supplied composite name name. In addition, attributes given in attrs are associated with the newly created context. The target context must already exist. The new context is created and bound in the target context using the terminal atomic name in name. The operation returns a reference to the newly created context.

FN_ref_t *fn_attr_create_subcontext(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const FN_attrset_t *attrs,
    FN_status_t *status);