CA_CreateObjHandleFromInterface
- Updated2023-02-21
- 2 minute(s) read
CA_CreateObjHandleFromInterface
HRESULT CA_CreateObjHandleFromInterface (void *interacePtr, const IID *interfaceId, int supportMultithreading, LCID locale, intptr_t reserved, int callAddRef, CAObjHandle *objectHandle);
Purpose
Creates a CAObjHandle when you already have an IDispatch derived interface pointer to an ActiveX object.
You must call CA_InitActiveXThreadStyleForCurrentThread with COINIT_APARTMENTTHREADED if you register any ActiveX event callbacks and want the callbacks to be called from the same thread in which they were registered. If you do not call CA_InitActiveXThreadStyleForCurrentThread with COINIT_APARTMENTTHREADED, your callbacks will be called from a system thread.
Parameters
| Input | ||
| Name | Type | Description |
| interacePtr | void * | An interface pointer to an ActiveX server object. The interface must be derived from IDispatch. |
| interfaceId | const IID * | The interface id specifying the type of the interface pointer parameter. |
| supportMultithreading | int | Specify a nonzero value or select Yes in the function panel to use the object from multiple threads. Specify 0 or select No in the function panel to use the object only from the thread that calls this function. The ActiveX Library uses the COM Global Interface Table (GIT) to allow you to use an object handle from threads other than the thread in which it was created. There is overhead associated with using the GIT, which you should try to avoid when possible. If you do not pass the CAObjHandle between threads in your application, you do not need to use the GIT, and you can pass 0 for this parameter. You do not need to use the GIT if all of the threads in which you use an object handle belong to the multithreaded apartment. You can call CA_InitActiveXThreadStyleForCurrentThread with COINIT_MULTITHREADED as the threading style. Refer to www.msdn.com for more information about threads and apartments. |
| locale | LCID | The locale you want to use. Usually, you should pass LOCALE_NEUTRAL, which signifies the default locale of the server. Refer to www.msdn.com for more information. |
| reserved | intptr_t | This parameter is reserved and must be zero. |
| callAddRef | int | Specify a nonzero value or select Yes in the function panel to invoke the AddRef method of the object. Specify 0 or select No in the function panel if you do not want to call the AddRef method of the object. |
| Output | ||
| Name | Type | Description |
| objectHandle | CAObjHandle | A handle to the requested ActiveX object. Use this handle to call methods or get and set properties of this ActiveX object. When this handle is no longer needed, discard it by calling CA_DiscardObjHandle. |
Return Value
| Name | Type | Description |
| status | HRESULT | A value indicating whether an error occurred. Negative error codes indicate function failure. Error codes are defined in CVIversion\include\cviauto.h and <Program Files>\National Instruments\Shared\MSDTRedistributables\SDKHeaderFiles\8.1\winerror.h. The LabWindows/CVI ActiveX Library explicitly returns error codes. Other error codes in winerror.h are generated by ActiveX servers and passed on to you by the LabWindows/CVI ActiveX Library. You can use CA_GetAutomationErrorString to get the description of an error code or CA_DisplayErrorInfo to display the description of the error code. |
Additional Information
Library: ActiveX Library
Include file: cviauto.h
LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later