Creating XLLs and DLLs that Call Back into Excel

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

If your DLL is self-contained or only relies on other libraries, you must know how to enable Microsoft Office Excel to access its functions and commands. For more information, see How to: Access DLLs in Excel.

However, if your DLL needs to access Excel functionality, for example, to get the contents of a cell, to call a worksheet function, or to interrogate Excel to obtain workspace information, your code must be able to call back into Excel.

The Excel C API provides several functions that enable DLLs to call back into Excel. To access these, the DLL must be linked statically at compile time with the Excel 32-bit library, xlcall32.lib. The static library is downloadable from Microsoft as part of the .

Enabling DLLs to Call Back into Excel

For a DLL to be able to access the functionality in Excel and get or set workspace information, it must first obtain the addresses of the Excel callback functions Excel4, Excel4v, Excel12, and Excel12v. The last two are introduced in Microsoft Office Excel 2007. To access all of these, the DLL project must include references to the following files in Excel 2007. If you want to access only the first two callbacks (in any version of Excel), your project needs to include only the first two files.

You can download these files and the Framework project from the Download Center.

xlcall.h

The xlcall.h file contains the following:

Function prototypes for all callback functions.
Definitions of the data structures that the callbacks used to exchange data between the DLL/XLL and Excel and data type constant definitions.
Definitions of the C API function and command equivalents of the worksheet, macro sheet functions, and supported Excel commands.
Definitions of callback function return values.

You should #include this file, directly or indirectly via another header file, in all files that access the C API or that handle data types used by the C API.

xlcall32.lib

The xlcall32.lib library exports the first two callbacks, Excel4 and Excel4v, and also the XlCallVer function. Without a reference to this library in your project, the linker cannot create the XLL if you have used any of these callbacks in your code. (You can obtain the addresses of these functions by linking dynamically to the equivalent xlcall32.dll that is copied to your system as part of a normal Excel installation.)

xlcall.cpp

The Excel 2007 callbacks Excel12 and Excel12v are not exported in xlcall32.lib. This is so that Excel 2007 XLL projects can be created that also work with earlier versions of Excel. The xlcall.cpp module contains code for the Excel12 and Excel12v functions, which call into an Excel entry point if you are running Excel 2007, or return a safe error value if you are running an earlier version of Excel. You should include this module in your project if you want to create an XLL that runs with Excel 2007 and that is able to use the new data types that handle larger grids and longer Unicode strings.

Turning DLLs into XLLs: Add-in Manager Interface Functions

An XLL is a DLL that exports several procedures that are called by Excel or the Excel Add-in Manager. These procedures are described briefly here and discussed in detail in Add-in Manager and XLL Interface Functions. All of these DLL callbacks start with the prefix xlAuto. Only one of these, the command xlAutoOpen, is required. It is called when the add-in is activated, and it is typically used to register XLL functions and commands with Excel and to do other initialization tasks. The function signatures and example implementations of all of the xlAuto functions are provided in later sections.

Even though xlAutoOpen is the only required one of these callbacks, your add-in may also need to export others depending on its behavior.

Excel 2007 introduces a new data type to accommodate larger grids and to support long Unicode strings, XLOPER12, which is described later in this topic. Whereas xlAuto functions take or return the old data type XLOPER, new versions are introduced together with these in Excel 2007 that use XLOPER12s. With the exception of xlAutoFree12, which sometimes must be implemented to avoid XLOPER12 memory leaks, all the version 12 xlAuto functions can safely be omitted, in which case Excel 2007 calls the XLOPER versions.

xlAutoOpen

Excel calls the xlAutoOpen function whenever the XLL is activated. The add-in will be activated at the start of an Excel session if it was active in the last Excel session that ended normally. The add-in is activated if it is loaded during an Excel session. The add-in can be deactivated and reactivated during an Excel session, and the function is called on reactivation.

xlAutoOpen is the recommended place from where to register XLL functions and commands, initialize data structures, customize the user interface, and so on.

If your add-in implements and exports the xlAutoRegister function or the xlAutoRegister12 function, Excel might attempt to activate and register a function or command without first calling the xlAutoOpen function. In this case, you should ensure that your add-in is sufficiently initialized for your function or command to work properly. If it is not, you should either fail the attempt to register the function or command, or carry out the necessary initialization.

xlAutoClose

Excel calls the xlAutoClose function whenever the XLL is deactivated. The add-in will be deactivated when an Excel session ends normally. If the user deactivates the add-in during an Excel session, the function is called on.

xlAutoClose is the recommended place from where to unregister functions and commands, release resources, undo customizations, and so on. There is a known issue with the unregistration of functions and commands which is discussed in Known Issues in Excel XLL Development.

xlAutoAdd

Excel calls the xlAutoAdd function whenever the user activates the XLL during an Excel session by using the Add-In Manager. This function is not called when Excel starts up and loads a pre-installed add-in.

The function can be used to display a custom dialog box that tells the user that the add-in has been activated, to read from or write to the registry, or to check licensing information, for example.

xlAutoRemove

Excel calls the xlAutoRemove function whenever the user deactivates the XLL during an Excel session by using the Add-In Manager. This function is not called when an Excel session closes, normally or abnormally, with the add-in installed.

The function can be used to display a custom dialog box that tells the user that the add-in has been deactivated, or to read from or write to the registry, for example.

xlAddInManagerInfo/xlAddInManagerInfo12

Excel calls the xlAddInManagerInfo function when the Add-in Manager is invoked for the first time in an Excel session. If Excel passes an argument equal to 1, this function should return a string (typically, the name of the add-in); otherwise it should return #VALUE!.

Excel 2007 calls the xlAddInManagerInfo12 function in preference to the xlAddInManagerInfo function if it is exported by the XLL. The xlAddInManagerInfo12 function should work in the same way as the xlAddInManagerInfo function to avoid version-specific differences in the behavior of the XLL. Excel expects the xlAddInManagerInfo12 function to return an Excel 2007 XLOPER12 data type, whereas the xlAddInManagerInfo function should return an XLOPER data type.

xlAutoRegister/xlAutoRegister12

Excel calls the xlAutoRegister function whenever a call has been made to the XLM function REGISTER, or the C API equivalent xlfRegister function, with the return and argument types of the function being registered missing. It allows the XLL to search its internal lists of exported functions and commands to register the function with the argument and return types specified.

Excel 2007 calls the xlAddInRegister12 function in preference to the xlAddInRegister function if it is exported by the XLL.

Note
If xlAddInRegister/xlAddInRegister12 tries to register the function without supplying the argument and return types, a recursive calling loop occurs which eventually overflows the call stack and crashes Excel.

xlAutoFree/xlAutoFree12

Excel calls the xlAutoFree/xlAutoFree12 function just after an XLL worksheet function returns an XLOPER/XLOPER12 data type to it with a flag set that tells it there is memory that the XLL still needs to release. This enables the XLL to return dynamically allocated arrays, strings, and external references to the worksheet without memory leaks. Only Excel 2007 and later versions support the XLOPER12 data type. For more information, see Memory Management in Excel 2007.

Note
When Excel 2007 is configured to use multithreaded worksheet recalculation, the xlAutoFree/xlAutoFree12 function is called on the same thread that was just used to call the function that returned it. The call to xlAutoFree/xlAutoFree12 is always made before any subsequent worksheet cells are evaluated on that thread. This simplifies thread-safe design in your XLL. For more information, see Multithreaded Recalculation in Excel 2007.

When Excel 2007 is configured to use multithreaded worksheet recalculation, the xlAutoFree/xlAutoFree12 function is called on the same thread that was just used to call the function that returned it. The call to xlAutoFree/xlAutoFree12 is always made before any subsequent worksheet cells are evaluated on that thread. This simplifies thread-safe design in your XLL. For more information, see Multithreaded Recalculation in Excel 2007.

Share via