Object Parameters - LabWindows/CVI Call Parameters

Object Parameters

The Object category includes the ActiveX Automation IDispatch Pointer (IDispatch *), ActiveX Automation IUnknown Pointer (IUnknown *), and LabWindows/CVI ActiveX Automation Handle (CAObjHandle) data types. Use these types to pass a reference to a TestStand object to the DLL function. You can also use these types to pass the value of an object reference property to the DLL function.

If you specify an object reference property as the value of an object parameter, TestStand passes the value of the property. Otherwise, TestStand passes a reference to the property object you specify. The DLL function can use the property object reference in conjunction with the TestStand API to get and set the values of properties in the object, to add properties to the object, and so on.

Note The 32-bit TestStand LabWindows/CVI Adapter treats 32-bit signed integer data types ( int or long ) as compatible with the LabWindows/CVI ActiveX Automation handle ( CAObjHandle ) data type. However, in 64-bit LabWindows/CVI DLLs, you must declare LabWindows/CVI ActiveX Automation handles as CAObjHandle for the 64-bit TestStand LabWindows/CVI Adapter to recognize them correctly. Although 32-bit TestStand supports integer declaration of LabWindows/CVI handles, National Instruments recommends declaring all LabWindows/CVI ActiveX Automation handles as CAObjHandle for 32-bit applications and 64-bit applications to address migrating from 32-bit TestStand to 64-bit TestStand.

Pass by Value or by Reference

When you select the Object category for a parameter, the LabWindows/CVI Adapter displays the Pass control. This control specifies whether TestStand passes the value of the argument you specify in the Value Expression control or passes a pointer to the argument. If you select By Reference (by pointer) , the LabWindows/CVI Adapter passes a pointer to the argument value.

When the DLL function stores the value of the object for later use after the function returns, the function must properly add an additional reference to the ActiveX Automation IDispatch Pointer or ActiveX Automation IUnknown Pointer or duplicate the LabWindows/CVI ActiveX Automation Handle. When you pass the object by reference and the DLL function alters the value of the reference, the function must release the original reference.

When you pass an array of object references that use the CAObjHandle data type and the DLL function alters the value of any of the array elements, do not use the function to discard the original handles the array elements contain. TestStand discards the original handles after the call completes.

If you choose to pass a pointer, the argument you specify in the Value Expression control must be the name of a variable or property.

Note You cannot pass NULL to an Object Reference pointer parameter. If you specify Nothing the LabWindows/CVI Adapter passes an empty ActiveX reference for the parameter. Do not pass the constant 0 .

See Also

Mapping Parameters

Pointers and Handles in 32-bit TestStand and 64-bit TestStand

Representing Pointers in Sequences in 32-bit TestStand and 64-bit TestStand

Representing Pointer-Sized Numbers in Sequences in 32-bit TestStand and 64-bit TestStand

TestStand ActiveX API Overview