DOCUMENT:Q207931 11-JUL-2001 [vbwin] TITLE :HOWTO: Pass Arrays Between Visual Basic and C PRODUCT :Microsoft Visual Basic for Windows PROD/VER::5.0,6.0 OPER/SYS: KEYWORDS:kbATL kbDLL kbVBp kbVBp500 kbVBp600 kbVC kbVC500 kbVC600 kbGrpDSVB kbDSupport ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual Basic Learning Edition for Windows, versions 5.0, 6.0 - Microsoft Visual Basic Professional Edition for Windows, versions 5.0, 6.0 - Microsoft Visual Basic Enterprise Edition for Windows, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Enterprise Edition, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Professional Edition, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Learning Edition, version 6.0 ------------------------------------------------------------------------------- SUMMARY ======= This article discusses some aspects related to passing data in arrays between Microsoft Visual Basic and C functions. It compares the Standard C array and the SAFEARRAY data types, and discusses the different scenarios when calling C functions from Visual Basic or writing functions in C. The following scenarios are discussed: - Scenario 1: Passing an array from Visual Basic to a function expecting a pointer. - Scenario 2: Writing a function in C/C++ to receive a SAFEARRAY. - Scenario 3: Declaring SAFEARRAYs in Component Object Model (COM) DLLs written in C. In the "More Information" section there are some code samples that illustrate the scenarios discussed. NOTE: The code samples use a one-dimensional array as an example. If you pass multi-dimensional arrays, you need to keep in mind that SAFEARRAY is column-major, while the array in C is row-major. MORE INFORMATION ================ In Microsoft Visual Basic an array is stored as a SAFEARRAY. In C it is basically a pointer to the first element of the array. While a SAFEARRAY provides information on the array size, dimensions, and so forth, the C way of using just a pointer leaves all the responsibility of controlling the data to the programmer. You will find a more detailed explanation about SAFEARRAYs in Scenario 2. Scenario 1: Passing an Array from Microsoft Visual Basic to a Function Expecting a Pointer ------------------------------------------------------------------------------------------ It is common to call from Microsoft Visual Basic a function in a DLL not specifically intended for Visual Basic, such as Windows API functions. Since the C function expects the address of the first element of the array, you can accomplish this in Visual Basic by passing the first element of the array by reference. For example, the following is the prototype of a C function that returns the sum of long integers in an array. The first parameter is a pointer to the array and the second provides the number of elements in the array. long AddLongs_Pointer(long *plArrayOfLongs, long lElements); The Visual Basic version of the function declaration looks like this: Declare Function AddLongs_Pointer Lib "MyDll.dll" (FirstElement As Long, ByVal lElements As Long) As Long To call the function, use the following code: Dim MyArrayOfLongs(0 to 10) as Long Dim lTotal as Long ' Insert code here to initialize the elements of the array ' Calling the function lTotal = AddLongs_Pointer (MyArrayOfLongs(0), UBound(MyArrayOfLongs) + 1) LIMITATIONS: See the "Important Considerations" topic. Scenario 2: Writing a Function in C to Receive a SAFEARRAY ---------------------------------------------------------- To write a function in C to receive or return an array from or to Visual Basic, you need to use SAFEARRAY as the parameter type. You will be able to call the function naturally within Visual Basic, as if it were written in Visual Basic. You will also be able to check if enough memory was allocated and if the dimensions are adequate. In some circumstances, you will even be able to resize the dimension of the array. SAFEARRAY is basically a structure that provides important information about an array, including a pointer to the actual elements of the array. SAFEARRAY is defined in the OLEAUTO.H header. This header also includes prototypes for a set of API functions used to manipulate SAFEARRAYs. In Win32, after replacing all typedefs and conditionals included in its declaration, this is what SAFEARRAY looks like: struct SAFEARRAY { WORD cDims; // number of dimensions WORD fFeatures; // bitfield indicating attributes of a particular // array DWORD cbElements; // size of an element of the array DWORD cLocks; // lock counter Void * pvData; // pointer to the array's elements (use only if // cLocks>0) SAFEARRAYBOUND rgsabound[1]; // structure containing information for // each dimension }; The SAFEARRAYBOUND member is also a structure and looks like the following: struct SAFEARRAYBOUND { DWORD cElements; // number of elements on a given dimension long lLbound; // lower boundary on a given dimension }; It is beyond the scope of this article to describe in detail how to operate a SAFEARRAY in C or C++. You can find this information in the references provided. The purpose here is to show you how to prototype your function in C to make it work correctly with Visual Basic. The following example demonstrates how to create a function that takes an array of longs as a parameter: Declare Function AddLongs_SafeArray Lib "MyDll.dll" (FirstElement() As Long, lSum As Long) As Long The C declaration will need to look like this: long AddLongs_SafeArray(SAFEARRAY **psaArray, long *plSum); Note that now the function does not need a parameter to show how many elements are in the array. This information is included in the SAFEARRAY structure. LIMITATIONS: See the "Important Considerations" topic. Scenario 3: Declaring SAFEARRAYS in COM DLLs Written in C --------------------------------------------------------- To use Type libraries or COM DLLs, you should always declare SAFEARRAY parameters as [in,out] for it to work correctly in Visual Basic. This is how your declaration should look: STDMETHOD(AddLongs)(/*[in,out]*/ SAFEARRAY ** psaMyArray, /*[in,out]*/ long *plSum); The .idl file contains the following declaration: [id(1), helpstring("method AddLongs")] HRESULT AddLongs([in,out] SAFEARRAY (long) * psaMyArray, [in,out] Long *plSum); Important Considerations ------------------------ - The solutions described in Scenarios 1 and 2 cannot be used with arrays of strings or User Defined Types (UDTs) containing strings. This is due to the intrinsic UNICODE/ANSI conversion performed by Visual Basic when calling DLL functions. However, this limitation does not apply to functions defined in Type libraries, so the solution described in Scenario 3 is valid for arrays of strings or UDTs containing strings. - Microsoft Visual Basic version 5.0 and earlier versions of Visual Basic cannot handle SAFEARRAY as return values. In Microsoft Visual Basic version 6.0, this is possible and the C prototype would be something like this: STDMETHOD(ReturnAnArray) (/*[out,retval]*/SAFEARRAY **psaArray); Sample Code ----------- Here are some code samples that demonstrate the concepts described in this article. The first sample has two functions, the first (AddLongs_Pointer) related to Scenario 1 and the second (AddLongs_SafeArray) related to Scenario 2. The second sample has only one function (AddLongs) and is related to Scenario 3. Sample 1: This sample calculates the sum of an array of long integers using two functions in a Win32 DLL. The first function expects a pointer to a standard C array and the second one uses a SAFEARRAY. Both should return the same value. 1. Create a Win32 DLL in Visual C named MyStDll. 2. Add a new header file and paste the following code into it: /* prototypes */ #include #include long __declspec (dllexport) __stdcall AddLongs_Pointer(long *plArrayOfLongs, long lElements); long __declspec (dllexport) __stdcall AddLongs_SafeArray(SAFEARRAY **psaArray, long *plSum); 3. Add a new source code file with the following code: /* functions */ #include "MyDll.h" // use here the name of your header file /*======================================================== AddLongs_Pointer - a function to add all elements of an array passed as a pointer (long *) returns the sum of the elements ==========================================================*/ long __declspec (dllexport) __stdcall AddLongs_Pointer( long *plArrayOfLongs, // the array's pointer long lElements) // number of elements to add { long lSum; long i; lSum = 0; if(lElements > 0) { for (i=0; i < lElements; i++) lSum = lSum + plArrayOfLongs[i]; } // returning return(lSum); } /*=============================================================== AddLongs_SafeAray - a function to add all elements of an one-dimensional array of longs return codes: 0 - Success >0 - Failure =================================================================*/ long __declspec (dllexport) __stdcall AddLongs_SafeArray( SAFEARRAY **psaArray, // the array to use long *plSum) // returns the sum of all elements of the array { long lElements; // number of elements in the array long iCount; HRESULT lResult; // return code for OLE functions long *pArrayElements; // pointer to the elements of the array // initializing the output *plSum=0; // checking if it is an one-dimensional array if ( (*psaArray)->cDims != 1 ) return(1); // checking if it is an array of longs if ( (*psaArray)->cbElements != 4 ) return(2); // how many elements are there in the array lElements=(*psaArray)->rgsabound[0].cElements; // locking the array before using its elements lResult=SafeArrayLock(*psaArray); if(lResult)return(3); // using the array pArrayElements=(long*) (*psaArray)->pvData; for (iCount=0; iCount < lElements; iCount++) *plSum = *plSum + pArrayElements[iCount]; // releasing the array lResult=SafeArrayUnlock(*psaArray); if (lResult) return(4); // returning return(0); } 4. Add a .def file to your project and paste in the following code: EXPORTS AddLongs_Pointer @1 AddLongs_SafeArray @2 5. Press F7 to build the DLL. 6. In Visual Basic create a new Standard EXE project. Form1 is created by default. 7. Place a command button named Command1 on Form1 and paste the following code into Form1's code window: Option Explicit Private Declare Function AddLongs_Pointer Lib "MyStDll.dll" _ (FirstElement As Long, ByVal lElements As Long) As Long Private Declare Function AddLongs_SafeArray Lib "MyStDll.dll" _ (FirstElement() As Long, lSum As Long) As Long Private Sub Command1_Click() Dim ArrayOfLongs(2) As Long Dim lSum As Long Dim k As Long ArrayOfLongs(0) = 1 ArrayOfLongs(1) = 2 ArrayOfLongs(2) = 3 lSum = AddLongs_Pointer(ArrayOfLongs(0), UBound(ArrayOfLongs)+1) MsgBox "Result with C array = " & Str$(lSum) k = AddLongs_SafeArray(ArrayOfLongs(), lSum) If k = 0 Then MsgBox "Result with Safearray = " & Str$(lSum) Else MsgBox "Call with Safearray failed" End If End Sub 8. Press F5 to run this project. 9. Click Command1. You should see two message boxe. The first one displays the returned value of the first function and passes a pointer to the array. The second one displays the result returned from the second function that used the SAFEARRAY. Both functions return number 6. Sample 2: This sample calculates the sum of long integers in a SAFEARRAY using a function in an ActiveX DLL created with the ActiveX Template Library (ATL) wizard. 1. In Visual C create an ATL DLL using the ATL COM AppWizard. Name it MyAtlDll. 2. From the Insert menu, select New ATL Object. Highlight Objects in the category list and select Simple Object in the Objects list. Click Next. Type in MyClass in the Short Name field, and then click the Attributes tab. Check the following options and then click OK: Threading Model: Apartment Interface: Dual Aggregation: Yes 3. On the ClassView pane in the workspace, right-click IMyClass and select Add Method. Type AddLongs in the Method Name text box and type the following in the Parameters text box: [in,out] SAFEARRAY (long) *psaMyArray, [in,out] long *plSum Note for Visual C version 6.0: If you are using Visual C version 6.0 you may receive the following error message: Unable to create the function because the header or the implementation file could not be found. This is a known issue in the wizard of Visual C version 6.0. You can by pass this error by manually changing the parameters for the AddLongs method in the header, source and .idl files as explained here: In the Parameters list type in: [in,out] long *psaMyArray, [in,out] long *plSum On the FileView tab in the workspace, expand MyAtlDll files. Under the header files double-click the MyClass.h header file. At the very end of this file you will find the declaration of your method: STDMETHOD(AddLongs)(/*[in,out]*/ long *psaMyArray, /*[in,out]*/ long *plSum); Change it to the following: STDMETHOD(AddLongs)(/*[in,out]*/ SAFEARRAY **psaMyArray, /*[in,out]*/ long *plSum); Under the Source Files list double-click MyClass.cpp. Here you will find the implementation of your method. Change the following line: STDMETHODIMP CMyClass::AddLongs(long *psaMyArray, long *plSum) to: STDMETHODIMP CMyClass::AddLongs(SAFEARRAY **psaMyArray, long *plSum) Also, under the Source Files list, double-click the .idl file (the only one with an .idl extension) and locate the following line: [id(1), helpstring("method AddLongs")] HRESULT AddLongs([in,out] long *psaMyArray, [in,out] long *plSum); Change it to: [id(1), helpstring("method AddLongs")] HRESULT AddLongs([in,out] SAFEARRAY(long) *psaMyArray, [in,out] long *plSum); 1. Double-click the implementation file, MyClass.cpp, under the Source Files list. In the implementation file add the following code to your function: STDMETHODIMP CMyClass::AddLongs(SAFEARRAY * * psaArray, long * plSum) { // TODO: Add your implementation code here long lElements; // number of elements in the array long iCount; HRESULT lResult; // return code for OLE functions long *pArrayElements; // pointer to the elements of the array // initializing the output *plSum=0; // checking if it is a one-dimensional array if ( (*psaArray)->cDims != 1 ) return(E_FAIL); // checking if it is an array of longs if ( (*psaArray)->cbElements != 4 ) return(E_FAIL); // how many elements are there in the array lElements=(*psaArray)->rgsabound[0].cElements; // locking the array before using its elements lResult=SafeArrayLock(*psaArray); if(lResult)return(lResult); // using the array pArrayElements=(long*) (*psaArray)->pvData; for (iCount=0; iCount