SMS Context Qualifiers
Context objects are used to provide additional information to the SMS Provider that cannot be passed as a parameter to a WMI API method. You use the IWbemContext interface to register your context qualifiers. The interface pointer for the context object is passed as the last parameter of an IWbemServices method. You should pass a context object on every call to an IWbemServices method.
Use the SWbemNamedValueSet interface to create context qualifiers when using the WMI Scripting API. This interface creates a collection of named value objects, which are the same as the context qualifiers used in the COM API for WMI.
For more information on setting the SMS context qualifier using the IWbemContext and SWbemNamedValueSet interfaces, see the WMI SDK documentation. For an example that sets LocaleID, MachineName, and ApplicationName context qualifiers, see Creating A Context Object.
The following table contains the context qualifiers (named values) used by the SMS Provider. Most qualifiers, like SessionHandle, are only used in conjunction with specific functional areas of the provider, whereas LocaleID, MachineName, and ApplicationName should be set for all IWbemServices calls.
| Context qualifier | Description |
|---|---|
| ApplicationName | Identifies the application that made the call. |
| ContextHandle | Identifies where the SMS Provider has stored your cached context qualifiers. |
| InstanceCount | Limits the number of instances returned from IWbemServices::ExecQuery and IWbemServices::CreateInstanceEnum. |
| LimitToCollectionIDs | Limits the results of a resource query to the members of the named collections. |
| LocaleID | Identifies the code page to use. |
| MachineName | Identifies which computer is running the application. |
| QueryQualifiers | Returns the SecurityVerbs bit flags when you execute queries against secured objects. |
| SessionHandle | Identifies your application's copy of the site control file to SMS. |
ApplicationName
The ApplicationName context qualifier is a string value that identifies the name of the application that made the call. You should specify ApplicationName for your application because it is used for auditing. If you do not supply the name of your application, a value of Unknown is used. You must supply the ApplicationName value when you call any of the raise status message methods, such as SMS_StatusMessage::RaiseErrorStatusMsg, or the call will fail.
ContextHandle
The ContextHandle context qualifier is a string value that identifies where the SMS Provider has stored your cached context qualifiers. You can use this mechanism to reduce the amount of data being passed over the network. Follow these steps to cache your context qualifiers:
- Create a context object (or a named value set for scripting users).
- Add your qualifiers to the context object.
- Call the SMS_ContextMethods::GetContextHandle method to cache your qualifiers on the server. The provider caches the context object that you pass as a parameter of ExecMethod when you call GetContextHandle.
- Remove all the qualifiers from your context object
- Add the ContextHandle qualifier and value to your context object.
- Pass the context object on all calls to IWbemServices.
You must call the SMS_ContextMethods::ClearContextHandle method to remove your cached qualifiers before you end your application. You can create as many ContextHandle values as you want, with each providing varying information used by your application.
Note that after you cache your context qualifiers, you can override your cached values by adding the same context qualifiers, with different values, to your context object.
InstanceCount
The InstanceCount context qualifier is an integer value used to limit the number of instances returned from the IWbemServices::ExecQuery and IWbemServices::CreateInstanceEnum methods. You set InstanceCount equal to the maximum number of instances you want returned from the query or enumerator. For example, setting InstanceCount to 10 will return, at most, 10 instances.
LimitToCollectionIDs
The LimitToCollectionIDs context qualifier is a string array that contains a list of CollectionID values. Currently, you can specify only one CollectionID. You use this qualifier to limit the results of a resource query to the members of the named collection. A resource query is a query that includes classes derived from SMS_Resource or SMS_Group.
The user must have instance read resource permissions for the collection to which the resource belongs. You must use collection limiting when the user does not have class read resource rights for collections; otherwise, no data is returned. From SMS Service Pack 1 and later, this restriction applies only to classes derived from SMS_Group.
You cannot use this qualifier when querying collections.
LocaleID
The LocaleID context qualifier is an integer value that accepts either a hexadecimal value or a decimal value in the form "MS\x", where x is the locale ID. For example, you can enter the English LocaleID value as ms\0x0409 or ms\1033. The provider only accepts LocaleID values that use the Microsoft format. You can find a list of locale IDs in Writing International Software, published by Microsoft Press®.
The LocaleID context qualifier is used by all IWbemServices methods. You should use the LocaleID context qualifier in preference to setting the strLocale parameter in the IWbemLocator::ConnectServer method. This eliminates localization errors that may occur because WMI provides only the locale ID for a user and namespace combination. For example, if a user connects to the same namespace on different computers that are running different language operating systems, the user will experience localization errors.
MachineName
The MachineName context qualifier is a string value that identifies which computer is running the application. You should specify MachineName for your application because it is used for auditing. If you do not supply the computer name, a value of Unknown is used. You must supply the MachineName value when you call any of the raise status message methods, such as SMS_StatusMessage::RaiseRawStatusMsg, or the call will fail.
QueryQualifiers
The QueryQualifiers context qualifier is a Boolean value that is used to return the SecurityVerbs bit flags when you execute queries against secured objects, such as SMS_Site or SMS_Package. Note that using QueryQualifiers when querying unsecured objects generates an error. By default, SecurityVerbs flags are not returned with the query. You must create this qualifier and set its value to TRUE if you want the flags returned. Not creating QueryQualifiers is the same as setting its value to FALSE. For more information on secured and unsecured objects, see Security.
SessionHandle
The SessionHandle context qualifier is a string value that is returned as an out parameter of the SMS_SiteControlFile::GetSessionHandle method. The string is a unique GUID that identifies your application's copy of the site control file to SMS. You should use this mechanism to modify the site control file and reduce data collisions with other applications that are modifying the site control file at the same time. If you do not supply a SessionHandle value, your application modifies the global copy of the site control file, which has no protection from applications overwriting each other's data.