NAME FN_search_filter_t, fn_search_filter_create, fn_search_filter_destroy, fn_search_filter_copy, fn_search_filter_assign, fn_search_filter_expression, fn_search_filter_arguments - filter expression for attribute search SYNOPSIS #include <xfn/xfn.h> FN_search_filter_t *fn_search_filter_create(unsigned int *status, const unsigned char *estr, .); void fn_search_filter_destroy(FN_search_filter_t *sfilter); FN_search_filter_t *fn_search_filter_copy(const FN_search_filter_t *sfilter); FN_search_filter_t *fn_search_filter_assign(FN_search_filter_t *dst, const FN_search_filter_t *src); const char *fn_search_filter_expression(const FN_search_filter_t *sfilter); const void **fn_search_filter_arguments(const FN_search_filter_t *sfilter, size_t *number_of_arguments); DESCRIPTION The FN_search_filter_t type is an expression that is evaluated against the attributes of named objects bound in the scope of the search operation fn_attr_ext_search(3XFN). The filter evaluates to TRUE or FALSE. If the filter is empty, it evaluates to TRUE. Names of objects whose attri- bute values satisfy the filter expression are returned by the search operation. If the identifier in any subexpression of the filter does not exist as an attribute of an object, then the innermost logical expression containing that identifier is FALSE. A subexpression that is only an attribute tests for the pres- ence of the attribute; the subexpression evaluates to TRUE if the attribute has been defined for the object and FALSE otherwise. fn_search_filter_create() creates a search filter from the expression string estr and the remaining arguments. fn_search_filter_destroy() releases the storage associated with the search filter sfilter. fn_search_filter_copy() returns a copy of the search filter sfilter. fn_search_filter_assign() makes a copy of the search filter src and assigns it to dst, releasing the old contents of dst. A pointer to the same object as dst is returned. fn_search_filter_expression() returns the filter expression of sfilter. fn_search_filter_arguments() returns an array of pointers to arguments supplied to the filter constructor. number_of_arguments is set to the size of this array. The types of the arguments are determined by the substitution tokens in the expression in sfilter. BNF of Filter Expression <FilterExpr> ::= [ <Expr> ] <Expr> ::= <Expr> "or" <Expr> <Expr> "and" <Expr> | "not" <Expr> | "(" <Expr> ")" | <Attribute> [ <Rel_Op> <Value> ] | <Ext> <Rel_Op> ::= "==" | "!=" | "<" | "<=" | ">" | ">=" | "~=" <Attribute> ::= "%a" <Value> ::= <Integer> | "%v" |<Wildcarded_string> <Wildcarded_string> ::= "*" | <String> | {<String> "*"}+ [<String>] | {"*" <String>}+ ["*"] <String> ::= "`" { <Char> } * "`" | "%s" <Char> ::= <PCS> // See BNF in Section 4.1.2 for PCSdefinition | Characters in the repertoire of a string representation <Identifier> ::=" "%i" <Ext> ::= <Ext_Op> "(" [Arg_List] ")" <Ext_Op> ::= <String> | <Identifier> <Arg_List> ::= <Arg> | <Arg> "," <Arg_List> <Arg> ::= <Value> | <Attribute> | <Identifier> Specification of Filter Expression The arguments to fn_search_filter_create() are a return status, an expression string, and a list of arguments. The string contains the filter expression with substitution tokens for the attributes, attribute values, strings, and identifiers that are part of the expression. The remaining list of arguments contains the attributes and values in the order of appearance of their corresponding substitution tokens in the expression. The arguments are of types FN_attribute_t*, FN_attrvalue_t*, FN_string_t*, or FN_identifier_t*. Any attribute values in an FN_attribute_t* type of argument are ignored; only the attribute identifier and attribute syntax are relevant. The argument type expected by each substitution token are listed in the following table. ____________________________________________________________ | Token | Argument Type | | %a | FN_attribute_t* | | %v | FN_attrvalue_t* | | %s | FN_string_t* | | %i | FN_identifier_t* | |__________________|________________________________________| Precedence The following precedence relations hold in the absence of parentheses, in the order of lowest to highest: or and not relational operators These boolean and relational operators are left associative. Relational Operators Comparisons and ordering are specific to the syntax and/or rules of the supplied attribute. Locale (code set, language, or territory) mismatches that occur during string comparisons and ordering operations are resolved in an implementation-dependent way. Relational operations that have ordering semantics may be used for strings of code sets in which ordering is meaningful, but is not of general use in internationalized environments. An attribute that occurs in the absence of any relational operator tests for the presence of the attribute. ____________________________________________________________ | Operator | Meaning | | == | The sub-expression is TRUE if at least| | | one value of the specified attribute is| | | equal to the supplied value. | | != | The sub-expression is TRUE if no values| | | of the specified attribute equal the| | | supplied value. | | >= | The sub-expression is TRUE if at least| | | one value of the attribute is greater| | | than or equal to the supplied value. | | > | The sub-expression is TRUE if at least| | | one value of the attribute is greater| | | then the supplied value. | | <= | The sub-expression is TRUE if at least| | | one value of the attribute is less than| | | or equal to the supplied value. | | < | The sub-expression is TRUE if at least| | | one value of the attribute is less than| | | the supplied value. | | ~= | The sub-expression is TRUE if at least| | | one value of the specified attribute| | | matches the supplied value according to| | | some context-specific approximate| | | matching criterion. This criterion must| | | subsume strict equality. | |__________________|________________________________________| Wildcarded Strings A wildcarded string consists of a sequence of alternating wildcard specifiers and strings. The sequence can start with either a wildcard specifier or a string, and end with either a wildcard specifier or a string. The wildcard specifier is denoted by the asterisk character ('*') and means zero or more occurrences of any character. Wildcarded strings can be used to specify substring matches. The following are examples of wildcarded strings and what they mean: _______________________________________________________________ | Wildcarded String | Meaning | | * | Any string | | *'ing' | Any string ending with ing | | Any string starting | | | with jo, and con-| | | taining the sub-| | | string ph, | | | and which contains| | | the substring ne in| | | the portion | | | of the string fol-| | | lowing ph, and which| | | ends with er | | | T} | | | %s* | Any string starting with the supplied| | | string | | Any string starting| | | with bix and ending| | | with the supplied| | | string | | | T} | | |_____________________|________________________________________| String matches involving strings of different locales (code set, language, or territory) are resolved in an implementation-dependent way. Extended Operations In addition to the relational operators, extended operators can be specified. All extended operators return either TRUE or FALSE. A filter expression can contain both relational and extended operations. Extended operators are specified using an identifier (see FN_identifier_t(3XFN)) or a string. If the operator is specified using a string, the string is used to construct an identifier of format FN_ID_STRING. Identifiers of extended operators and signatures of the corresponding extended operations, as well as their suggested semantics, are registered with X/Open Company Ltd. The following three extended operations are currently defined: 'name'(<Wildcarded String>) The identifier for this operation is 'name' (FN_ID_STRING). The argument to this operation is a wildcard string. The operation returns TRUE if the name of the object matches the supplied wildcard string. 'reftype'(%i) The identifier for this operation is 'reftype' (FN_ID_STRING). The argument to this operation is an identifier. The operation returns TRUE if the refer- ence type of the object is equal to the supplied iden- tifier. 'addrtype'(%i) The identifier for this operation is 'addrtype' (LM FN_ID_STRING). The argument to the operation is an identifier. The operation returns TRUE if any of the address types in the reference of the object is equal to the supplied identifier. Support and exact semantics of extended operations are context-specific. If a context does not support an extended operation, or if the filter expression supplies the extended operation with either an incorrect number or type of argu- ments, the error FN_E_SEARCH_INVALID_OP is returned. (Note: FN_E_OPERATION_NOT_SUPPORTED is returned when fn_attr_ext_search(3XFN) is not supported.) The following are examples of filter expressions that con- tain extended operations: ______________________________________________________________ | Expression | Meaning | | Evaluates to | | | TRUE | | | if the name of the object| | | starts with | | | bill. | | | T} | | | %i(%a, %v) | Evaluates to result of| | | applying the specified| | | operation to the supplied| | | arguments. | | (%a == %v) and 'name'('joe'*)| Evaluates to TRUE if the| | | specified attribute has the| | | given value and if the name| | | of the object starts with| | | joe. | |______________________________|______________________________| RETURN VALUES fn_search_filter_create() returns a pointer to an FN_search_filter_t object if the operation succeeds; other- wise it returns a NULL pointer. ERRORS fn_search_filter_create() returns a NULL pointer if the operation fails and sets status in the following way: FN_E_SEARCH_INVALID_FILTER The filter expression had a syntax error or some other problem. 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_INVALID_ATTR_IDENTIFIER The left hand side of an operator expression was not an attribute. FN_E_INVALID_ATTR_VALUE The right hand side of an operator expression was not an integer, attribute value, or (wildcarded) string. Other status codes are possible as described in the refer- ence manual pages for FN_status_t(3XFN) and xfn_status_codes(3XFN). EXAMPLES Example 1: Creating Different Filters The following examples illustrate how to create three dif- ferent filters. The first example shows how to construct a filter involving substitution tokens and literals in the same filter expres- sion. This example creates a filter for named objects whose color attribute contains a string value of red, blue, or white. The first two values are specified using substitution tokens; the last value, white, is specified as a literal in the expression. unsigned int status; extern FN_attribute_t *attr_color; FN_string_t *red = fn_string_from_str((unsigned char *)"red"); FN_string_t *blue = fn_string_from_str((unsigned char *)"blue"); FN_search_filter_t *sfilter; sfilter = fn_search_filter_create( &status, "(%a == %s) or (%a == %s) or (%a == 'white')", attr_color, red, attr_color, blue, attr_color); The second example illustrates how to construct a filter involving a wildcarded string. This example creates a filter for searching for named objects whose last_name attribute has a value that begins with the character m. unsigned int status; extern FN_attribute_t *attr_last_name; FN_search_filter_t *sfilter; sfilter = fn_search_filter_create( &status, "%a == 'm'*", attr_last_name); The third example illustrates how to construct a filter involving extended operations. This example creates a filter for finding all named objects whose name ends with ton. unsigned int status; FN_search_filter_t *sfilter; sfilter= fn_search_filter_create(&status, "'name'(*'ton')"); 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_attrvalue_t(3XFN), FN_identifier_t(3XFN), FN_status_t(3XFN), FN_string_t(3XFN), fn_attr_ext_search(3XFN), xfn_status_codes(3XFN), attri- butes(5)
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |