HOWTO: Pass Arrays Between Visual Basic and C

ID: Q207931

The information in this article applies to:

Microsoft Visual Basic Learning, Professional, and Enterprise Editions for Windows, versions 5.0, 6.0
Microsoft Visual C++, 32-bit Editions, versions 5.0, 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. (Editor's Note: This sentence needs clarification): Let's say that we would like a function which declared in Visual Basic should be:


   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.

Create a Win32 DLL in Visual C named MyStDll.

Add a new header file and paste the following code into it:


    /* prototypes */ 
    #include <windows.h>
    #include <oleauto.h>

    long __declspec (dllexport) __stdcall AddLongs_Pointer(long
    *plArrayOfLongs, long lElements);

    long __declspec (dllexport) __stdcall AddLongs_SafeArray(SAFEARRAY
    **psaArray, long *plSum);

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);
   }

Add a .def file to your project and paste in the following code:


EXPORTS
   AddLongs_Pointer @1
   AddLongs_SafeArray @2

Press F7 to build the DLL.

In Visual Basic create a new Standard EXE project. Form1 is created by default.

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

Press F5 to run this project.

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.

In Visual C create an ATL DLL using the ATL COM AppWizard. Name it MyAtlDll.

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

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);

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<lElements; iCount++)
         *plSum = *plSum + pArrayElements[iCount];

      // releasing the array
      lResult=SafeArrayUnlock(*psaArray);
      if (lResult) return(lResult);

      return S_OK;
   }

Build the DLL by pressing the F7 key.

In Visual Basic, create a new Standard EXE project. Form1 is created by default.

Place a command button named Command1 on Form1.

Select References from the Project menu and add a reference to the ActiveX DLL created previously (MyAtlDll).

Paste the following code into the Click event of Command1:


   Private Sub Command1_Click()
      Dim MyObj As New MYATLDLLLib.MyClass
      Dim ArrayOfLongs(3) As Long
      Dim lSum As Long

      ArrayOfLongs(0) = 1
      ArrayOfLongs(1) = 2
      ArrayOfLongs(2) = 3

      MyObj.AddLongs ArrayOfLongs, lSum
      MsgBox "Result from ATL dll = " & Str$(lSum)
   End Sub

Press F5 to run your project.

Click Command1. You should see a message box that displays the value 6 returned from the AddLongs method.

REFERENCES

MSDN Library: Platform SDK; COM and ActiveX Object Services; Automation; Conversion and Manipulation Functions; Array Manipulation API Functions

MSDN Library: Technical Articles; Visual Tools; Visual Basic; Extending Visual Basic with C++ DLLs.

VB5Dll.doc: This file is located on your Microsoft Visual Basic 5.0 installation CD, in the \Tools\Docs directory.

For additional informationabout the 'Note for Visual C version 6.0' section mentioned previously, click the article number below to view the article in the Microsoft Knowledge Base:

Q198017 BUG: Unexpected Error Using ATL Interface Wizard to Add Methods

For additional informationon working with Visual C++ DLLs from Visual Basic, click the article numbers below to view the articles in the Microsoft Knowledge Base:

Q188541 INFO: Visual Basic Requirements for Using Exported DLLs

Q171583 HOWTO: Fill a 32-bit VBA Array of UDType via a Visual C++ DLL

Q194609 HOWTO: Pass Array of UDTs with Variable Length Strings to C/C++

Q177218 HOWTO: Return Array to VB from VC++ DLL or OLE Server

Additional query words:

Keywords : kbATL kbDLL kbVBp kbVBp500 kbVBp600 kbVC kbVC500 kbVC600 kbGrpVB kbDSupport
Version : WINDOWS:5.0,6.0; winnt:5.0,6.0
Platform : WINDOWS winnt
Issue type : kbhowto