Interfaces for Writing XFN Applications
This chapter describes the client programming interfaces for XFN. Additional information on the XFN interfaces is available in the man pages.
XFN Interface Overview
The XFN client interface consists of the base context interface, the base attribute interface, the extended attribute interface, and some supporting interfaces.
The base context interface provides the basic operations for naming, such as binding a name to a reference, looking up the reference bound to a name, and unbinding a name.
The base attribute interface provides operations to examine and modify attributes associated with named objects.
The extended attribute interface provides operations to search and create objects in the namespace with attributes.
The supporting interfaces contain:
Operations on the status object and status codes used in the context and attribute operations
Abstract data types that represent objects passed to and returned from the context and attribute operations, such as composite names, references, and attributes
A standard model and operations for parsing compound names whose syntax is specific to a naming system. These are of interest primarily to service implementers
Operations for manipulating objects that are used to specify the criteria of extended search operations
"API Usage Model"summarizes how an application typically uses the programming interface.
Interface Conventions
The XFN interface is presented in ISO standard C, which is equivalent to ANSI standard C. The symbols defined by the interface are prefixed by fn or FN, for federated naming.
The FN_ prefix is used for both data types and predefined constants.
In addition, data types have a _t suffix, such as FN_ref_t. Predefined constants appear in all-uppercase characters, such as FN_ID_STRING.
The fn_ prefix is used for function names. Names of functions in the base context interface have the prefix fn_ctx_, such as fn_ctx_lookup. Names of functions in the base attribute interface have the prefix fn_attr_, such as fn_attr_get.
Usage
Include the XFN header file in your code.
#include <xfn/xfn.h> |
Include the XFN library when you compile.
cc -o program_name file1.c file2.c -lxfn |
Abstract Data Types
Except for FN_attrvalue_t and FN_identifier_t, the types defined in the interface hide their actual data representation from the client. The client performs every operation on an object of one of these types through a well-defined interface for that data type.
When the client accesses these objects, the client refers to the objects solely through a handle to an object. Operations are provided to create objects of each type and to destroy them. The creation operation returns a handle to the new object. The destroy operation releases all resources associated with the object.
The only information about this handle revealed to the client is that it is a pointer type. The client cannot assume what this handle points to. In particular, the handle might not point directly to the memory containing the object's actual state.
The value 0 is defined for all pointer types. The functions that return handles in the interface return the value 0 as an indication of failure. The values 0 and NULL are equivalent.
Memory-Management Policies
The following memory-management policies are used for all client interfaces described in this chapter:
When a function returns a non-const pointer to an object, the client "owns" the object. The client can alter the object and is responsible for freeing the space allocated to it when the object is no longer required.
When a function returns a const pointer to an object, the service "owns" the object. The client must neither modify the object in any way, nor free the space allocated to it. If the client needs to control a copy, it must make one for itself.
When a function takes a non-const parameter that is passed by reference, the service "borrows" the object during the function's execution. It can modify the object during this period, but it does not retain any reference to the object beyond this period.
When a function takes a const parameter that is passed by reference, the service reads but does not modify the object. The service does not keep any reference to the object beyond the period of the function's execution.
The Base Context Interface
This section describes the operations in the base context interface. The interfaces to the objects used in the operations are described in "Parameters Used in the Interface".