SmsGetNextFilter

The SmsGetNextFilter function retrieves the handle to the next persistent filter of the specified type from the specified filter container.

SMS_STATUS SmsGetNextFilter(
  HANDLE hFContainer,  // Handle to filter container.
  DWORD frType,        // Filter type.
  HANDLE *phFilter     // Pointer to handle that receives the next 
                       // filter's handle.
);
 

Parameters

hFContainer

Specifies the handle to the filter container from which to retrieve the next persistent filter.

frType

Specifies the filter type. See Filter Types. A specific filter type must be specified—F_ANY is an invalid parameter for frType. Currently, MACHINE_FILTER is the only type of filter supported by filter containers. If your application specifies a filter type other than MACHINE_FILTER, SmsGetNextFilter returns SMS_INVALID_FILTER_ID.

phFilter

Receives the handle to the next persistent filter.

Return Values

The SmsGetNextFilter function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns one of the following manifest constants:

SMS_INVALID_FILTER_ID

No filters of the specified filter type were found in the filter container.

SMS_NO_MORE_DATA

No filter was retrieved because the end of the filter list was reached.

Remarks

After a filter container is opened, the order of the filters within that particular filter container is fixed. The sequence is determined by the order in which the persistent filters were retrieved. SmsGetNextFilter opens the next filter in the filter container.

Note that a filter opened by the SmsGetNextFilter remains open until it is closed by using SmsCloseFilter. The memory allocated for the filter is not deallocated until the usage count for the filter is zero, that is, when all handles to the filter are closed and the filter container itself is closed using SmsCloseFilterContainer.

Because SmsGetNextFilter reads filters sequentially, your application must explicitly reset the filter list to start at the beginning of the list again. When SmsGetNextFilter has reached the end of the filter list, it returns SMS_NO_MORE_DATA. To start at the beginning of the filter list again, your application can use SmsRewind. SmsRewind enables your application to iterate the filters again from the beginning of the filter list.

Using the SmsGetFilterByID function, your application can also access a particular filter by its identifier.

See Also

SmsCloseFilter, SmsCloseFilterContainer, SmsGetFilterByID, SmsRewind