Партнёры:
Хостинг:
NAME
fn_attr_search, FN_searchlist_t, fn_searchlist_next,
fn_searchlist_destroy - search for the atomic name of
objects with the specified attributes in a single context
SYNOPSIS
#include <xfn/xfn.h>
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);
DESCRIPTION
This set of operations is used to enumerate names of objects
bound in the target context named name relative to the con-
text ctx with attributes whose values match all those speci-
fied by match_attrs.
The attributes specified by match_attrs form a conjunctive
AND expression against which the attributes of each named
object in the target context are evaluated. For multi-valued
attributes, the list order of values is ignored and attri-
bute values not specified in match_attrs are ignored. If no
value is specified for an attribute in match_attrs, the
presence of the attribute is tested. If the value of
match_attrs is 0, all names in the target context are
enumerated.
If a non-zero value of return_ref is passed to
fn_attr_search(), the reference bound to the name is
returned in the returned_ref argument to
fn_searchlist_next().
Attribute identifiers and values associated with named
objects that satisfy match_attrs may be returned by
fn_searchlist_next(). The attributes returned are those
listed in the return_attr_ids argument to fn_attr_search().
If the value of return_attr_ids is 0, all attributes are
returned. If return_attr_ids is an empty FN_attrset_t(3XFN)
object, no attributes are returned. Any attribute values in
return_attr_ids are ignored; only the attribute identifiers
are relevant for return_attr_ids.
The call to fn_attr_search() initiates the enumeration pro-
cess. It returns a handle to an FN_searchlist_t object that
is used to enumerate the names of the objects whose attri-
butes match the attributes specified by match_attrs.
The operation fn_searchlist_next() returns the next name in
the enumeration identified by the sl. The reference of the
name is returned in returned_ref if return_ref was set in
the call to fn_attr_search(). The attributes specified by
return_attr_ids are returned in returned_attrs.
fn_searchlist_next() also updates sl to indicate the state
of the enumeration. Successive calls to fn_searchlist_next()
using sl return successive names, and optionally, references
and attributes, in the enumeration; these calls further
update the state of the enumeration.
fn_searchlist_destroy() releases resources used during the
enumeration. This can be invoked at any time to terminate
the enumeration.
fn_attr_search() does not follow XFN links that are bound in
the target context.
RETURN VALUES
fn_attr_search() returns a pointer to an FN_searchlist_t
object if the enumeration is successfully initiated; it
returns a NULL pointer if the enumeration cannot be ini-
tiated or if no named object with attributes whose values
match those specified in match_attrs is found.
fn_searchlist_next() returns a pointer to an
FN_string_t(3XFN) object; it returns a NULL pointer if no
more names can be returned in the enumeration. If
returned_ref is a NULL pointer, or if the return_ref parame-
ter to fn_attr_search was 0, no reference is returned; oth-
erwise, returned_ref contains the reference bound to the
name. If returned_attrs is a NULL pointer, no attributes are
returned; otherwise, returned_attrs contains the attributes
associated with the named object, as specified by the
return_attr_ids parameter to fn_attr_search().
In the case of a failure, these operations return in the
status argument a code indicating the nature of the failure.
ERRORS
fn_attr_search() returns a NULL pointer if the enumeration
could not be initiated. The status argument is set in the
following way:
FN_SUCCESS
A named object could not be found whose attributes
satisfied the implied filter of equality and conjunc-
tion.
FN_E_ATTR_NO_PERMISSION
The caller did not have permission to read one or more
of the specified attributes.
FN_E_INVALID_ATTR_VALUE
A value type in the specified attributes 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_searchlist_next() returns a name
and, optionally, the reference and requested attributes.
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 was
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.
fn_searchlist_next() returns a NULL pointer if no more names
can be returned. The status argument 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 specified attributes.
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 names enumerated using fn_searchlist_next() are not
ordered in any way. Furthermore, there is no guarantee that
any two series of enumerations on the same context with
identical match_attrs will return the names in the same
order.
EXAMPLES
Example 1: A sample program of displaying how to use
fn_attr_search() function.
The following code fragment illustrates how the
fn_attr_search() operation may be used. The code consists of
three parts: preparing the arguments for the search, per-
forming the search, and cleaning up.
The first part involves getting the name of the context to
start the search and constructing the set of attributes 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.
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 match-
ing attributes to fn_attr_search(). This particular call to
fn_attr_search() is requesting that no reference be returned
(by passing in 0 for return_ref), and that all attributes
associated with the named object be returned (by passing in
0 as the return_attr_ids argument). If successful,
fn_attr_search() returns sl, a handle for enumerating the
results of the search. The results of the search are
enumerated using calls to fn_searchlist_next(), which
returns the name of the object and the attributes associated
with the named object in returned_attrs.
The last part of the code involves cleaning up the resources
used during the search and enumeration. The call to
fn_searchlist_destroy() releases resources reserved for this
enumeration. The other calls release the context handle,
name, attribute set, and status objects created earlier.
/* Declarations */
FN_ctx_t *ctx;
FN_searchlist_t *sl;
FN_string_t *name;
FN_attrset_t *returned_attrs;
FN_status_t *status = fn_status_create();
FN_composite_name_t *target_name = get_name_from_user_input();
FN_attrset_t *match_attrs = get_search_query();
/* Get context handle to Initial Context */
ctx = fn_ctx_handle_from_initial(status);
/* error checking on 'status' */
/* Initiate search */
if ((sl=fn_attr_search(ctx, target_name, match_attrs,
/* no reference */ 0, /* return all attrs */ 0, status)) == 0) {
/* report 'status', cleanup, and exit */
}
/* Enumerate names and attributes requested */
while (name=fn_searchlist_next(sl, 0, &returned_attrs, status)) {
/* do something with 'name' and 'returned_attrs'*/
fn_string_destroy(name);
fn_attrset_destroy(returned_attrs);
}
/* check 'status' for reason for end of enumeration */
/* Clean up */
fn_searchlist_destroy(sl); /* Free resources of 'sl' */
fn_status_destroy(status);
fn_attrset_destroy(match_attrs);
fn_ctx_handle_destroy(ctx);
fn_composite_name_destroy(target_name);
/*
* Procedure for constructing attribute set containing
* attributes to be matched:
* "zip_code" attribute value is "02158"
* AND "employed" attribute is present.
*/
FN_attrset_t *
get_search_query()
{
/* Zip code and employed attribute identifier, syntax */
extern FN_attribute_t *attr_zip_code;
extern FN_attribute_t *attr_employed;
FN_attribute_t *zip_code = fn_attribute_copy(attr_zip_code);
FN_attr_value_t zc_value = {5, "02158"};
FN_attrset_t *match_attrs = fn_attrset_create();
fn_attribute_add(zip_code, &zc_value, 0);
fn_attrset_add(match_attrs, zip_code, 0);
fn_attrset_add(match_attrs, attr_employed, 0);
return (match_attrs);
}
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
FN_attribute_t(3XFN), FN_attrset_t(3XFN),
FN_attrvalue_t(3XFN), FN_composite_name_t(3XFN),
FN_ctx_t(3XFN), FN_status_t(3XFN), FN_string_t(3XFN),
fn_attr_ext_search(3XFN), fn_attr_get(3XFN),
fn_attr_multi_get(3XFN), fn_ctx_list_names(3XFN),
xfn_status_codes(3XFN), attributes(5)
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |