| |
| XFN Interface Library Functions | fn_attr_ext_search(3XFN) |
| | fn_attr_ext_search, FN_ext_searchlist_t, fn_ext_searchlist_next, fn_ext_searchlist_destroy - search for names in
the specified context(s) whose attributes satisfy the filter |
SYNOPSIS
| |
#include <xfn/xfn.h>
FN_ext_searchlist_t *fn_attr_ext_search(FN_ctx_t *ctx, const FN_composite_name_t *name, const FN_search_control_t *control, const FN_search_filter_t *filter, 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); |
| |
This set of operations is used to list names of objects whose attributes satisfy the filter expression. The references to which these names are bound and specified attributes and their values may
also be returned.
control encapsulates the option settings for the search. These options are:
- the scope of the search
- whether XFN links are followed
- a limit on the number of names returned
- whether references and specific attributes associated with the named objects that satisfy the filter are returned
The scope of the search is one of:
- the object named name relative to the context ctx
- the context named name relative to the context ctx
- the context named name relative to the context ctx,
and its subcontexts
or
- the context named name relative to the context ctx, and a context implementation-defined set of subcontexts
If the value of control is 0, default control option settings are used. The default settings are:
- scope is search named context
- links are not followed
- all names of objects that satisfy the filter are returned
- references and attributes are not returned
The FN_search_control_t type is described in FN_search_control_t(3XFN).
The filter expression filter in fn_attr_ext_search() is evaluated against the attributes of the objects bound in the scope of the search. The filter evaluates
to either TRUE or FALSE. The names and, optionally, the references and attributes of objects whose attributes satisfy the filter are enumerated.
If the value of filter is 0, all names within the search scope are enumerated. The FN_search_filter_t type is described in FN_search_filter_t(3XFN).
The call to fn_attr_ext_search() initiates the search process. It returns a handle to an FN_ext_searchlist_t object that is used to enumerate the names of the
objects that satisfy the filter.
The operation fn_ext_searchlist_next() returns the next name in the enumeration identified by esl; it also updates esl to indicate
the state of the enumeration. If the reference to which the name is bound was requested, it is returned in returned_ref. Requested attributes associated with the name are returned
in returned_attrs; each attribute consists of an attribute identifier, syntax, and value(s). Successive calls to fn_ext_searchlist_next() using esl return successive names and, optionally, their references and attributes, in the enumeration; these calls further update the state of the enumeration.
The names that are returned are composite names, to be resolved relative to the starting context for the search. This 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 in name
is returned.
fn_ext_searchlist_destroy() releases resources used during the enumeration. This may be invoked at any time to terminate the enumeration.
|
| |
fn_attr_ext_search() returns a pointer to an FN_ext_searchlist_t object if the search is successfully initiated; it returns a NULL
pointer if the search cannot be initiated or if no named object with attributes whose values satisfy the filter expression is found.
fn_ext_searchlist_next() returns a pointer to an FN_composite_name_t object (see FN_composite_name_t(3XFN)) that is the next name in the enumeration; it returns a NULL pointer if no more names can be returned. If returned_attrs is a NULL pointer, no attributes are returned; otherwise, returned_attrs contains the attributes associated with the
named object, as specified in the control parameter to fn_attr_ext_search(). If returned_ref is a NULL pointer, no reference
is returned; otherwise, if control specified the return of the reference of the named object, that reference is returned in returned_ref.
In the case of a failure, these operations return in the status argument a code indicating the nature of the failure.
|
| |
If successful, fn_attr_ext_search() returns a pointer to an FN_ext_searchlist_t object and sets status to FN_SUCCESS.
fn_attr_ext_search() returns a NULL pointer when no more names can be returned. status is set in the following way:
-
FN_SUCCESS
- A named object could not be found whose attributes satisfied the
filter expression.
-
FN_E_NOT_A_CONTEXT
- The object named for the start of the search was not a context and the search scope was the given context
or the given context and its subcontexts.
-
FN_E_SEARCH_INVALID_FILTER
- The filter could not be evaluated TRUE or FALSE, or there was some other problem with the filter.
-
FN_E_SEARCH_INVALID_OPTION
- A supplied search control option could not be supported.
-
FN_E_SEARCH_INVALID_OP
- An operator in the filter expression is not supported or, if the operator is an extended operator,
the number of types of arguments supplied does not match the signature of the operation.
-
FN_E_ATTR_NO_PERMISSION
- The caller did not have permission to read one or more of the attributes specified in the filter.
-
FN_E_INVALID_ATTR_VALUE
- A value type in the filter did not match the syntax of the attribute against which it was being
evaluated.
Other status codes are possible as described in FN_status_t(3XFN) and xfn_status_codes(3XFN).
Each successful call to fn_ext_searchlist_next() returns a name and, optionally, its reference in returned_ref and requested attributes in returned_attrs. status is set in the following way:
-
FN_SUCCESS
- All requested attributes were returned successfully with the name.
-
FN_E_ATTR_NO_PERMISSION
- The caller did not have permission to read one or more of the requested attributes.
-
FN_E_INVALID_ATTR_IDENTIFIER
- A requested attribute identifier was not in a format acceptable to the naming system, or
its contents were not valid for the format specified.
-
FN_E_NO_SUCH_ATTRIBUTE
- The named object did not have one of the requested attributes.
-
FN_E_INSUFFICIENT_RESOURCES
- Insufficient resources are available to return all the requested attributes and their values.
-
FN_E_ATTR_NO_PERMISSION
-
FN_E_INVALID_ATTR_IDENTIFIER
-
FN_E_NO_SUCH_ATTRIBUTE
-
FN_E_INSUFFICIENT_RESOURCES
- These indicate that some of the requested attributes may have been
returned in returned_attrs but one or more of them could not be returned. Use fn_attr_get(3XFN) or fn_attr_multi_get(3XFN) to discover why
these attributes could not be returned.
If fn_ext_searchlist_next() returns a name, it can be called again to get the next name in the enumeration.
fn_ext_searchlist_next() returns a NULL pointer if no more names can be returned. status is set in the following way:
-
FN_SUCCESS
- The search has completed successfully.
-
FN_E_PARTIAL_RESULT
- The enumeration is not yet complete but cannot be continued.
-
FN_E_ATTR_NO_PERMISSION
- The caller did not have permission to read one or more of the attributes specified in the filter.
-
FN_E_INVALID_ENUM_HANDLE
- The supplied enumeration handle was not valid. Possible reasons could be that the handle was
from another enumeration, or the context being enumerated no longer accepts the handle (due to such events as handle expiration or updates to the context).
Other status codes are possible as described in FN_status_t(3XFN) and xfn_status_codes(3XFN).
|
| |
The search performed by fn_attr_ext_search() is not ordered in any way, including the traversal of subcontexts. The names enumerated using fn_ext_searchlist_next()
are not ordered in any way. Furthermore, there is no guarantee that any two series of enumerations with the same arguments to fn_attr_ext_search() will return the names in the same order.
XFN links encountered during the resolution of name are followed, regardless of the follow links control setting, and the search starts
at the final named object or context.
If control specifies that the search should follow links, XFN link names encountered during the search are followed and the terminal named
object is searched. If the terminal named object is bound to a context and the scope of the search includes subcontexts, that context and its subcontexts are also searched. For example, if aname is bound to an XFN link, lname, in a context within the scope of the search, and aname is returned
by fn_ext_searchlist_next(), this means that the object identified by lname satisfied the filter expression. aname is returned instead
of lname because aname can always be named relative to the starting context for the search.
If control specifies that the search should not follow links, the attributes associated with the names of XFN links are searched. For example,
if aname is bound to an XFN link, lname, in a context within the scope of the search, and aname
is returned by fn_ext_searchlist_next(), this means that the object identified by aname satisfied the filter expression.
When following XFN links, fn_attr_ext_search() may search contexts outside of scope. In addition, if the link name's
terminal atomic name is bound in a context within scope, the operation may return the same object more than once.
XFN does not specify how control affects the following of native naming system links during the search.
|
| | Example 1. A sample program of displaying how the fn_attr_ext_search operation may be used.
| |
The following code fragment illustrates how the fn_attr_ext_search() operation may be used. The code consists of three parts: preparing the arguments for the search, performing
the search, and cleaning up.
The first part involves getting the name of the context to start the search and constructing the search filter that named objects in the context must satisfy. This is done in the declarations part
of the code and by the routine get_search_query. See FN_search_filter_t(3XFN)
for the description of sfilter and the filter creation operation.
The next part involves doing the search and enumerating the results of the search. This is done by first getting a context handle to the Initial Context, and then passing that handle along with the
name of the target context and search filter to fn_attr_ext_search(). This particular call to fn_attr_ext_search() uses the default search control options (by passing
in 0 as the control argument). This means that the search will be performed in the context named by target_name and that no reference
or attributes will be returned. In addition, any XFN links encountered will not be followed and all named objects that satisfy the search filter will be returned (that is,
no limit). If successful, fn_attr_ext_search() returns esl, a handle for enumerating the results of the search. The results of the search are enumerated using
calls to fn_ext_searchlist_next(), which returns the name of the object. (The arguments returned_ref and returned_attrs to fn_ext_searchlist_next() are 0 because the default search control used i fn_attr_ext_search() did not request them to be returned.)
The last part of the code involves cleaning up the resources used during the search and enumeration. The call to fn_ext_searchlist_destroy() releases resources reserved for this
enumeration. The other calls release the context handle, name, filter, and status objects created earlier.
| |
/* Declarations */
FN_ctx_t *ctx;
FN_ext_searchlist_t *esl;
FN_composite_name_t *name;
FN_status_t *status = fn_status_create();
FN_composite_name_t *target_name = get_name_from_user_input();
FN_search_filter_t *sfilter = get_search_query();
/* Get context handle to Initial Context */
ctx = fn_ctx_handle_from_initial(status);
/* error checking on 'status' */
/* Initiate search */
if ((esl=fn_attr_ext_search(ctx, target_name,
/* default controls */ 0, sfilter, status)) == 0) {
/* report 'status', cleanup, and exit */
}
/* Enumerate names requested */
while (name=fn_ext_searchlist_next(esl, 0, 0, status)) {
/* do something with 'name' */
fn_composite_destroy(name);
}
/* check 'status' for reason for end of enumeration */
/* Clean up */
fn_ext_searchlist_destroy(esl);
fn_search_filter_destroy(sfilter);
fn_ctx_handle_destroy(ctx);
fn_composite_name_destroy(target_name);
fn_status_destroy(status);
/*
* Procedure for constructing the filter object for search:
* "age" attribute is greater than or equal to 17 AND
* less than or equal to 25
* AND the "student" attribute is present.
*/
FN_search_filter_t *
get_search_query()
{
extern FN_attribute_t *attr_age;
extern FN_attribute_t *attr_student;
FN_search_filter_t *sfilter;
unsigned int filter_status;
sfilter = fn_search_filter_create(
&filter_status,
"(%a >= 17) and (%a <= 25) and %a",
attr_age, attr_age, attr_student);
/* error checking on 'filter_status' */
return (sfilter);
}
|
|
|
| |
See attributes(5) for descriptions of the following
attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| MT-Level | MT-Safe |
|
| |
FN_attrset_t(3XFN), FN_composite_name_t(3XFN), FN_ctx_t(3XFN), FN_ref_t(3XFN), FN_search_control_t(3XFN), FN_search_filter_t(3XFN), FN_status_t(3XFN), fn_attr_get(3XFN), fn_attr_multi_get(3XFN), xfn_status_codes(3XFN), attributes(5)
|
| |
