CA_ServerGetEventObjHandles
HRESULT CA_ServerGetEventObjHandles (CAServerObjHandle serverObjectHandle, const IID *eventInterfaceId, int supportMultithreading, LCID locale, CAObjHandle eventObjectHandles[], unsigned int *numberOfEventObjectHandles);
Purpose
Gets the event object handles that client applications have registered with the server object to receive events through the specified event interface.
 |
Note Sample usage of this function is generated as comments in the ActiveX event wrapper function prototypes section of the ActiveX server header file. |
If this function returns successfully, you must call CA_ServerReleaseEventObjHandles to release the object handles and library data associated with them. You must call CA_ServerReleaseEventObjHandles even if CA_ServerGetEventObjHandles returns successfully with no object handles. CA_ServerReleaseEventObjHandles must be called from the same thread that called this function.
|
Note When you hold unreleased client event object handles, the LabWindows/CVI ActiveX Library might receive requests from client applications to register or unregister event objects. These requests might not be processed until the client event object handles have been released. Due to synchronization issues, you must refrain from calling any unnecessary functions between calls to CA_ServerGetEventObjHandles and CA_ServerReleaseEventObjHandles. |
Parameters
| Input | ||||
| Name | Type | Description | ||
| serverObjectHandle | CAServerObjHandle | The handle to an ActiveX object in your ActiveX server. | ||
| eventInterfaceId | const IID * | The outgoing event interface Id specified by the server object and implemented by client event objects. | ||
| 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. | ||
| Output | ||||
| Name | Type | Description | ||
| eventObjectHandles | CAObjHandle [] | A CAObjHandle array to hold the handles of the client event objects that are registered with the server object to receive events through the specified event interface. Pass an array that can hold at least CA_SERVER_MAX_EVENT_CONNECTIONS object handles. The number of object handles returned in this array is indicated by the numEventObjHandles output parameter. In addition, this array is terminated with zeroes. You must call CA_ServerReleaseEventObjHandles to release these object handles and library data associated with them. You must call CA_ServerReleaseEventObjHandles even if CA_ServerGetEventObjHandles returns successfully with no object handles. CA_ServerReleaseEventObjHandles must be called from the same thread that called this function.
|
||
| numberOfEventObjectHandles | unsigned int | The number of client event object handles returned in the eventObjHandles array. You can pass NULL for this parameter. |
||
Return Value
| Name | Type | Description | ||
| status | HRESULT | A value indicating whether an error occurred. Function failure is indicated by a negative error code. 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 the COM runtime and passed on to you by the 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.
The error codes defined in <Program Files>\National Instruments\Shared\MSDTRedistributables\SDKHeaderFiles\8.1\winerror.h are too numerous to display here. These error codes can be returned to your ActiveX clients. |
Additional Information
Library: ActiveX Library
Include file: cviauto.h
LabWindows/CVI compatibility: LabWindows/CVI 7.0 and later