CA_ServerGetGlobalData

Download PDF

Updated2023-02-21
3 minute(s) read

HRESULT CA_ServerGetGlobalData (HINSTANCE serverHInstance, void *moduleData);

Purpose

Obtains the global data associated with your ActiveX server.

Note Use the CA_ServerSetGlobalData, CA_ServerGetGlobalData, and CA_ServerReleaseGlobalData functions to manage any global data associated with the server. These functions protect the global data from multithread access based on the server's threading model. If you do not use these functions, you must protect any global data from multithread access.

Note This function acquires a lock to protect your data from multithread access. When you are done using the data returned by this function, you must call CA_ServerReleaseGlobalData to release the lock.

Example Code

The following code demonstrates the use of global data functions:

// Structure to represent the global data
typedef struct __MyGlobalData {
   double dVal;
   int iVal;
} MyGlobalData;

// Global variable to hold the global data
// This memory will always be valid
MyGlobalData g_Data = {3.1415, 4};

// Fragment from main function (DllMain or WinMain)
// Initializes the server and sets the global data
if (FAILED (ServerInit (hInstance, ...)))
   return failureCode;
if (FAILED (CA_ServerSetGlobalData (hInstance, &g_Data))) {
   ServerUninit (hInstance);
   return failureCode;
}

// Simple function that uses the global data
HRESULT UseGlobalData (HINSTANCE hInstance, double dV, int iV)
{
   HRESULT hr;
   void *pvGlobalData = NULL;

   // Get ptr to global data
   hr = CA_ServerGetGlobalData (hInstance, &pvGlobalData);
   if (FAILED (hr))
      return hr;

   if (pvGlobalData) {
      // Use global data
      MyGlobalData pData = (MyGlobalData*) pvGlobalData;
      printf ("Double Data: %f, Int Data: %d");

      pData.dVal = dV;
      pData.iVal = iV;

      // Prevent further use of ptr to global data
      pvGlobalData = NULL;
   }

   // Release ptr to global data
   // MUST be called because CA_ServerGetGlobalData succeeded
   hr = CA_ServerReleaseGlobalData (hInstance);
   return hr;
}

Parameters

Input
Name	Type	Description
serverHInstance	HINSTANCE	The HINSTANCE of your server. Note that the HINSTANCE is passed in as an argument to DllMain and WinMain. If your code uses main instead of WinMain as the module entry point, this value is not available. Therefore, EXE servers must use WinMain as their entry point.
Output
Name	Type	Description
moduleData	void *	Data associated with your server.

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.

Note You should not return the ActiveX Library error codes from your ActiveX server to your ActiveX clients, unless you document them in your server documentation. An acceptable compromise in this case is to return E_UNEXPECTED to the clients.

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 6.0 and later

LabWindows/CVI