SE CreateSearchFilter

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE CreateSearchFilter

extern SE_Return_Code
SE_CreateSearchFilter
(
	SE_Encoding		encoding,	¹
const	SE_Search_Rule		rules[],	²
	SE_Search_Filter	*	search_filter	³
);

Definition

Defines a set of rules that can be used by an iterator to filter objects from a transmittal so that only objects that pass the rules will be returned to the user. This function only defines a set of rules; to use a set of rules after they have been defined, pass the search filter into an iterator when creating the iterator. By doing so, the iterator will be bound to use that set of rules (that search filter) to filter all objects that will be returned by that iterator.

Search filters can be freed at any time; a search filter does NOT need to stay in existence until the iterator(s) that depend on that filter are freed. (An iterator retains a copy of any search filter used to initialize that iterator). Also, the same search filter can be used to initialize many iterators.

See SE_Search_Rule for further details on how to construct a valid set of rules.

Returns

SE_RETCOD_SUCCESS	and the search filter is created.
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

and a handle for the newly created search filter is copied into *search_filter, if valid parameters were passed in and all operations succeeded.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_INACTIONABLE_FAILURE	and *search_filter is left unaltered, if either search_filter or rules was NULL, or encoding was required but was NULL.
SE_STATCODE_OUT_OF_MEMORY	*search_filter is set to NULL, if the API could not allocate memory for the new search filter.
SE_STATCODE_INACTIONABLE_FAILURE	*search_filter is set to NULL, if an illegal expression was specified by the rules parameter (for example, if an AND expression within the array only had one parameter), or the call fails for any other reason.

Parameters Notes

¹ identifies the API implementation encoding to use when creating this search filter. If the specified API can't create the search filter, then the API will return a status code indicating why it could not be created. If encoding is NULL, then the API implementation encoding to be used must be statically bound at compile time. See also SE_GetEncoding().

² a postfix array defining a set of search rules to be applied as a filter for one or more iterators. This must be a 'properly formed' set of rules (each AND expression must have two parameters, each OR expression must have two parameters, each NOT expression must have 1 parameter, the last entry in the array must be a rule with a value of SE_SEARCHRULETYP_END, ...). The end of the array is indicated by the SE_SEARCHRULETYP_END entry. Any entries after an SE_SEARCHRULETYP_END entry will be ignored.

³ pointer to the newly created search filter.