The call to fn_attr_ext_search() initiates the search and, if successful, returns a handle to an FN_ext_searchlist_t object, esl, that is used to enumerate the names of the objects that satisfy the filter.
fn_ext_searchlist_next() returns the next name, and optionally, its reference and attributes, in the enumeration identified by esl. The name returned is a composite name, to be resolved relative to the starting context for the search. The starting context is the context named name relative to ctx, unless the scope of the search is only the named object. If the scope of the search is only the named object, the terminal atomic name is returned. Successive calls to fn_ext_searchlist_next() using esl return successive names, and optionally, references and attributes, in the enumeration and further update the state of the enumeration.
fn_ext_searchlist_destroy() releases resources used during the search and enumeration. It can be called at any time to terminate the enumeration.
Object Creation with Attributes
fn_attr_bind fn_attr_create_subcontext |
At times it is useful or necessary to associate attributes with an object at the time the object is created. The XFN extended attribute interface contains functions that provide these capabilities. The two functions in this interface, fn_attr_bind() and fn_attr_create_subcontext(), are analogous to their counterparts in the base context interface, fn_ctx_bind() and fn_ctx_create_subcontext(), respectively, except that the versions in the extended attribute interface allow an extra parameter for specifying attributes to be associated with the new binding.
Bind with Attributes
This operation binds the supplied reference ref to the supplied composite name name relative to ctx, and associates the attributes specified in attrs with the named object. The binding is made in the target context--that context named by all but the terminal atomic part of name. The operation binds the terminal atomic part of name to the supplied reference in the target context. The target context must already exist.
int fn_attr_bind(
FN_ctx_t *ctx,
const FN_composite_name_t *name,
const FN_ref_t *ref,
unsigned int exclusive,
FN_status_t *status);
|
The value of exclusive determines what happens if the terminal atomic part of the name is already bound in the target context. If exclusive is non-zero and name is already bound, the operation fails. If exclusive is zero, the new binding replaces any existing binding, and attrs, if not NULL, replaces any existing attributes associated with the named object.
Create Subcontext with Attributes
This operation creates a new XFN context of the same type as the target context--that named by all but the terminal atomic component of name--and binds it to the supplied composite name name. In addition, attributes given in attrs are associated with the newly created context. The target context must already exist. The new context is created and bound in the target context using the terminal atomic name in name. The operation returns a reference to the newly created context.
FN_ref_t *fn_attr_create_subcontext(
FN_ctx_t *ctx,
const FN_composite_name_t *name,
const FN_attrset_t *attrs,
FN_status_t *status);
|
Status Objects and Status Codes
The result statuses of operations in the context interface and the attribute interface are encapsulated in FN_status_t objects. The FN_status_t object contains information about how the operation completed: whether an error occurred in performing the operation, the nature of the error, and information that helps locate where the error occurred. If the error occurred while resolving an XFN link, the status object contains additional information about that error.
The status object contains several items of information as shown in Table 2-2.
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-3are determined by XFN.
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"and "Base Attribute Interface".