Working with Output Parameters

[This is preliminary documentation and subject to change.]

Web-Based Enterprise Management (WBEM) observes the standard Component Object Model (COM) rules for passing input and output parameters. Observing the rules for output parameters is especially important because failing to observe them can result in memory leaks and unpredictable behavior.

If a method returns an interface pointer to its caller in an output parameter, it is the caller's responsibility to release the pointer when it is no longer needed. This is done by using the pointer to call Release. Because the Release method is part of the IUnknown interface, it is inherited by every WBEM interface.

For example, if an application calls the IWbemClassObject::GetPropertyQualifierSet method, a pointer to the IWbemQualifierSet interface is passed in the contents of the ppQualSet output parameter. The pointer can be released by calling IWbemQualifierSet::Release as is shown in the following sample:

IWbemQualifierSet* pSet;pObject->GetPropertyQualifierSet(strPropName, &pSet);if(pSet != NULL){  // call IUnknown::Release  pSet->Release();  // don't use pSet anymore!}
 

Because methods that return an interface pointer always set it to NULL whenever an error occurs, a Release call is necessary only if the method has been successful.

If a method has either a binary string (BSTR) or VARIANT output parameter, the incoming value of the parameter is ignored and overwritten by the method. With string parameters, either a new string is allocated or the contents of the original string is set to NULL. A memory leak results if the parameter has an initial value. It is the caller's responsibility to ensure that the output parameter does not contain data that requires deallocation. One option for string parameters is to always call SysFreeString; SysFreeString can be called regardless of the parameter's contents.

Always call VariantInit to initialize a VARIANT parameter. When finished using VARIANT data that is returned by a method, call VariantClear.