XFN Interface Overview

The XFN client interface consists of the base context interface, the base attribute interface, and a number of 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 supporting interfaces contain

• Operations on the status object and status codes used in the context and attribute operations.
• A number of abstract data types defined to 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 primary interest to service implementers.

"API Usage Model" on page 22 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

The XFN header file must be included in code as shown for compilation.

#include <xfn/xfn.h>

The XFN library must be included in the link line as shown.

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 may 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 may 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 period of the function's execution. It may modify the object during this period, but it does not retain any reference to the object passed in 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" on page 153.

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 may 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, and then
• 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" on page 15.

Requirements for Supporting the Context Operations

The lookup operation fn_ctx_lookup() must be supported by all contexts. Contexts may indicate that they do not support other operations by returning an FN_E_OPERATION_NOT_SUPPORTED status code (see Table 10-3 on page 151).

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 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" on page 163.

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" on page 150. All status objects are handled in this manner for each operation in the base context interface; this will not be restated in the individual operation descriptions.

Getting Context Handles

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

Construct Handle to Initial Context FN_ctx_t *fn_ctx_handle_from_initial(FN_status_t *status);

This operation returns a handle to the caller's initial context. On successful return, the context handle points to a context containing the bindings described in "Initial Context Bindings for Naming Within the Enterprise" on page 54 and "Initial Context Bindings for Global Naming" on page 62.

Construct Context Handle From Reference

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

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

Lookup and List Contexts

Lookup

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

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

List Names 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,
FN_status_t *status);

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

The call to fn_ctx_list_names() initiates the enumeration process for the target context. It returns an FN_nameslist_t object that can be used 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 may be invoked at any time to terminate the enumeration.

The names enumerated using the list names operations are not ordered in any way. There is no guaranteed relation between the order in which names are added to a context and the order 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 may not necessarily invalidate the enumeration handle that the client holds for that context. If the enumeration handle remains valid, the update may or may not be visible to the client.

List Bindings

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,
    FN_status_t *status);

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. name must name a context. If the intent is to list the contents of ctx, name should be an empty composite name.

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

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

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

The normal fn_ctx_lookup() operation follows all XFN links encountered, including any 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

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

Bind

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

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.

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 the intent is to reserve a name using the fn_ctx_bind() operation, a reference containing no address should be bound. This reference may be naming service-specific or it may be the conventional NULL reference.

Unbind

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

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

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

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

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.

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

Contexts can be created or destroyed.

Create Subcontext

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

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.

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

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

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

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.

Other Context Operations

Get Reference to Context

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

This operation returns a reference to the supplied context object.

Get Syntax Attributes of Context

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

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

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 may not necessarily be associated with the context; they may be associated with the reference of the context, rather than the context itself (see "Relationship to Naming Operations" on page 144).

Destroy Context Handle void fn_ctx_handle_destroy(FN_ctx_t *ctx);

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.

The 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" on page 153.

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 may be used to examine and modify the settings of attributes associated with existing named objects. These objects may 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 may vary widely. Some naming systems may not support any attribute operations. Other naming systems may support only read operations or operations on attributes whose identifiers are in some fixed set. A naming system may limit attributes to have a single value or may require at least one value. Some naming systems may only associate attributes with context objects, while others may allow associating attributes with noncontext 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 may not necessarily 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. The reason is that in some attribute models, attributes are associated 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 relationship between the attributes and the reference associated with a given name. Some naming systems may 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 the use of 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" on page 150. 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

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

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

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_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 are expected to be too large to be returned in a single invocation of

fn_attr_get().

Modify Attribute

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

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.

Table 10-1

Operation Code	Meaning
FN_ATTR_OP_ADD	Add an attribute with given attribute identifier and set of values. If an attribute with this identifier exists already, replace the set of values with those in the given set. The set of values may 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 exists already. The set of values may 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 set given). Create the attribute if it does not exist already. The set of values may 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 set given). 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 will remove the attribute as well.

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

FN_valuelist_t *fn_attr_get_values(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    const   FN_identifier_t *attribute_id,
    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,
    FN_status_t *status);

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 are obtained.

This interface should be used instead of fn_attr_get() if the combined size of the 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 may be invoked at any time in order to terminate the enumeration.

Multiple-Attribute Operations

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

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

Get Attribute Identifiers

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

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.

Get Multiple Attributes

FN_multigetlist_t *fn_attr_multiget(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    const   FN_attrset_t *attr_ids,
    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,
    FN_status_t *status);

This set of operations gets 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.

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 may be invoked at any time to terminate the enumeration.

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

Modify Multiple Attributes

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

This operation modifies the attributes associated with the object named name, relative to ctx.

In the mods parameter, the caller specifies a sequence of modifications that are to be done in order on the attributes. Each modification in the sequence specifies a modification operation code (shown in Table 10-1 on page 146) 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 indicates no modifications were executed.

Status Objects and Status Codes

The result status of operations in the context interface and the attribute interface is encapsulated in an FN_status_t object. This 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 consists of several items of information.

Table 10-2

Information Type	Description
Primary status code	An unsigned int code describing the disposition of the operation.
Resolved name	In the case of a failure during the resolution phase of the operation, this is the leading portion of the name that was resolved successfully. Resolution may have been successful beyond this point, but the error might not be pinpointed further.
Resolved reference	The reference to which the resolved name is bound.
Remaining name	The remaining unresolved portion of the name.
Diagnostic message	Any diagnostic message returned by the context implementation.
Link status code	If an error occurs while resolving an XFN link, the primary status code has the value FN_E_LINK_ERROR, and this code describes the error that occurred while resolving the XFN link.
Resolved link name	In the case of a link error, this contains the resolved portion of the name in the XFN link.
Resolved link reference	In the case of a link error, this contains the reference to which the resolved link name is bound.
Remaining link name	In the case of a link error, this contains the remaining resolved portion of the name in the XFN link.
Link diagnostic message	Any diagnostic message related to the resolution of the link.

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 10-3 are determined by XFN.

Table 10-3

Code	Meaning
FN_SUCCESS	The operation succeeded.
FN_E_ATTR_NO_PERMISSION	The caller did not have permission to perform the attempted attribute operation.
FN_E_ATTR_VALUE_REQUIRED	The operation attempted to create an attribute without a value, and the specific naming system does not allow this.
FN_E_AUTHENTICATION_FAILURE	The identity of the client principal could not be verified.
FN_E_COMMUNICATION_FAILURE	An error occurred in communicating with one of the contexts involved in the operation.
FN_E_CONFIGURATION_ERROR	A problem was detected that indicated an error in the installation of the XFN interfaces.
FN_E_CONTINUE	The operation should be continued using the remaining name and the resolved reference returned in the status.
FN_E_CTX_NO_PERMISSION	The client did not have permission to perform the operation.
FN_E_CTX_NOT_EMPTY	Applies only to fn_ctx_destroy_subcontext(). The naming system required that the context be empty before its destruction, and it was not empty.
FN_E_CTX_UNAVAILABLE	Service could not be obtained from one of the contexts involved in the operation. This may be because the naming system is busy or is not providing service. In some implementations this may not be distinguished from a communication failure.
FN_E_ILLEGAL_NAME	The name supplied to the operation was not a well-formed composite name, or one of the component names was not well formed according to the syntax of the naming systems involved in its resolution.
FN_E_INCOMPATIBLE_CODE_SETS	The operation involved character strings of incompatible code sets or the supplied code set is not supported by the implementation.
FN_E_INSUFFICIENT_RESOURCES	Either the client or one of the involved contexts could not obtain sufficient resources (on memory, file descriptors, communication ports, stable media space, for example) to complete the operation successfully.

Table 10-3 (Continued)

Code	Meaning
FN_E_INVALID_ATTR_VALUE	One of the values supplied was not in the appropriate form for the given attribute.
FN_E_INVALID_ENUM_HANDLE	The enumeration handle supplied was invalid, either because it was from another enumeration, because an update operation occurred during the enumeration, or for some other reason.
FN_E_INVALID_SYNTAX_ATTRS	The syntax attributes supplied are invalid or insufficient to fully specify the syntax.
FN_E_LINK_ERROR	An error occurred while resolving an XFN link encountered during resolution of the supplied name.
FN_E_LINK_LOOP_LIMIT	A nonterminating loop (cycle) in the resolution is suspected. This arises due to XFN links encountered during the resolution of a supplied composite name. This code indicates either the definite detection of such a cycle, or that resolution exceeded an implementation-defined limit on the number of XFN links allowed for a single operation invoked by the caller (and thus a cycle is suspected).
FN_E_MALFORMED_LINK	A malformed link reference was encountered. For fn_ctx_lookup_link(), the name supplied resolved to a reference that was not a link.
FN_E_MALFORMED_REFERENCE	A context object could not be constructed from the supplied reference because the reference was not properly formed.
FN_E_NAME_IN_USE	(Only for operations that bind names.) The supplied name was already in use.
FN_E_NAME_NOT_FOUND	Resolution of the supplied composite name proceeded to a context in which the next atomic component of the name was not bound.
FN_E_NO_SUCH_ATTRIBUTE	The object does not have an attribute with the given identifier.
FN_E_NO_SUPPORTED_ADDRESS	A context object could not be constructed from a particular reference. The reference contained no address type over which the context interface was supported.
FN_E_NOT_A_CONTEXT	Either one of the intermediate atomic names did not name a context, and resolution could not proceed beyond this point, or the operation required that the caller supply the name of a context, and the name did not resolve to a reference for a context
FN_E_OPERATION_NOT_SUPPORTED	The operation attempted is not supported.
FN_E_PARTIAL_RESULT	The operation attempted is returning a partial result.

Table 10-3 (Continued)

Code	Meaning
FN_E_SYNTAX_NOT_SUPPORTED	The syntax type specified is not supported.
FN_E_TOO_MANY_ATTR_VALUES	The operation attempted to associate more values with an attribute than the naming system supported.
FN_E_UNSPECIFIED_ERROR	An error occurred that could not be classified by any of the other error codes.

Parameters Used in the Interface

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" on page 135 and "The Base Attribute Interface" on page 143.

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" on page 159 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 may 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 applications developers should not have to manipulate the contents of either address or reference objects themselves. These interfaces would generally be 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 10-4.

Table 10-4

Identifier Format	Description
FN_ID_STRING	The identifier is an ASCII string (ISO 646).
FN_ID_DCE_UUID	The identifier is an OSF DCE UUID in string representation. See the X/Open DCE RPC (ISBN 1-872630-95-2).
FN_ID_ISO_OID_STRING	The identifier is an ISO OID in ASN.1 dot-separated integer list string format. See the ISO ASN.1 (ISO 8824).
FN_ID_ISO_OID_BER	The identifier is an ISO OID in ASN.1 Basic Encoding Rules (BER) format. See the ISO BER (ISO 8825).

Strings

The FN_string_t type is used to represent 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 has an attribute identifier, a syntax, and a set of distinct values. An attribute is represented by the FN_attribute_t type. The attribute identifier and its syntax are specified using an FN_identifier_t. Each value is a sequence of octets, represented by the FN_attrvalue_t type.

There are operations to 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

An attribute-modification list allows you 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. An attribute-modification specifier consists of an operation and an attribute object. The attribute's identifier indicates the attribute that is to be operated upon. The attribute's values are used in a manner depending on the operation. The operation specifier is one of the values described in Table 10-1 on page 146. The operations are to be done in the order in which they appear in the list.

Parsing Compound Names

Most applications treat names as opaque data; therefore, the majority of clients of the XFN interface will not need to parse compound names from specific naming systems. Some applications, however, such as browsers, need such capabilities. For these applications, XFN provides support in the form of 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 may 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 would be set to an implementation-specific string and different or additional syntax attributes would be in the set.

Syntax attributes of a context may be generated automatically by a context, in response to fn_ctx_get_syntax_attrs(), or may 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:

• In a string without quotes or escapes, any instance of the separator string delimits two atomic names.
• A separator, quotation mark, or escape string is escaped if preceded immediately (on the left) by the escape string.
• 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.
• 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.
• When the separator appears between a (nonescaped) begin-quote and the end-quote, it is ignored.
• 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.
• 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.

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.

Table 10-5 lists all the XFN standard syntax model attributes.

Table 10-5

Attribute Identifier	Attribute Value
fn_syntax_type	Its value is the ASCII string "standard" if the context supports the XFN standard syntax model. Its value is an implementation-specific value if another syntax model is supported.
fn_syntax_direction	Its value is an ASCII string, one of "left-to-right," "right-to-left," or "flat." This determines whether the order of components in a compound name string goes from left-to-right, right-to-left, or whether the namespace is flat (that is, not hierarchical, with all names atomic)
fn_std_syntax_separator	Its value is the separator string for this name syntax. This attribute is required unless the fn_syntax_direction is flat.
fn_std_syntax_escape	If present, its value is the escape string for this name syntax.
fn_std_syntax_case_insensitive	If present, it indicates that names that differ only in case are considered identical. If this attribute is absent, it indicates that case is significant. If a value is present, it is ignored.
fn_std_syntax_begin_quote	If present, its value is the begin-quote string for this syntax.
fn_std_syntax_end_quote	If present, its value is the end-quote string for this syntax.
fn_std_syntax_ava_separator	If present, its value is the attribute-value assertion separator string for this syntax.
fn_std_syntax_typeval_separator	If present, its value is the attribute type-value separator string for this syntax.
fn_std_syntax_code_sets	If present, its value identifies the code sets of the string representation for this syntax. Its value consists of a structure containing an array of code sets supported by the context; the first member of the array is the preferred code set of the context. The values for the code sets are defined in the X/Open code set registry currently defined in DCE RFC 40.1. If this attribute is not present, or if the value is empty, the default code set is ISO 646 (same encoding as ASCII).
fn_std_syntax_locale_info	If present, its value identifies locale information, such as character set information, of the string representation for this syntax. The interpretation of its value is implementation dependent.