Filtering is enabled by setting the CRA_FILTERED attribute of container records that are to be excluded from the viewable subset.
The pfnFilter parameter points to an application-provided function that determines whether a record is to be included in the viewable subset. The pfnFilter parameter must be declared as:
BOOL PFN pfnFilter (
PRECORDCORE p,
PVOID pStorage);
where p points to a RECORDCORE structure that describes the container record to be tested. The pfnFilter parameter returns TRUE if the record is to be included in the viewable subset, or FALSE if it is to be excluded. The container sets the CRA_FILTERED attribute for the record based on the return from the pfnFilter parameter.
Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, then MINIRECORDCORE should be used instead of RECORDCORE and PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data structures and messages.
If the CRA_FILTERED attribute is set for the record, the record is not visible. If the CCS_AUTOPOSITION style bit is set and the container is showing the icon view, the container records are arranged when a record is filtered out.
The CM_FILTER message supports only one level of filtering.
It is the application's responsibility to provide a National Language Support-enabled (NLS-enabled) function for the pfnFilter parameter.
If the pfnFilter parameter value is NULL, a container is returned to an unfiltered state. If functions such as inserting a record into a container, arranging the records, or sorting the records are performed on a container whose records have been filtered, the effect of these functions remains if the container records are later unfiltered.
All messages act on the entire container. For example, a record that is filtered and is removed from the container will be removed from the container entirely; it is not present in the container when the container records are unfiltered.