MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

IViewFilter

IViewFilter enables consumers to restrict the contents of a rowset to rows matching a set of conditions.

When to Implement

Providers that can define a subset of rows based on a consumer-defined set of conditions expose IViewFilter. A provider may restrict functionality to filters based on existing indexes, or filters may require a specific sort order to also be applied.

When to Call

Consumers needing a subset of rows can call IViewFilter::SetFilter to apply a filter condition to a view. Rowsets or chapters opening using this view expose only those rows that match the criteria. Each view can have only a single filter applied, but a view containing a filter can be applied to an existing filtered chapter to further filter its contents.

Filter criteria are expressed as an array of rows and columns, with an associated set of comparison operators.

Within a row of the criteria array, each column corresponds to a column in the table. The mapping of the columns in the criteria array to the columns in the table is done through an accessor passed into IViewFilter::SetFilter or IViewFilter::GetFilter. The same column from the table may appear once, more than once, or not at all in the criteria array. Each column in the criteria array has a corresponding comparison operation that defines how the value passed in the criteria array is to be compared to the value of the corresponding column in the rowset. Each column of the criteria array is joined in a logical AND with the other columns in that row of the criteria array.

The criteria array can contain multiple rows. In this case, the array of comparison operations is a two-dimensional array stored in row-major format, such that the comparison operators for each of the columns of the first row in the criteria array are followed by the comparison operators for each column of the second row in the criteria array, and so forth. Multiple rows in the criteria array are joined together in a logical OR.

For example, assume the rowset shown in the following table.

Using the preceding rowset, the following table shows the results for various combinations of accessor bindings, criteria array, and comparison operators.

Note   DBCOMPAREOPS_IGNORE must be supported by all providers that implement IRowsetFind or IViewFilter. In addition, providers that expose IViewFilter on the view object must also expose IAccessor and IColumnsInfo on the view object. Consumers should use only accessors created on the view object to get or set filters.

The following code example shows defining a filter for which the individual is from Oregon or has more than one child:

DBBINDING     rgBindings[2];
IAccessor *   pIAccessor;
HACCESSOR     hAccessor;
DBCOMPAREOP   rgCompareOps[] = { DBCOMPAREOP_EQ, DBCOMPAREOP_IGNORE,
                                 DBCOMPAREOP_IGNORE, DBCOMPAREOP_GT };

typedef struct FILTER_CRITERIA {
   TCHAR   rcState[4];
   ULONG   ulStateStatus;
   ULONG   ulStateLength;
   ULONG   cChildren;
   ULONG   ulChildrenStatus;
} WHERE_CLAUSE;

WHERE_CLAUSE rgCriteriaData[] =
{
   _T("OR"), DBSTATUS_S_OK, 2 * sizeof(TCHAR), NULL, DBSTATUS_S_ISNULL,
   NULL, DBSTATUS_S_ISNULL, 0, 1, DBSTATUS_S_OK
};

// Initialize common binding values
for (cCol = 0; cCol < 2; cCol++)
{
   rgBindings[cCol].pTypeInfo    = NULL;
   rgBindings[cCol].pObject      = NULL;
   rgBindings[cCol].pBindExp     = NULL;
   rgBindings[cCol].dwMemOwner   = DBMEMOWNER_CLIENTOWNED;
   rgBindings[cCol].eParamIO     = DBPARAMIO_NOTPARAM;
   rgBindings[cCol].dwFlags      = 0;
   rgBindings[cCol].bPrecision   = 0;
   rgBindings[cCol].bScale       = 0;
}

// Initial bindings for the "State" column
   rgBindings[0].dwPart     = DBPART_VALUE | DBPART_LENGTH | DBPART_STATUS;
   rgBindings[0].iOrdinal   = 3;
   rgBindings[0].wType      = DBTYPE_STR;
   rgBindings[0].obValue    = offsetof(WHERE_CLAUSE, rcState);
   rgBindings[0].obStatus   = offsetof(WHERE_CLAUSE, ulStateStatus);
   rgBindings[0].obLength   = offsetof(WHERE_CLAUSE, ulStateLength);
   rgBindings[0].cbMaxLen   = sizeof(WHERE_CLAUSE.rcState);

// Initial bindings for the "Children" column
   rgBindings[1].dwPart     =
   rgBindings[1].iOrdinal   = 2
   rgBindings[1].wType      = DBTYPE_I4;
   rgBindings[1].obValue    = offsetof(WHERE_CLAUSE, cChildren);
   rgBindings[1].obStatus   = offsetof(WHERE_CLAUSE, ulChildrenStatus);
   rgBindings[0].obLength   = 0;
   rgBindings[1].cbMaxLen   = sizeof(WHERE_CLAUSE.cChildren);

pIAccessor->CreateAccessor(DBACCESSOR_ROWDATA, 2, rgBindings, sizeof(WHERE_CLAUSE), &hAccessor, NULL);

// Set filter condition
pIViewFilter->SetFilter(hAccessor, 2, rgCompareOps, rgCriteriaData);