SmsGetFilterByID

The SmsGetFilterByID function retrieves the handle to the persistent filter of the specified filter type and with the specified identifier.

SMS_STATUS SmsGetFilterByID(
  HANDLE hFContainer, // Handle to filter container.
  DWORD frType,       // Filter type.
  const char *pszID,  // Pointer to identifier string.
  HANDLE *phFilter    // Pointer to handle that receives the 
                      // filter's handle.
);
 

Parameters

hFContainer

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

frType

Specifies the filter type of the filter to retrieve. 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 that is not MACHINE_FILTER, SmsGetFilterByID returns SMS_INVALID_FILTER_ID.

pszID

Specifies the identifier of the persistent filter to retrieve. The filter identifier is an eight-character identifier that the SMS system assigns to a query. Note that the first three characters are the site code for the site where the query was created. Also note that the default queries provided with SMS have a six-character identifier, which begins with the characters SMS.

phFilter

Receives the handle to the specified persistent filter.

Return Values

The SmsGetFilterByID 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_NOT_FOUND

The filter with the specified identifier could not be found in the filter container.

Remarks

SmsGetFilterByID opens the specified filter in the filter container. This filter remains open until it is closed 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.

Using the SmsGetNextFilter function, your application can access the filters in the filter container sequentially. 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.

See Also

SmsCloseFilter, SmsCloseFilterContainer, SmsGetNextFilter