A site filter specifies the sites that are retrieved for a site container. If no site filter is set on a site container, all sites in the site database (the current site and all sites below it in the site hierarchy) are retrieved for the container. Site filters can only be applied to site containers.
Using the SmsAddToken function, your application can add tokens to a site filter. The TOKEN structure that contains the expression token must have the following members:
"RootSite" specifies that all sites in the site database (the current site and all sites beneath it in the site hierarchy) are retrieved for the site container.
"SiteByCode" specifies that a specified site is retrieved for the site container. The szValue member contains the site code for the site.
For site filters, this operator can only be QOP_STR_EQ. Note that if RootSite is specified for szName, this member is ignored.
For example, "TIM".
For site 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. In addition, only tokens that specify SiteByCode for szName can be combined. By combining SiteByCode tokens, your application can populate a site container with only the specified sites. If SiteByCode tokens are combined with a RootSite token, the RootSite token (which specifies all sites in the site database) will override the SiteByCode tokens and all sites will be retrieved.
For example, your application could create a site filter with two tokens (one for a site with site code JS1 and the other for a site ASH) and set this filter on a site container. When your application populates the site container, the container contains folders that represent the specified sites.
Note There are two methods for retrieving all sites in a site database:
If no site filter is set on a site container, all sites in the site database are retrieved and each site is represented as a top-level site folder. This is a flat list of sites. Note that if a site contains subsites, the subsites are also represented as subfolders of that site (in addition to the subsites' representation as top-level folders).
If a site filter with RootSite specified for szName is set on a site container, all sites in the site database are retrieved, but the sites are represented in accordance with their hierarchy in the SMS system. This means that only the current site is represented as a top-level folder in the container, and that the subsites directly beneath the current site are represented as subfolders of the current site's folder. If those second-level subsites have their own subsites, third-level subsites are represented as subfolders of the second-level subsites, and so on.
// Function to add a token to a Site filter so that
// the filter retrieves the folder for
// Tim World, which has a site code of TIM.
SMS_STATUS AddTokenToSiteFilter(HANDLE hFilter)
// Handle to Site filter.
{
SMS_STATUS stat;
TOKEN Token;
// Clear the Token structure.
memset( &Token, 0, sizeof (TOKEN) );
// Set the expression token to
// szName = "SiteByCode"
// dwOp = QOP_STR_EQ
// szValue = "TIM"
// Set the method of collection.
strcpy( Token.szName, "SiteByCode");
// Set the operator to string equals.
Token.dwOp = QOP_STR_EQ;
// Set the site code to TIM.
strcpy( Token.szValue, "TIM");
// 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 Site filter.
&Token, // Specifies the structure containing
// the expression token.
AT_END // Add 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;
}