This chapter describes the client programming interfaces for XFN. Additional information on the XFN interfaces is available in the man pages.
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.
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.
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 |
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.
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.
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.
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.
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.
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).
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 |
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.
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.
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 |
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); |
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.
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.
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.
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.
fn_ctx_bind fn_ctx_unbind fn_ctx_rename |
Bindings can be added, overwritten, removed, or renamed.
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.
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.
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.
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.
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.
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.
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); |
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).
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); |
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.
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.
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:
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.
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.
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.
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().
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); |
Operation Code |
Meaning |
---|---|
Add an attribute with given attribute identifier and set of values. If an attribute with this identifier already exists, replace the set of values with those in the given set. The set of values can be empty if the target naming system permits. |
|
Add an attribute with the given attribute identifier and set of values. The operation fails if an attribute with this identifier already exists. The set of values can be empty if the target naming system permits. |
|
Add the given values to those of the given attribute (resulting in the attribute having the union of its prior value set with the given set). Create the attribute if it does not already exist. The set of values can be empty if the target naming system permits. |
|
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. |
|
Remove the given values from those of the given attribute (resulting in the attribute having the set difference of its prior value set and the given set). This succeeds even if some of the given values are not in the set of values that the attribute has. In naming systems that require an attribute to have at least one value, removing the last value removes the attribute as well. |
This set of operations allows the caller to obtain attribute values associated individually with a single attribute.
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.
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.
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 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 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.
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.
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.
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.
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:
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.
Whether XFN links are followed during the search
A limit on the number of names returned
Whether the reference associated with the named object is returned
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.
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.
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.
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); |
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.
Table 2–2 Status Object
Information Type |
Description |
---|---|
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 might have been successful beyond this point, but the error can 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. |
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 2–3 are determined by XFN.
Table 2–3 Status Codes
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.
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.
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 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.
Table 2–4 XFN Identifier Formats
Identifier Format |
Description |
---|---|
The identifier is an ASCII string (ISO 646). |
|
The identifier is an OSF DCE UUID in string representation. See the X/Open DCE RPC (ISBN 1-872630-95-2). |
|
The identifier is an ISO OID in ASN.1 dot-separated integer list string format. See the ISO ASN.1 (ISO 8824). |
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.
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.
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.
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.
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)
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.
Scope |
Meaning |
---|---|
FN_SEARCH_NAMED_OBJECT |
Search just the given named object. |
FN_SEARCH_ONE_CONTEXT |
Search just the given context. |
FN_SEARCH_SUBTREE |
Search given context and all its subcontexts. |
FN_SEARCH_CONSTRAINED_SUBTREE |
Search given context and its subcontexts as constrained by the context-specific policy in place at the named 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.
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.
<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> |
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.
Table 2–6 Substitute Tokens in Search Filter Expressions
Token |
Argument Type |
---|---|
%a |
FN_attribute_t* |
%v |
FN_attrvalue_t* |
%s |
FN_string_t* |
%i |
FN_identifier_t* |
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.
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.
Table 2–7 Relational Operators in Search Filter Expressions
Operator |
Meaning |
---|---|
== |
The sub-expression is TRUE if at least one value of the specified attribute is equal to the supplied value. |
!= |
The sub-expression is TRUE if no values of the specified attribute equal the supplied value. |
>= |
The sub-expression is TRUE if at least one value of the attribute is greater than or equal to the supplied value. |
> |
The sub-expression is TRUE if at least one value of the attribute is greater then the supplied value. |
<= |
The sub-expression is TRUE if at least one value of the attribute is less than or equal to the supplied value. |
< |
The sub-expression is TRUE if at least one value of the attribute is less than the supplied value. |
~= |
The sub-expression is TRUE if at least one value of the specified attribute matches the supplied value according to some context-specific approximate matching criterion. This criterion must subsume strict equality. |
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.
Table 2–8 Examples of Wildcarded Strings
Wildcarded String |
Meaning |
---|---|
* |
Any string |
`tom' |
The string tom |
`harv'* |
Any string starting with harv |
*'ing' |
Any string ending with ing |
`a'*'b' |
Any string starting with a and ending with b |
`a*b' |
The string a*b |
`jo'*'ph'*'ne'*'er' |
Any string starting with jo, and containing the substring ph, and which contains the substring ne in the portion of the string following ph, and which ends with er |
%s* |
Any string starting with the supplied string |
`bix'*%s |
Any string starting with bix and ending with the supplied string |
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:
Table 2–9 Extended Operations
`name'(<Wildcarded String>) |
The identifier for this operation is name(FN_ID_STRING). The argument to this operation is a wildcarded string. The operation returns TRUE if the name of the object matches the supplied wildcarded string. |
`reftype'(%i) |
The identifier for this operation is reftype (FN_ID_STRING). The argument to this operation is an identifier. The operation returns TRUE if the reference type of the object is equal to the supplied identifier. |
`addrtype'(%i) |
The identifier for this operation is addrtype(FN_ID_STRING). The argument to this operation is an identifier. |
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.
Table 2–10 Extended Operations in Search Filter Expressions
Expression |
Meaning |
---|---|
`name'(`bill'*) |
Evaluates to TRUE if the name of the object starts with bill. |
%i(%a, %v) |
Evaluates to result of applying the specified operation to the supplied arguments. |
(%a == %v) and `name'(`joe'*) |
Evaluates to TRUE if the specified attribute has the given value and if the name of the object starts with joe. |
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.
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.
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.
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.
Table 2–11 XFN Syntax Attributes
Attribute Identifier |
Attribute Value |
---|---|
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. |
|
ax_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). |
Its value is the separator string for this name syntax. This attribute is required unless the fn_syntax_direction is flat. |
|
If present, its value is the escape string for this name syntax. |
|
If present, it indicates that names differing 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. |
|
If present, its value is one of the begin-quote strings for this syntax. If fn_std_syntax_end_quote1 is absent but fn_std_syntax_begin_quote1 is present, the quote-string specified in fn_std_syntax_begin_quote1 is used as both the begin and end quote-strings. If fn_std_syntax_end_quote1 is present but fn_std_syntax_begin_quote1 is absent, the quote-string specified in fn_std_syntax_end_quote1 is used as both the begin and end-quote-strings. |
|
If present, its value is the end-quote string for this syntax. If fn_std_syntax_end_quote1 is absent but fn_std_syntax_begin_quote1 is present, the quote-string specified in fn_std_syntax_begin_quote1 is used as both the begin and end quote-strings. If fn_std_syntax_end_quote1 is present but fn_std_syntax_begin_quote1 is absent, the quote-string specified in fn_std_syntax_end_quote1 is used as both the begin and end-quote-strings. |
|
If present, its value is one of the begin-quote strings for this syntax. If fn_std_syntax_end_quote2 is absent but fn_std_syntax_begin_quote2 is present, the quote-string specified in fn_std_syntax_begin_quote2 is used as both the begin and end quote-strings. If fn_std_syntax_end_quote2 is present but fn_std_syntax_begin_quote2 is absent, the quote-string specified in fn_std_syntax_end_quote2 is used as both the begin and end-quote-strings. |
|
If present, its value is the end-quote string for this syntax. If fn_std_syntax_end_quote2 is absent but fn_std_syntax_begin_quote2 is present, the quote-string specified in fn_std_syntax_begin_quote2 is used as both the begin and end quote-strings. If fn_std_syntax_end_quote2 is present but fn_std_syntax_begin_quote2 is absent, the quote-string specified in fn_std_syntax_end_quote2 is used as both the begin and end-quote-strings. |
|
If present, its value is the attribute-value assertion separator string for this syntax. |
|
If present, its value is the attribute type-value separator string for this syntax. |
|
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). |
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.”