SmsGetAllFilters

The SmsGetAllFilters function retrieves a list of handles to all the filters that have been applied to a specified container.

SMS_STATUS SmsGetAllFilters(
  HANDLE hContainer, // Handle to the container.
  HANDLE *pahFilters,
                     // Pointer to an array of HANDLE values.
  DWORD *pctFilters  // Number of filters applied to the container.
);
 

Parameters

hContainer

Specifies the handle to the container whose applied filters you want to retrieve.

pahFilters

Points to an array of HANDLE values. This array will receive the handles to the filters that have been applied to the container. Your application must ensure that the array specified by pahFilters is large enough to contain the number of filters applied to the container specified by hContainer. See the following remarks.

pctFilters

Specifies the number of filters applied to the container.

Return Values

The SmsGetAllFilters 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_HANDLE

The specified handle is not a valid filter handle.

SMS_MORE_DATA

This status code can be caused by one of the following conditions:

• The filter count pointer is NULL.
• The filter handle array pointer is NULL.
• The actual number of filters exceeds the specified number of entries in the filter handle array.

Remarks

The application must ensure that the array specified by pahFilters is large enough to contain the number of filters applied to the container specified by hContainer.

To get the correct size for the pahFilters array, call the SmsGetAllFilters function with pahFilters set to NULL or with pctFilters set to zero. SmsGetAllFilters will assign the count of applied filters to pctFilters and return a status of SMS_MORE_DATA. After getting the correct value for pctFilters, call the SmsGetAllFilters function again using the correct value for pctFilters, and a pahFilters array with a size that matches the count specified by pctFilters.

If the value for pctFilters is less than the number of applied filters, the function writes the number of filter handles specified by pctFilters to the pahFilters array and returns a status of SMS_MORE_DATA.

If the value for pctFilters is greater than or equal to the number of applied filters, the function writes all filter handles for the specified container to the pahFilters array and returns a status of SMS_OK.

Important After SmsGetAllFilters is called for a container, the instance count for each filter applied to the container is incremented by 1. To decrement the count to the previous count value for each filter, your application must explicitly call SmsCloseFilter for each filter applied to the container.

See Also

SmsCloseFilter