Chapter 2 Interfaces for Writing XFN Applications

This chapter describes the client programming interfaces for XFN. Additional information on the XFN interfaces is available in the man pages.

• Interface Conventions

• Usage

• Abstract Data Types

• Memory–Management Policies

• The Base Context Interface

• Base Attribute Interface

• Status Objects and Status Codes

• Parameters Used in the Interface

• Parsing Compound Names

XFN Interface Overview

The XFN client interface consists of the base context interface, the base attribute interface, the extended attribute interface, and some supporting interfaces.

The base context interface provides the basic operations for naming, such as binding a name to a reference, looking up the reference bound to a name, and unbinding a name.

The base attribute interface provides operations to examine and modify attributes associated with named objects.

The extended attribute interface provides operations to search and create objects in the namespace with attributes.

The supporting interfaces contain:

• Operations on the status object and status codes used in the context and attribute operations

• Abstract data types that represent objects passed to and returned from the context and attribute operations, such as composite names, references, and attributes

• A standard model and operations for parsing compound names whose syntax is specific to a naming system. These are of interest primarily to service implementers

• Operations for manipulating objects that are used to specify the criteria of extended search operations

API Usage Model summarizes how an application typically uses the programming interface.

Interface Conventions

The XFN interface is presented in ISO standard C, which is equivalent to ANSI standard C. The symbols defined by the interface are prefixed by fn or FN, for federated naming.

• The FN_ prefix is used for both data types and predefined constants.

  In addition, data types have a _t suffix, such as FN_ref_t. Predefined constants appear in all–uppercase characters, such as FN_ID_STRING.

• The fn_ prefix is used for function names. Names of functions in the base context interface have the prefix fn_ctx_, such as fn_ctx_lookup. Names of functions in the base attribute interface have the prefix fn_attr_, such as fn_attr_get.

Usage

Include the XFN header file in your code.

#include <xfn/xfn.h>

Include the XFN library when you compile.

cc -o program_name file1.c file2.c -lxfn

Abstract Data Types

Except for FN_attrvalue_t and FN_identifier_t, the types defined in the interface hide their actual data representation from the client. The client performs every operation on an object of one of these types through a well-defined interface for that data type.

When the client accesses these objects, the client refers to the objects solely through a handle to an object. Operations are provided to create objects of each type and to destroy them. The creation operation returns a handle to the new object. The destroy operation releases all resources associated with the object.

The only information about this handle revealed to the client is that it is a pointer type. The client cannot assume what this handle points to. In particular, the handle might not point directly to the memory containing the object's actual state.

The value 0 is defined for all pointer types. The functions that return handles in the interface return the value 0 as an indication of failure. The values 0 and NULL are equivalent.

Memory–Management Policies

The following memory–management policies are used for all client interfaces described in this chapter:

• When a function returns a non-const pointer to an object, the client “owns” the object. The client can alter the object and is responsible for freeing the space allocated to it when the object is no longer required.

• When a function returns a const pointer to an object, the service “owns” the object. The client must neither modify the object in any way, nor free the space allocated to it. If the client needs to control a copy, it must make one for itself.

• When a function takes a non-const parameter that is passed by reference, the service “borrows” the object during the function's execution. It can modify the object during this period, but it does not retain any reference to the object beyond this period.

• When a function takes a const parameter that is passed by reference, the service reads but does not modify the object. The service does not keep any reference to the object beyond the period of the function's execution.

The Base Context Interface

This section describes the operations in the base context interface. The interfaces to the objects used in the operations are described in Parameters Used in the Interface.

• Names in Context Operations

• Requirements for Supporting the Context Operations

• Status Objects

• Getting Context Handles

• Lookup and List Contexts

• Updating Bindings

• Managing Contexts

Names in Context Operations

In most of the operations of the base context interface, the caller supplies a context and a composite name argument. The supplied composite name is always interpreted relative to the supplied context.

The operation might eventually be effected on a different context called the operation's target context. Each operation has an initial resolution phase that conveys the operation to its target context, following which the operation is applied. The effect (but not necessarily the implementation) is that of:

• Doing a lookup on that portion of the name that represents the target context

• Invoking the operation on the target context

The contexts involved only in the resolution phase are called intermediate contexts. Normal resolution of names in context operations always follows XFN links, which are defined in XFN Links.

Requirements for Supporting the Context Operations

The lookup operation fn_ctx_lookup() must be supported by all contexts. When contexts do not support other operations, they can return an FN_E_OPERATION_NOT_SUPPORTED status code (see codes in Table 2–3).

XFN contexts are required to support the resolution phase of every operation in the base context and attribute interface when involved in the operation as intermediate contexts. That is, each intermediate context must participate in the process of conveying the operation to the target context, even if it does not support that operation itself. For example, not all contexts need to allow binding and listing names. However, all contexts must fully support the resolution phase of these operations.

Composite names are passed to an XFN context implementation in a structural form as an ordered sequence of components. When resolving a name, the context implementation is responsible for:

• Determining which set of leading components it must resolve

• Resolving that portion to a reference

• Returning a status object containing this reference and the portion of the name unresolved

Composite name resolution is further discussed in Composite Name Resolution.

Status Objects

In each context 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 way for each operation in the base context interface (this is not restated in the individual operation descriptions).

Getting Context Handles

All operations on a context require a context handle. There are several ways of obtaining a context handle. If you have a reference, you can use it to construct a context handle. Otherwise, to get a handle to the initial context, you must call fn_ctx_handle_from_initial().

fn_ctx_handle_from_initial
fn_ctx_handle_from_ref

Construct Handle to Initial Context

This operation returns a handle to the callers initial context. On successful return, the context handle points to a context containing the bindings described in Initial Context Bindings.

FN_ctx_t *fn_ctx_handle_from_initial(
    unsigned int authoritative,
    FN_status_t *status);

authoritative specifies whether the handle to the Initial Context returned should be authoritative, with respect to information the context obtains from the naming service. When the flag is non-zero, subsequent operations on this context handle can access the most authoritative information. When authoritative is zero, the handle to the Initial Context returned need not be authoritative. Authoritativeness is determined by specific naming services. In some, the authoritative source is a single “master” servers, while in others, the authoritative source is a quorum of servers.

Construct Context Handle From Reference

This operation returns a handle to an FN_ctx_t object given a reference, ref, for that context.

FN_ctx_t *fn_ctx_handle_from_ref(
    const   FN_ref_t *ref, 
    unsigned int authoritative,
    FN_status_t *status);      

authoritative specifies whether the handle to the context returned should be authoritative, with respect to information the context obtains from the naming service. When the flag is non-zero, subsequent operations on this context handle can access the most authoritative information. When authoritative is zero, the handle to the context returned need not be authoritative. Authoritativeness is determined by specific naming services. In some, the authoritative source is a single “master” server, while in others, the authoritative source is a quorum of servers.

Lookup and List Contexts

fn_ctx_lookup
fn_ctx_list_names
fn_namelist_next
fn_namelist_destroy
fn_ctx_list_bindings
fn_bindinglist_next
fn_bindlist_destroy
fn_ctx_lookup_link

Lookup

This operation returns the reference bound to name relative to the context ctx.

FN_ref_t *fn_ctx_lookup(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);

List Names

This set of operations is used to list the set of names bound in the context named name relative to the context ctx. The name must name a context. If the intent is to list the contents of ctx, name should be an empty composite name.

FN_nameslist_t* fn_ctx_list_names(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);
 
FN_string_t *fn_namelist_next(
    FN_namelist_t *nl,
    FN_status_t *status);
 
void fn_namelist_destroy(
    FN_namelist_t *nl);

The call to fn_ctx_list_names() initiates the enumeration process for the target context. It returns an FN_nameslist_t object that you can use for the enumeration.

The operation fn_namelist_next() returns the next name in the enumeration identified by nl and updates nl to indicate the state of the enumeration marker. Successive calls to fn_namelist_next() using nl return successive names and further update the state of the enumeration. fn_namelist_next() returns a NULL pointer when the enumeration has been completed.

fn_namelist_destroy() is used to release resources used during the enumeration. This call can be invoked at any time to terminate the enumeration.

The names enumerated using the list names operations are not in any order. There is no guaranteed relation between the order in which names are added to a context and the order in which names are obtained by enumeration. There is no guarantee that any two enumerations will return the names in the same order.

When a name is added to or removed from the context, this might not necessarily invalidate the enumeration handle that the client holds for that context. If the enumeration handle remains valid, the update might or might not be visible to the client.

List Bindings

This set of operations is used to list the set of names and bindings in the context named by name, relative to the context ctx. The name must name a context. If the intent is to list the contents of ctx, name should be an empty composite name.

FN_bindinglist_t* fn_ctx_list_bindings(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);FN_string_t *fn_bindinglist_next(
FN_bindinglist_t *bl,
    FN_ref_t ** ref,
    FN_status_t *status);
void fn_bindinglist_destroy(
   FN_bindinglist_t *bl);

The semantics of these operations are similar to those for listing names. In addition to a name string being returned, fn_bindinglist_next() also returns the reference of the binding for each member of the enumeration.

Lookup Link

This operation returns the XFN link bound to name. The terminal atomic part of name must be bound to an XFN link.

FN_ref_t *fn_ctx_lookup_link(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);

The normal fn_ctx_lookup() operation follows all XFN links encountered, including any that are bound to the terminal atomic part of name. This operation differs from the normal lookup in that when the terminal atomic part of name is an XFN link, this last link is not followed, and the operation returns the link.

Updating Bindings

fn_ctx_bind
fn_ctx_unbind
fn_ctx_rename

Bindings can be added, overwritten, removed, or renamed.

Bind

This operation binds the supplied reference ref to the supplied composite name name, taken relative to ctx. The binding is made in the target context—that named by all but the terminal atomic part of name. The operation binds the terminal atomic name to the supplied reference in the target context. The target context must already exist.

int fn_ctx_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 nonzero and name is already bound, the operation fails. If exclusive is zero, the new binding replaces any existing binding.

The value of ref cannot be NULL. If you want to reserve a name using the fn_ctx_bind() operation, bind a reference containing no address. This reference can be naming service-specific or it can be the conventional NULL reference.

Unbind

This operation removes the terminal atomic name in name from the target context—that named by all but the terminal atomic part of name.

int fn_ctx_unbind(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    FN_status_t *status);

This operation is successful even if the terminal atomic name was not bound in target context, but fails if any of the intermediate names are not bound. fn_ctx_unbind() operations are idempotent.

Rename

This operation binds the reference currently bound to oldname, resolved relative to ctx to newname, and unbinds oldname. The newname is resolved relative to the target context—that named by all but the terminal atomic part of oldname.

int fn_ctx_rename(
    FN_ctx_t *ctx,
    const FN_composite_name_t *oldname,
    const FN_composite_name_t *newname,
    unsigned int exclusive,
    FN_status_t *status);

If exclusive is zero, this operation overwrites any old binding of newname. If exclusive is nonzero, the operation fails if newname is already bound.

The only restriction that XFN places on newname is that it be resolved relative to the target context. For example, in some implementations, newname might be restricted to be a name in the same naming system as the terminal component of oldname. In another implementation, newname might be restricted to an atomic name.

Managing Contexts

fn_ctx_create_subcontext
fn_ctx_destroy_subcontext
fn_ctx_get_ref
fn_ctx_get_syntax_attrs
fn_ctx_handle_destroy
fn_ctx_equivalent_name

Contexts can be created, destroyed,and referenced.

Create Subcontext

This operation creates a new context of the same type as the target context—that named by all but the terminal atomic part of name—and binds it to the composite name name resolved relative to the context ctx, and returns a reference to the newly created context.

FN_ref_t *fn_ctx_create_subcontext(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    FN_status_t *status);

As with the bind operation, 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 fails if the terminal atomic name already exists in the target context.

The new subcontext exports the context interface and is created in the same naming system as the target context. XFN does not specify any further properties of the new subcontext. Other properties of the subcontext are determined by the target context and its naming system.

Destroy Subcontext

This operation destroys the subcontext named by name, interpreted relative to ctx, and unbinds the name.

int fn_ctx_destroy_subcontext(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);

As with the unbind operation, the operation succeeds if the terminal atomic name is not bound in the target context—that named by all but the terminal atomic part of name.

Some aspects of this operation are determined by the target context and its naming system. For example, XFN does not specify what happens if the named subcontext is not empty when the operation is invoked.

Get Reference to Context

This operation returns a reference to the supplied context object.

FN_ref_t *fn_ctx_get_ref(
    const FN_ctx_t *ctx,
    FN_status_t *status);

Get Syntax Attributes of Context

This operation returns the syntax attributes associated with the context named by name, relative to the context ctx.

FN_attrset_t *fn_ctx_get_syntax_attrs(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    FN_status_t *status);

This operation is different from other XFN attribute operations in that these syntax attributes could be obtained directly from the context. Attributes obtained through other XFN attribute operations might not be associated with the context; they might be associated with the reference of the context, rather than with the context itself (see Relationship to Naming Operations).

Destroy Context Handler

This operation destroys the context handle ctx and allows the implementation to free resources associated with the context handle. This operation does not affect the state of the context itself.

void fn_ctx_handle_destroy(FN_ctx_t *ctx);

Construct an Equivalent Name (Preliminary Specification)

Given the name of an object name relative to the context ctx, the operation returns an equivalent name for that object, relative to the same context ctx, that has leading_name as its initial atomic name. Two names are said to be equivalent if they have prefixes that resolve to the same context, and the parts of the names immediately following the prefixes are identical. For example, for user jsmith, the names “myself/service/calendar” is equivalent to “user/jsmith/service/calendar” when resolved relative to the Initial Context.

FN_composite_name_t *fn_ctx_equivalent_name(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const FN_string_t *leading_name,
    FN_status_t *status);

If an equivalent name cannot be constructed, the value 0 is returned and the status argument set appropriately.

Base Attribute Interface

This section describes the operations in the base attribute interface. The interfaces to the objects used in operations in this interface are described in Parameters Used in the Interface.

• XFN Attribute Model

• Relationship to Naming Operations

• Status Objects

• Single-Attribute Operations

• Multiple-Attribute Operations

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.

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);

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);

Get Multiple Attributes

Get one or more attributes associated with the object named name relative to the context ctx. If name is empty, the attributes associated with ctx are returned.

FN_multigetlist_t *fn_attr_multiget(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    const   FN_attrset_t *attr_ids,
    unsigned int follow_link,
    FN_status_t *status);
 
    FN_attribute_t *fn_multigetlist_next(
    FN_multigetlist_t *ml,
    FN_status_t *status);
 
void fn_multigetlist_destroy(   
    FN_multigetlist_t *ml);

The attributes returned are those specified in attr_ids. If the value of attr_ids is 0, all attributes associated with the named object are returned. Any attribute values in attr_ids provided by the caller are ignored; only the identifiers are relevant for this operation. Each attribute (identifier, syntax, and values) is returned one at a time using an enumeration scheme similar to that for listing a context. fn_attr_multi_get() initiates the enumeration process. It returns a handle to an FN_multigetlist_t object that can be used for subsequent fn_multigetlist_next() calls to enumerate the attributes requested.

The operation fn_multigetlist_next() returns the next attribute (identifier, syntax, and values) in the enumeration and updates ml to indicate the state of the enumeration. Successive calls to fn_multigetlist_next() using ml return successive attributes in the enumeration and further update the state of the enumeration.

The operation fn_multigetlist_destroy() frees the resources used during the enumeration. This operation can be invoked at any time to terminate the enumeration.

Implementations are not required to return all attributes requested by attr_ids. Some might choose to return only the attributes found successfully; such implementations might not necessarily return identifiers for attributes that could not be read.

Modify Multiple Attributes

Modify the attributes associated with the object named name, relative to ctx.

int fn_attr_multi_modify(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    const   FN_attrmodlist_t *mods,
    unsigned int follow_link,                                  
    FN_attrmodlist_t **unexecuted_mods,
    FN_status_t *status);

In the mods parameter, the caller specifies a sequence of modifications that are to be performed in order on the attributes. Each modification in the sequence specifies a modification operation code (shown in Table 2–1) and an attribute on which to operate.

If all the modifications were performed successfully, unexecuted_mods is a NULL pointer. If an error is encountered while performing the list of modifications, status indicates the type of error and unexecuted_mods is set to point to a list of unexecuted modifications. The contents of unexecuted_mods do not share any state with mods; items in unexecuted_mods are copies of items in mods and appear in the same order in which they were originally supplied in mods. The first operation in unexecuted_mods is the first one that failed, and the code in status applies to this modification operation in particular. If status indicates a failure and a NULL pointer is returned in unexecuted_mods, that means no modifications were executed.

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

   • Search the context named by name

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

   • Search 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 terminal 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);

Status Objects and Status Codes

The result statuses of operations in the context interface and the attribute interface are encapsulated in FN_status_t objects. The FN_status_t object contains information about how the operation completed: whether an error occurred in performing the operation, the nature of the error, and information that helps locate where the error occurred. If the error occurred while resolving an XFN link, the status object contains additional information about that error.

The status object contains several items of information as shown in Table 2–2.

Both the primary status code and the link status code are values of type unsigned int that are drawn from the same set of meaningful values. XFN reserves the values 0 through 127 for standard meanings. Currently, values and interpretations for the codes in Table 2–3 are determined by XFN.

Parameters Used in the Interface

• Composite Names

• References and Addresses

• Identifiers

• Strings

• Attributes and Attribute Values

• Attribute Sets

• Attribute-Modification Lists

This section gives an overview of the types of parameters that are passed and returned by operations in the base context and attribute interfaces. Manipulation of these objects using their corresponding interfaces does not affect their representation in the underlying naming system.

Changes to objects in the underlying naming system can only be effected through the use of the interfaces described in The Base Context Interface and Base Attribute Interface.

Composite Names

A composite name is represented by an object of type FN_composite_name_t. A composite name is a sequence of components, where each component is a string (of type FN_string_t) intended to contain a name from a single naming system. (See Syntax for a description of composite name syntax and structure.) Operations are provided to iterate over this sequence, modify it, and compare two composite names.

References and Addresses

A reference is represented by the type FN_ref_t. An object of this type contains a reference type and a list of addresses. The ordering in this list at the time of binding might not be preserved when the reference is returned upon lookup.

The reference type is represented by an object of type FN_identifier_t. The reference type is intended to identify the class of object referenced, but XFN does not dictate its precise use.

Each address in a reference is represented by an object of type FN_ref_addr_t. An address consists of an opaque data buffer and a type field, again of type FN_identifier_t. The address type is intended to identify the mechanism that should be used to reach the object using that address.

Multiple addresses in a single reference are intended to identify multiple communication endpoints for the same conceptual object. Multiple addresses can arise for various reasons; for example, because the object offers interfaces over more than one communication mechanism.

The client process must interpret the contents of the opaque buffers based on the type of the address and on the type of the reference. However, this interpretation is intended to occur below the application layer.

Most application developers should not be required to manipulate the contents of either address or reference objects themselves. These interfaces are generally used within service libraries.

Identifiers

Identifiers are used to identify reference types and address types in the reference and to identify attributes and their syntax in the attribute operations.

The FN_identifier_t type is used to represent an identifier. It consists of an unsigned integer, which determines the format of identifier, and the actual identifier, which is expressed as a sequence of octets.

XFN defines a small number of standard forms for identifiers, as shown in Table 2–4.

Strings

The FN_string_t type represents character strings in the XFN interface. It provides a layer of insulation from specific string representations. The FN_string_t operations contain operations for string comparison, substring searches, and manipulation. The FN_string_t type supports multiple code sets. In Solaris 2.5, FNS supports ISO 646.

Attributes and Attribute Values

An attribute is represented by the FN_attribute_t type, and contains:

• An attribute identifier (of type FN_identifier_t)

• A syntax (of type FN_identifier_t)

• A set of distinct values (each value is a sequence of octets of type FN_attrvalue_t)

Various operations allow the construction, destruction, and manipulation of an attribute.

Attribute Sets

An attribute set is a set of attribute objects with distinct attribute identifiers. Attribute sets are represented by the FN_attrset_t type.

There are operations to allow the construction, destruction, and manipulation of an attribute set.

Attribute-Modification Lists

Use an attribute-modification list to specify multiple modification operations to be performed on the attributes associated with a single named object.

An attribute-modification list is represented by the FN_attrmodlist_t type. It consists of an ordered list of attribute-modification specifiers. Each specifier contains an operation and an attribute object. The attribute's identifier indicates the attribute that is to be operated upon. How the attribute's values are used depends on the operation.

The operation specifier is one of the values described in Table 2–1. The operations should be done in the order in which they appear in the list.

Parameters Used in Extended Search (Preliminary Specification)

The types of objects used to specify the scope and details of an extended search operation:

• the search control operations (FN_search_control_t)

• the search filter expression (FN_search_filter_t)

Search Control

The FN_search_control_t object encapsulates the different options that the application can specify in controlling the scope and the return values of the extended search operation, fn_attr_ext_search() .

These options are:

• Scope of search. This determines which contexts and objects will be searched. The default is FN_SEARCH_ONE_CONTEXT.

• Follow links during search. This determines whether links encountered during the search will be followed. The initial resolution phase of the operation (the resolution up to the target context) always follow links. This option controls the following of links after reaching the target context.

  The default is to not follow links.

• Maximum names returned. This specifies the maximum number of names to be returned before terminating the search. A value of 0 indicates that the search is terminated only when all the context and objects specified by the scope have been searched.

  The default is to return all named objects found.

• Return reference. This determines whether the reference of the object is returned.

  The default is to not return the reference.

• Return attributes. This determines which attributes associated with the named object, if any, are returned.

  The default is to not return any attributes.

Search Filter

The fn_attr_ext_search() operation allows the search for named objects whose attributes satisfy a given filter expression. The filter is expressed in terms of logical expressions involving attribute identifiers and their values of named objects examined during the search. The filter is created from an expression string and a list of arguments that replace substitution tokens within the expression string.

BNF of Filter Expression

<FilterExpr> ::=  [ <Expr> ]
 <Expr> ::= <Expr> "or" <Expr>
    | <Expr> "and" <Expr>
    | "not" <Expr>
    | "(" <Expr> ")"
    | <Attribute> [ <Rel_Op> <Value> ]
    | <Ext>
 <Rel_Op> ::= "==" | "!=" | "<" | "<=" | ">" | ">=" | "~="
 <Attribute> ::= "%a"
 <Value> ::= <Integer>
    | "%v"
    | <Wildcarded_string>
 <Wildcarded_string> ::= "*"
    | <String>
    | {<String> "*"}+ [<String>]
    | {"*" <String>}+ ["*"]
 <String> ::= "`" { <Char> } * "`"
    | "%s"
 <Char> ::= <PCS> // See BNF in Section 4.1.2 for PCS definition
    | Characters in the repertoire of a string representation
 <Identifier> ::= "%i"
 <Ext> ::= <Ext_Op> "(" [Arg_List] ")"
 <Ext_Op> ::= <String> | <Identifier>
 <Arg_List> ::= <Arg> | <Arg> "," <Arg_List>
 <Arg> ::= <Value> | <Attribute> | <Identifier>

Specification of Filter Expression

The arguments to fn_search_filter_create() are a return status, an expression string, and a list of arguments. The string contains the filter expression with substitution tokens for the attributes, attribute values, strings and identifiers that are part of the expression. The remaining list of arguments contains the attributes and values in the order of appearance of their corresponding substitution tokens in the expression. The arguments are of types FN_attribute_t*, FN_attrvalue_t*, FN_string_t* or FN_identifier_t*.

Except when attributes appear as arguments in specially defined extended operations, any attribute values in an FN_attribute_t type of argument are ignored; only the attribute identifier and attribute syntax are relevant. The argument type expected by each substitution token is listed in Table 2–6.

Substitute Tokens in Search Filter Expressions

Precedence

The following precedence relations hold in the absence of parentheses, in the order of lowest to highest:

• or

• and

• not

• relational operators

These Boolean and relational operators are left associative.

Relational Operators

Table 2–7 contains descriptions of the relational operators. Comparisons and ordering are specific to the syntax or rules of the supplied attribute.

Locale (code set, language or territory) mismatches that occur during string comparisons and ordering operations are resolved in an implementation-dependent way. Relational operations that have ordering semantics may be used for strings of locales in which ordering is meaningful, but is not of general use in internationalized environments.

An attribute that occurs in the absence of any relational operator tests for the presence of the attribute.

Wildcarded Strings

A wildcarded string consists of a sequence of alternating wildcard specifiers and strings. The sequence can start with either a wildcard specifier or a string, and end with either a wildcard specifier or a string.

The wildcard specifier is denoted by the asterisk character (*) and means 0 or more occurrences of any character.

Wildcarded strings can be used to specify substring matches. Table 2–8 contains examples of wildcarded strings and their meaning.

Extended Operations

In addition to the relational operators, extended operators can be specified. All extended operators return either TRUE or FALSE. A filter expression can contain both relational and extended operations.

Extended operators are specified using an identifier (FN_identifier_t) or a string. If the operator is specified using a string, the string is used to construct an identifier of format FN_ID_STRING. Identifiers of extended operators and signatures of the corresponding extended operations, as well as their suggested semantics, are registered with X/Open.

The extended operations shown in Table 2–9 are currently defined:

The operation returns TRUE if any of the address types in the reference of the object is equal to the supplied identifier. Support and exact semantics of extended operations are context-specific. If a context does not support an extended operation, or if the filter expression supplies the extended operation with either an incorrect number or type of arguments, the error FN_E_SEARCH_INVALID_OP is returned. FN_E_OPERATION_NOT_SUPPORTED is returned when fn_attr_ext_search() is not supported.

Table 2–10 contains examples of filter expressions that contain extended operations.

Parsing Compound Names

• Syntax Attributes

• XFN Standard Syntax Model

Because most applications treat names as opaque data, most clients of the XFN interface do not need to parse compound names from specific naming systems. When an application (such as a browser) needs to do this, however, it can use the FN_compound_name_t object.

Syntax Attributes

Each context has an associated set of syntax-related attributes. The attribute fn_syntax_type (FN_ID_STRING format) identifies the naming syntax supported by the context. The value “standard” (ASCII attribute syntax) in the fn_syntax_type attribute specifies that the context supports the XFN standard syntax model that is by default supported by the FN_compound_name_t object.

Implementations can choose to support other syntax types in addition to or in place of the XFN standard syntax model, in which case the value of the fn_syntax_type attribute is set to an implementation-specific string and different or additional syntax attributes are in the set.

Syntax attributes of a context can be generated automatically by a context, in response to fn_ctx_get_syntax_attrs(), or can be created and updated using the attribute operations. This is implementation dependent.

XFN Standard Syntax Model

Each naming system in an XFN federation has a naming convention. XFN defines a standard model of expressing compound name syntax that covers a large number of specific name syntaxes. This model is expressed in terms of syntax properties of the naming convention and it uses XFN attributes to describe properties of the syntax.

Unless otherwise qualified, the syntax attributes described in this section have attribute identifiers that use the FN_ID_STRING format. This does not specify or restrict the use of other formats for identifiers of additional syntax attributes supported by specific implementations.

In the XFN standard syntax model, these attributes are interpreted according to the following rules:

1. In a string without quotes or escapes, any instance of the separator string delimits two atomic names.

2. A separator, quotation mark, or escape string is escaped if preceded immediately (on the left) by the escape string.

3. A non-escaped begin-quote that precedes a component must be matched by a non-escaped end-quote at the end of the component. Quotes embedded in nonquoted names are treated as simple characters and do not need to be matched. An unmatched quotation fails with the status code FN_E_ILLEGAL_NAME.

4. If there are multiple values for begin-quote and end-quote, a specific begin-quote value must be matched with its corresponding end-quote value.

5. When the separator appears between a (nonescaped) begin-quote and the end-quote, it is ignored.

6. When the separator is escaped, it is not treated as a separator. An escaped begin-quote or end-quote string is not treated as a quotation mark. An escaped escape string is not treated as an escape string.

7. A non-escaped escape string appearing within quotes is interpreted as an escape string. This can be used to embed an end-quote within a quoted string.

8. An escape string that precedes a character other than an escape string, a begin-quote or an end-quote is consumed (in other words, escaping a non-meta character returns the non-meta character itself).

After constructing a compound name from a string, the resulting component atoms have one level of escape strings and quotations interpreted and consumed.

Code set mismatches that occur during the construction of the compound name's string form are resolved in an implementation-dependent way. When an implementation discovers that a compound name has components with incompatible code sets, it returns the error code FN_E_INCOMPATIBLE_CODE_SETS. When an implementation discovers that a compound name has components with incompatible language or territory locale information, it returns the error code FN_E_INCOMPATIBLE_LOCALES.

Table 2–11 lists all the XFN standard syntax model attributes.

Compound Names

The FN_compound_name_t type is used to represent a compound name.

The FN_compound_name_t object has associated operations for applications to process compound names that conform to the XFN standard syntax model of expressing compound name syntax. Operations are provided to iterate over the list of atomic components of the name, modify the list, and compare two compound names.

An FN_compound_name_t object is constructed using the operation fn_compound_name_from_attrset(), with arguments consisting of a string name and an attribute set that contains the attribute “fn_syntax_type” with the value “standard.”