SmsSetFilter

The SmsSetFilter function applies the specified filter to a container.

SMS_STATUS SmsSetFilter(
  HANDLE hContainer,  // Handle to container.
  HANDLE hFilter      // Handle to filter.
);
 

Parameters

hContainer

Specifies the handle to the container to which you want to apply the filter.

hFilter

Specifies the handle to the filter to assign to the container.

Return Values

The SmsSetFilter 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 container or filter handle is not valid.

SMS_INVALID_CONTAINER_ID

An unknown container type was specified.

SMS_CONTAINER_POPULATED

The specified container is already populated.

SMS_INVALID_CONNECTION_HANDLE

The filter's connection handle does not match the container's connection handle.

SMS_DUPLICATE_FILTER

A filter of the specified type has already been set on the container.

SMS_INVALID_FILTER_TYPE

Your application has attempted to set a filter that is incompatible with the specified container.

SMS_EMPTY

Your application did not call SmsAddToken to add tokens to the filter.

Remarks

The type of the filter must be supported by the container. If the filter type is not supported by the container, SmsSetFilter does not apply the filter and returns a status of SMS_INVALID_FILTER_TYPE.

SmsSetFilter allows only one filter of each type to be applied to a container. For example, two machine filters cannot be applied to the same container. If a filter of the same type has already been applied to the container, SmsSetFilter does not apply the second filter and returns a status of SMS_DUPLICATE_FILTER.

After SmsSetFilter has been used to set a filter on a container, the container keeps a copy of the filter for its own use. This means that any changes made to the filter will not be reflected in the filter that has been set on the container. In addition, a filter cannot be removed from a container after it has been set.

To get the list of filters applied to a container, use the SmsGetAllFilters function.

After your application applies a filter to a container, it can close the filter (to free memory used by the filter) by using the SmsCloseFilter function. Note that the container maintains its own copy of a filter after the filter has been applied.

See Also

SmsGetAllFilters, SmsCloseFilter