Attribute Filters (ATTRIBUTE_FILTER)

An attribute filter specifies the attributes (represented as scalars) that are retrieved for the machine folders within a container. If only an attribute filter is set on a container, the attribute filter also determines which group folders are retrieved.

Attribute filters can be applied only to the following containers: site containers, site group containers, and machine containers.

Note that an attribute filter does not determine the set of machine folders retrieved from the site database—a machine filter is used to specify the attributes used to select the machine folders that will populate a container. An attribute filter specifies the criteria used to select the group folders and attribute scalars that are retrieved for each machine folder in a container.

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.

Note When an attribute filter is applied to a container that also has an architecture filter set, the architectures specified in the attribute filter are implicitly added to the list of architectures specified in the architecture filter.

Using the SmsAddToken function, your application can add tokens to an attribute filter. Each expression token represents an attribute. For attribute 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:

szArchitecture

A string that specifies the name of the architecture that contains the attribute.

For example, Personal Computer.

SzGroupClass

A string that specifies the name of the group class that contains the attribute.

For example, MICROSOFT|IDENTIFICATION|1.0.

szAttributeName

A string that specifies the name of the attribute that you want to retrieve for objects of the type specified by architecture.

For example, SMSLocation.

Your application could create an attribute filter with two tokens (one with Personal Computer architecture and MICROSOFT|IDENTIFICATION|1.0 group class with attribute SMSLocation, and the other with the same architecture and group class but with the attribute SystemRole) 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 one group folder (for the MICROSOFT|IDENTIFICATION|1.0 group class) and the group folder will contain two scalars (SMSLocation and SystemRole).

Example

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

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

// Set the expression token to 
// Architecture = "Personal Computer"
// Group Class = "MICROSOFT|IDENTIFICATION|1.0"
// Attribute = "SMSLocation"

// Set the architecture name to Personal Computer.
strcpy( Token.szArchitecture, "Personal Computer");
// Set the group class.
strcpy(Token.szGroupClass, "MICROSOFT|IDENTIFICATION|1.0");
// Set the attribute.
strcpy( Token.szAttributeName, "SMSLocation"); 

// 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 an Attribute 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;
}