Партнёры:
Хостинг:
NAME
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 *con-
trol, 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);
DESCRIPTION
This set of operations is used to list names of objects
whose attributes satisfy the filter expression. The refer-
ences to which these names are bound and specified attri-
butes and their values may also be returned.
control encapsulates the option settings for the search.
These options are:
o the scope of the search
o whether XFN links are followed
o a limit on the number of names returned
o whether references and specific attributes associated
with the named objects that satisfy the filter are
returned
The scope of the search is one of:
o the object named name relative to the context ctx
o the context named name relative to the context ctx
o the context named name relative to the context ctx,
and its subcontexts
or
o the context named name relative to the context ctx,
and a context implementation-defined set of subcon-
texts
If the value of control is 0, default control option set-
tings are used. The default settings are:
o scope is search named context
o links are not followed
o all names of objects that satisfy the filter are
returned
o 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 attri-
butes 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 pro-
cess. 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 succes-
sive 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 ter-
minate the enumeration.
RETURN VALUES
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.
ERRORS
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 sup-
ported.
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 dis-
cover 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 con-
tinued.
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. Possi-
ble 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).
USAGE
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 fol-
lowed, 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 subcon-
texts 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.
EXAMPLES
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 con-
sists 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 con-
text 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 han-
dle, 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);
}
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
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)
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |