CA_RegisterEventCallback
- Updated2023-02-21
- 3 minute(s) read
HRESULT CA_RegisterEventCallback (CAObjHandle serverObject, const CAEventClassDefn *eventClassDefinition, int methodTableIndex, void *callbackFunction, void *callbackData, int enableCallbacks, int *callbackId);
Purpose
 |
Note Normally, you do not use CA_RegisterEventCallback. Instead, the functions that the ActiveX Controller Wizard generates use this function. |
Registers a callback for an ActiveX server object event. To register the callback, you must specify the CAObjHandle of the server object from which you want to receive events. The callback function has the following pseudo-prototype:
HRESULT CVICALLBACK Callback (CAObjHandle caServerObjHandle, void *callbackData, [server-defined parameters]);
Upon entry to the callback the caServerObjHandle parameter identifies the object that is firing the event. The callbackData parameter contains the value you passed in the callbackData parameter of this function. The other parameters are event-specific and are specified and (optionally) documented by the server.
Parameters
| Input | ||
| Name | Type | Description |
| serverObject | CAObjHandle | The CAObjHandle of the server object from which you want to receive events. |
| eventClassDefinition | const CAEventClassDefn * | A pointer to a CAEventClassDefn structure that describes the ActiveX event class for which you are registering the callback. |
| methodTableIndex | int | The index of the event in the table of event methods. The order of the event methods in the table is specified in the ActiveX server's type library. |
| callbackFunction | void * | The function that the ActiveX Library calls when the server fires the event. The callback function has the following pseudo-prototype: HRESULT CVICALLBACK Callback (CAObjHandle caServerObjHandle, void *callbackData, [server-defined parameters]); Upon entry to the callback the caServerObjHandle parameter identifies the object that is firing the event. The callbackData parameter contains the value you passed in the callbackData parameter of this function. The other parameters are event-specific and are specified and (optionally) documented by the server. |
| callbackData | void * | A value that you want the ActiveX Library to pass to your callback as the callbackData parameter. Do not pass the address of the of a local variable or any other variable that might not be valid when the callback is executed. |
| enableCallbacks | int | Specifies whether this registration function enables the registered callbacks for the server. Pass 1 to enable all of the registered callbacks in the event class associated with the server object passed in the Server Object parameter of this function. Pass 0 to specify that this call to the registration function will not enable the callbacks. Once the callbacks in an event class have been enabled for a particular server object, the value of this parameter is ignored for subsequent callback registration functions in the event class. Typically, you pass 1 to enable callbacks immediately. Pass 0 when you have a set of callbacks that must be enabled simultaneously in order for you to properly respond to the server events. In this case, you must explicitly advise the server when you are ready to begin receiving events. You can advise the server either by passing 1 for this parameter when you register the final callback, or by calling CA_EnableEventsForServerObject when you are ready to enable the callbacks. |
| Output | ||
| Name | Type | Description |
| callbackId | int | A unique identifier for the callback. Pass this identifier to CA_UnregisterEventCallback to unregister the callback. Pass NULL if you do not want the Callback Id. |
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