SmsAddToken

The SmsAddToken function adds a token at the specified index in the specified filter or inventory rules folder.

SMS_STATUS SmsAddToken(
  HANDLE hFilter, // Handle to filter or inventory rules folder.
  ANDOR opAndOr,  // Control token for connecting the expression to 
                  // adjacent expression.
  TOKEN *pTokenInfo,
                  // Pointer to token structure containing the 
                  // expression token.
  INT iIndex      // Location to insert the control token and 
                  // expression token.
);
 

Parameters

hFilter

Specifies the handle to the filter or inventory rules folder where the token will be added.

opAndOr

Specifies whether an OP_AND or OP_OR control token is used to connect to the adjacent expression token or subclause. See the ANDOR enumerated type.

Important For attribute filters, group filters, site filters, and architecture filters, tokens can only be connected using an OP_OR control token—this means that your application must pass OP_OR for the opAndOr parameter when calling the SmsAddToken function to add a token to one of these filter types. If your application passes OP_AND for the opAndOr parameter, a status of SMS_PARAMETER_ERROR is returned.

pTokenInfo

Specifies the TOKEN structure containing the information for the expression token to add to the filter or inventory rules folder.

iIndex

Specifies the location where the specified control token opAndOr and expression token pTokenInfo are inserted within the set of expressions contained in the specified filter or inventory rules folder. The new tokens are added after the token specified by iIndex. If any tokens follow the token specified by iIndex, the indexes for those tokens are incremented to account for the addition of the new tokens. There are also special index values that place the new tokens at the beginning or end of the set tokens within a filter or inventory rules folder.

AT_START

Specifies that the expression token will be inserted at the beginning of the filter or inventory rules folder, and the control token will be added after the expression token.

AT_END

Specifies that the control token will be inserted at the end of the filter or inventory rules folder, and the expression token will be added after the control token.

The index is an integer that represents a token's position within a filter or inventory rules folder. The index for the first token is always zero. If the filter or inventory rules folder is empty (that is, it contains no tokens), the expression token is added as the first token and no control token is added. If the index does not exist within the filter or inventory rules folder (that is, if the index is greater than the current number of tokens in the filter or inventory rules filter), the new tokens are added at the end of the filter or inventory rules filter.

Note Because the indexes of tokens following added tokens are modified to account for the new tokens, your application should not rely on the index to identify a token. Your application should use the SmsGetToken to verify the contents of the token. In addition, when your application is building a filter or inventory rules folder, it is recommended that your application use the AT_START or AT_END index values to add tokens to the filter or inventory rules folder sequentially.

When tokens are added or removed from a filter or inventory rules folder, the indexes of the tokens that follow the added or removed tokens are adjusted. For example, if a filter has five tokens (indexes 0, 1, 2, 3,and 4) and SmsAddToken is used to add a token at index 2, the new control token would be index 3 and the new expression would be index 4. The tokens that were previously at index 3 and 4 now have index 5 and 6.

Return Values

The SmsAddToken function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns the following manifest constants:

SMS_INVALID_HANDLE

The specified handle is not a valid filter handle or inventory rules folder handle.

SMS_PARAMETER_ERROR

One or more of the parameters in the TOKEN structure is invalid, or the pointer to the TOKEN structure is NULL.

If your application attempted to add a token to an inventory rules folder and the szTokenString member of the TOKEN structure also uses the retrieve keyword, the szTokenString member may contain a file name that specifies an incorrect location for the file. SmsAddToken will not add the token to the inventory rules folder and will return a status of SMS_PARAMETER_ERROR.

If your application passes OP_AND for the opAndOr parameter for an attribute filter, group filter, site filter, or architecture filter, a status of SMS_PARAMETER_ERROR is returned.

Remarks

For filters of type GROUP_FILTER, the SMS API engine does not validate the existence of the group specified by a group token. Your application is responsible for creating a token for a valid group class.

Example

// Add a token to the end of an architecture filter.
TOKEN Token;
memset( &Token, 0, sizeof (TOKEN) ); // Clear the Token structure.

//**************************************************************
//******* Set the expression token to "Architecture is equal to 
//******* Personal Computer".
// Set the name of the value to be evaluated.
strcpy( Token.szName, "Architecture");

// Set the operator used to evaluate the expression.
Token.dwOp = QOP_STR_EQ; // Use the equals operator.

// Set the value to evaulate.
strcpy( Token.szValue, "Personal Computer"); 

// Add the token to the filter.
stat = SmsAddToken( hFilter, // Specifies the handle to filter.
                    OP_AND,  // Use the AND control token to connect
                             // the expression.
                    &Token,  // Specifies the structure containing
                             // the expression token.
                    AT_END   // Add the token to the end of 
                             // the filter.
                  );