Group Filters (GROUP_FILTER)

A group filter specifies the groups that are retrieved for the machine folders within a container.

Group filters can only be applied to containers that support machine folders: site container, site group container, machine container, and machine group container.

When a group filter is set on a container, the machine folders in that container will contain only the groups that have been specified in the group filter. However, all attributes within the specified groups will be retrieved if no attribute filter has been set.

If both an attribute filter and a group filter are set, the folders for only the groups specified by both the attribute filter and the group filter are retrieved. The group folders specified by the attribute filter will contain only the attributes specified in the attribute filter.

Using the SmsAddToken function, your application can add tokens to a group filter. Each expression token represents a group. For group filters, the tokens can be connected only by using an OP_OR control token—this means that your application must pass OP_OR for the opAndOr parameter when calling the SmsAddToken function. The TOKEN structure that contains the expression token must have the following members:

szName

A string that specifies that the group class name is used to evaluate the expression.

Currently, the string "GroupClass" must be specified for this value.

DwOp

A DWORD value that specifies the operator used to evaluate the expression.

For group filters, this operator can only be QOP_STR_EQ.

SzValue

A string that specifies the class name of the group to retrieve. A group class name has the following form:

organization:name:version.

For example, the Identification group for the Personal Computer architecture has a class name: "MICROSOFT|IDENTIFICATION|1.0".

Note that the SMS API engine does not validate the group specified by a group token. Your application is responsible for creating a token for a valid group class.

For example, your application could create a group filter with two tokens (one for MICROSOFT|IDENTIFICATION|1.0 group and the other for the MICROSOFT|DISK|1.0 group) and set this filter as the only filter on a machine container. When your application populates the machine container, the container contains folders that represent all computers, and each of those machine folders will contain two group folders: MICROSOFT|IDENTIFICATION|1.0 and MICROSOFT|DISK|1.0.

Example

// Function to add a token to a group filter so that
// the filter retrieves the Identification group
// within machine folders.

SMS_STATUS AddTokenToGroupFilter(HANDLE hFilter) 
                         //  Handle to group filter.
{
SMS_STATUS stat;
TOKEN Token;
// Clear the Token structure.
memset( &Token, 0, sizeof (TOKEN) );

// Set the expression token to 
// Group Class = "MICROSOFT|IDENTIFICATION|1.0"

// Set name to GroupClass.
strcpy( Token.szName, "GroupClass");

// Set the operator used to evaluate the expression.
// Must use the string equals operator.
Token.dwOp = QOP_STR_EQ;

// Set the group class name.
strcpy(Token.szValue, "MICROSOFT|IDENTIFICATION|1.0");

// Add the token to the filter.
stat = SmsAddToken( hFilter, // Specifies the handle to filter.
                    OP_OR,   // Must use the OR control token to 
                             // add a token to a Group filter.
                    &Token,  // Specifies the structure containing
                             // the expression token.
                    AT_END   // Adds the token to the end of 
                             // the filter.
                  );


if (stat == SMS_OK)    
    printf("The token was successfully added to the filter.\n");
else 
    printf("SmsAddToken error: %d\n", stat);

return stat;
}