SmsManipulateTokens

The SmsManipulateTokens function deletes, excludes, groups, or ungroups tokens within a filter or an inventory rules folder.

SMS_STATUS SmsManipulateTokens(
  HANDLE hFilter, // Handle to filter or inventory rules folder.
  DWORD dwFlags,  // Flag that specifies the operation to perform on 
                  // a range of tokens.
  INT iStart,     // Index of the token at the beginning of the 
                  // range.
  INT iEnd        // Index of the token at the end of the range.
);
 

Parameters

hFilter

Specifies the handle to the filter or inventory rules folder where you want to perform the token operation.

dwFlags

Specifies the operation to perform on the specified range of tokens. Four operations are supported:

TOK_GROUP

Groups the specified range of tokens into a subclause grouped together with parentheses.

TOK_UNGROUP

Ungroups the the specified range of tokens. Note that iStart and iEnd must specify a range of tokens that is an existing group.

TOK_DELETE

Deletes the specified range of tokens.

TOK_GROUP_NOT

Groups the specified range of tokens into a subclause and selects the group of objects that do not satisfy the conditions in that subclause.

iStart

Specifies the index of the token at the beginning of the range of tokens. Note that the value AT_START can be used to specify the index for first token in a filter or inventory rules folder.

Note that the indexes for tokens within a filter or inventory rules folder start with zero.

iEnd

Specifies the index of the token at the end of the range of tokens. Note that the value AT_END can be used to specify the index for last token in a filter or inventory rules folder.

Return Values

The SmsManipulateTokens 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 or inventory rules folder handle.

SMS_UNSUPPORTED

The TOK_GROUP_NOT flag is specified for a folder.

SMS_PARAMETER_ERROR

Value set for dwFlags is an unrecognized value.

SMS_RANGE_ERROR

The specified token indexes are outside of the range of tokens in the filter or the inventory rules folder. Or the operation specified by dwFlags cannot be performed on the specified range of tokens.

Remarks

The parameters iStart and iEnd must specify a range of tokens that is valid for the operation specified by dwFlags:

TOK_DELETE

To delete a range of tokens, iStart and iEnd must specify a range of tokens that constitutes a clause. A clause is the combination of an expression token (or subclause) and its adjacent logical operator. However, if the filter or inventory rules folder contains only one expression token, your application can delete the single token by specifying a range containing only that token (iStart equal to zero and iEnd equal to zero). To delete all tokens in a filter or inventory rules folder, your application can also use the range iStart equal to AT_START and iEnd equal to AT_END.

For example, the following tokens are in an inventory rules folder:

WINWORD.EXE
AND
WINWORD.INF
AND
WINWORD.INI

A range of iStart equal to 0 and iEnd equal to 1 leaves the following tokens:

WINWORD.INF
AND
WINWORD.INI

A range of iStart equal to AT_START and iEnd equal to AT_END deletes all the tokens.

A range of iStart equal to 3 and iEnd equal to 5 returns an SMS_RANGE_ERROR (and no tokens are removed) because if the specified range were removed, an invalid set of tokens would remain in the folder.

TOK_GROUP

To group a range of tokens, iStart and iEnd must specify a range of tokens that constitutes a subclause. A subclause is a set of expression tokens that can be logically treated as a single expression token. A subclause starts and ends with an expression token.

For example, the following tokens are in an inventory rules folder:

WINWORD.EXE
AND
WINWORD.INF
AND
WINWORD.INI

A range of iStart equal to 0 and iEnd equal to 2 groups the following tokens:

(
   WINWORD.EXE
   AND
   WINWORD.INF
)
AND
WINWORD.INI

A range of iStart equal to 1 and iEnd equal to 3 returns an SMS_RANGE_ERROR (and no tokens are grouped) because if the specified range were grouped, an invalid set of tokens would be formed in the folder.

TOK_UNGROUP

To ungroup a range of tokens, iStart and iEnd must specify a range of tokens that is an existing group. A group starts with a TOKEN_OPENPAREN token and ends with a TOKEN_CLOSEPAREN token. The range must have an iStart index that specifies a TOKEN_OPENPAREN token and an iEnd index that specifies a TOKEN_CLOSEPAREN token; otherwise, SmsManipulateTokens does not perform any action and returns SMS_RANGE_ERROR.

For example, if the following tokens are in an inventory rules folder:

WINWORD.EXE
AND
(
   WINWORD.INF
   AND
   WINWORD.INI
)

A range of iStart equal to 2 and iEnd equal to 6 results in the following set of tokens:

WINWORD.EXE
AND
WINWORD.INF
AND
WINWORD.INI

A range of iStart equal to 1 and iEnd equal to 3 returns an SMS_RANGE_ERROR (and no tokens are ungrouped) because if the specified range were ungrouped, an invalid set of tokens would be formed in the folder.

TOK_GROUP_NOT

The rules for the use of iStart and iEnd with TOK_GROUP_NOT are the same as for TOK_GROUP. TOK_GROUP_NOT groups the specified range of tokens and precedes them with NOT IN, which has the effect of inverting the selection criteria of the grouped tokens. This flag can only be used with persistent filters (currently, only filters of the type MACHINE_FILTER).

The indexes of the tokens within the filter or inventory rules folder are adjusted according to the operation performed. For example, a grouping of a range of tokens causes control tokens to be added for the opening and closing parentheses, and the indexes of the tokens following index iStart are adjusted to accommodate the addition of those control tokens. The indexes of the tokens starting at index iStart and ending at iEnd are incremented by 1. At the iStart index, the TOKEN_OPENPAREN token is added. After the iEnd token, the TOKEN_CLOSEPAREN is added. The indexes of tokens after iEnd are incremented by 2.