Accessing Excel Functionality Using the C API 265 { RetVal.SetType(xltypeNil); // These depend on the the version and what is provided char *types, *code_name, *arg_names; if(gExcelVersion12plus) { if(ps->name_in_code12 && ps->name_in_code12[0]) { code_name = ps->name_in_code12; types = ps->types12; } else { code_name = ps->name_in_code; types = ps->types; } if(ps->arg_names12 && ps->arg_names12[0]) arg_names = ps->arg_names12; else arg_names = ps->arg_names; } else { code_name = ps->name_in_code; types = ps->types; arg_names = ps->arg_names; } if(!check_register_args(ps->ws_name, types, arg_names)) return false; int arg_limit = (gExcelVersion12plus ? MAX_XL12_UDF_ARGS : MAX_XL11_UDF_ARGS); // Array of pointers to xloper that will be passed to Excel4v() const cpp_xloper *ptr_array[MAX_XL12_UDF_ARGS]; cpp_xloper FnArgs[MAX_XL12_UDF_ARGS]; // Get the full path and name of the DLL. // Passed as the first argument to xlfRegister. if(FnArgs[0].Excel(xlGetName)) { cpp_xloper ErrMsg = "Could not get XLL path,name"; ErrMsg.Alert(3);// Error alert type return false; } FnArgs[1] = code_name; FnArgs[2] = types; FnArgs[3] = ps->ws_name; FnArgs[4] = arg_names; FnArgs[5] = 1; FnArgs[6] = ps->fn_category; FnArgs[7].SetType(xltypeMissing); // Short cut text character FnArgs[8] = ps->help_file; FnArgs[9] = ps->fn_description; char *p_arg; 266 Excel Add-in Development in C/C++ for(int i = 10; i < arg_limit; i++) { p_arg = ps->arg_help[i-10]; if(!(p_arg && *p_arg)) break; // that was the last of the arguments for this fn // Set the corresponding xlfRegister argument FnArgs[i] = p_arg; // convert the string to a cpp_xloper } // Set up the array of pointers for(int num_args = i; i >= 0;) ptr_array[i] = FnArgs + i; if(RetVal.Excel(xlfRegister, num_args, ptr_array) != xlretSuccess) { cpp_xloper ErrMsg("Couldn't register "); ErrMsg += FnArgs[3]; ErrMsg.Alert(3); // Error alert dialog type return false; } return true; } Note that the return value in this case is passed back via the cpp_xloper argument RetVal rather than on the stack as in the example in the previous section. 8.6.13 A class based approach to managing registration data It is also possible to define a class which can be instantiated right next to the function (or command) to be exported, or pair of functions if using a dual-version interface. All the required data can be passed to the class instance through its constructor. The class can maintain a list of instances of itself and expose a static method which then registers all of the functions. This approach has the advantage of keeping the registration data close to the function itself, thereby simplifying changes and making bugs in the data easier to find. Here’s an example of just such a class that uses the same code to do the registration work as the dual-version approach outlined above: class RegData { public: RegData(void) {return;} RegData(char *name_in_code, char *types, char *name_in_code12, char *types12, char *ws_name, char *arg_names, char *arg_names12, char *fn_category, char *help_file, char *fn_description, ); bool RegisterThis(void); static void ClearData(void) { if(InstanceArray) { delete[] InstanceArray; InstanceArray = NULL; count = array_size = 0; } Accessing Excel Functionality Using the C API 267 } static void RegisterAll(void); private: // Class member variables static long count; static long array_size; static RegData **InstanceArray; // Instance member variables char *m_NameInCode; // Arg2: Function name as in code (v11-) char *m_Types; // Arg3: Return type and argument types (v11-) char *m_NameInCode12; // Arg2: Function name as in code (v12+) char *m_Types12; // Arg3: Return type and argument types (v12+) char *m_WsName; // Arg4: Fn name as it appears on worksheet char *m_ArgNames; // Arg5: Argument names (Excel 11-: max 30) char *m_ArgNames12; // Arg5: Argument names (Excel 12+: max 255) char *m_FnCategory; // Arg7: Function category for Function Wizard char *m_HelpFile; // Arg9: Help file (optional) char *m_FnDescription; // Arg10: Function description text (optional) char *m_ArgHelp[MAX_XL12_UDF_ARGS - 11]; // Arg11 arg help text }; long RegData::count = 0; long RegData::array_size = 0; RegData **RegData::InstanceArray = NULL; RegData::RegData(char *name_in_code, char *types, char *name_in_code12, char *types12, char *ws_name, char *arg_names, char *arg_names12, char *fn_category, char *help_file, char *fn_description, ) { m_NameInCode = name_in_code; m_Types = types; m_NameInCode12 = name_in_code12; m_Types12 = types12; m_WsName = ws_name; m_ArgNames = arg_names; m_ArgNames12 = arg_names12; m_FnCategory = fn_category; m_HelpFile = help_file; m_FnDescription = fn_description; va_list arg_ptr; va_start(arg_ptr, fn_description); // Initialize for(int i = 0; i < MAX_XL12_UDF_ARGS - 11; i++) if((m_ArgHelp[i] = va_arg(arg_ptr, char *)) == NULL) break; va_end(arg_ptr); // Reset for(i++; i < MAX_XL12_UDF_ARGS - 11; i++) m_ArgHelp[i] = NULL; if(count == array_size) // then need to allocate more space { RegData **new_array = new RegData *[array_size + 20]; if(array_size) memcpy(new_array, InstanceArray, array_size * sizeof(RegData *)); array_size += 20; 268 Excel Add-in Development in C/C++ delete[] InstanceArray; InstanceArray = new_array; } InstanceArray[count++] = this; } void RegData::RegisterAll(void) { for(long i = 0; i < count; i++) InstanceArray[i]->RegisterThis(); } bool RegData::RegisterThis(void) { dual_ws_func_export_data s; s.name_in_code = m_NameInCode; s.types = m_Types; s.name_in_code12 = m_NameInCode12; s.types12 = m_Types12; s.ws_name = m_WsName; s.arg_names = m_ArgNames; s.arg_names12 = m_ArgNames12; s.fn_category = m_FnCategory; s.help_file = m_HelpFile; s.fn_description = m_FnDescription; for(int i = 0; i < MAX_XL12_UDF_ARGS - 11; i++) s.arg_help[i] = m_ArgHelp[i]; cpp_xloper RetVal; return register_dual_function(&s, RetVal); } All that’s then needed is an instance of the class outside the body of the function. (Note that the variable argument list is terminated by an explicit NULL pointer and any of the pre-argument help strings must be passed as empty strings if missing). For example: RegData RT_is_error_UDF( // Instance name is not important "is_error_UDF",// Function name as in code (v11-) "RP", // Return type and argument types (v11-) "", // Function name as in code (v12+) "", // Return type and argument types (v12+) "IsErrUdf", // Fn name as it appears on worksheet "Input", // Argument names (Excel 11-: max 30) "", // Argument names (Excel 12+: max 255) "Example", // Function category for Function Wizard "", // Help file (optional) "Example UDF function. Returns TRUE if passed an error value or" " string starting with #.", // Function description text (optional) "the value or single cell ref to be tested", // Fn arg help text NULL); // Arg list terminator Accessing Excel Functionality Using the C API 269 xloper * __stdcall is_error_UDF(xloper *p_op) { // code omitted } And then a line in xlAutoOpen to register the functions: // Registration method 3: // Register all instances of RegData (supports dual-version interface) RegData::RegisterAll(); And a line in xlAutoClose to release the class’ instance array: // Explicitly clear the RegData instance pointer table RegData::ClearData(); The example projects on the CD ROM also contain a similar class-based approach for exported commands. 8.6.14 Getting and using the function’s register ID In the above sections, register_function() and register_dual_function() register a function and return an xloper/cpp_xloper. If successful this is of type xltypeNum and contains a unique register ID. This ID is intended to be used in calls to xlfUnregister. However, a bug in Excel prevents this from un-registering functions as intended – see next section. If you did not record the ID that xlfRegister returned, you can get it at any time using the xlfRegisterId function. This takes 3 arguments: 1. DllName: The name of the DLL as returned by the function xlGetName. 2. FunctionName: The name of the function as exported and passed in the 2nd argument to xlfRegister. 3. ArgRtnTypes: The string that encodes the return and argument types, the call- ing permission and volatile status of the function, as passed in the 3rd argument to xlfRegister. The macro sheet functions that take this ID as an argument are: • xlfUnregister: (See next section.) • xlfCall: Calls a DLL function. There is no point in calling this function where the caller is in the same DLL, but it does provide a means for inter-DLL calling. (The macro sheet version of this function, CALL(), used to be available on worksheets. This enabled a spreadsheet with no XLM or VBA macros to access any DLL’s functionality without alerting the user to the potential misuse that this could be put to. This security chasm was closed in version 7.0.) 270 Excel Add-in Development in C/C++ 8.6.15 Un-registering a DLL function Excel keeps an internal list of the functions that have been registered from a given DLL as well as the number of times each function has been registered. (You can interrogate Excel about the loaded DLL functions using the xlfGetWorkspace, argument 44. See section 8.10.11 Information about the workspace: xlfGetWorkspace on page 303 for details.) When registering a function, xlfRegister does two things. 1. Increments the count for the registered function. 2. Associates the function’s worksheet name, given as the 4th argument to xlfRegister, with the DLL resource. To un-register a function you therefore have to undo both of these actions in order to restore Excel to the pre-DLL state. The xlfUnregister function, which takes the register ID returned by the call to xlfRegister, decrements the usage count of the function. To disassociate the function’s worksheet name, you need to call the xlfSetName function, which usually associates a name with a resource, but without specifying a resource. This clears the existing associated resource – the DLL function. Sadly, a bug in Excel prevents even this two-pronged approach from successfully remov- ing the reference to the function. Another approach is as follows 3 : 1. Re-register the function as a hidden function by setting the 5th argument to xlfRegister, macro type,to0. 2. Use the returned register ID to unregister the function with xlfUnregister. Even this approach does not return Excel to the pre-registration state where the function in a worksheet cell returns #NAME? and where the function is not listed in the function wizard lists. Microsoft recognise the existence of this bug but, sadly, they have not been able to remove it even in Excel 2007. In practice, not un-registering functions has no grave consequences. Warning: The C API function xlfUnregister supports another syntax which takes a DLL name, as returned by the function xlfGetName. Called in this way it un-registers all that DLL’s resources. This syntax also causes Excel to call xlAutoClose().You will therefore crash Excel with a stack overflow if you call xlfUnregister with this syntax from within xlAutoClose(). You should avoid using this syntax anywhere within the DLL self-referentially. The following code sample shows a simple implementation of xlAutoClose(), called whenever the DLL is unloaded or the add-in is deselected in the Add-in Man- ager, and the code for the function it calls, unregister_function(). The example uses the same structures and constant definitions as section 8.6.14 above. As already stated, even this will not work as intended, due to an Excel bug. Leaving the body of xlAutoClose() empty in this example will not have grave consequences, although there may be other cleaning up tasks you should be doing here. 3 See Professional Excel Development, (Bullen, Bovey, Green), Addison Wesley, 2005. The method is credited to Laurent Longre. Accessing Excel Functionality Using the C API 271 int __stdcall xlAutoClose(void) { for(int i = 0 ; i < NUM_FUNCS; i++) unregister_function(i); return 1; } bool unregister_function(int fn_index) { // Decrement the usage count for the function using a module-scope // xloper array containing the function's ID, as returned by // xlfRegister or xlfRegisterId Excel4(xlfUnregister, 0, 1, fn_ID + fn_index); // Get the name that Excel associates with the function cpp_xloper xStr(WsFuncExports[fn_index].ws_name); // Undo the association of the name with the resource return Excel4(xlfSetName, 0 , 1, &xStr) == xlretSuccess; } 8.7 REGISTERING AND UN-REGISTERING DLL (XLL) COMMANDS As with functions, XLL commands need to be registered in order to be directly accessible within Excel (without going via VB). As with worksheet functions, the xlfRegister function is used. (See section 8.6.1 for how to call this function.) To register a command, the first 6 arguments to xlfRegister must all be passed. Table 8.11 xlfRegister arguments for registering commands Argument number Required or optional Description 1 Required The full drive, path and filename of the DLL containing the function. 2 Required The command name as it is exported. Note: This is case-sensitive. 3 Required The return type which should always be "J" 4 Required The command name as Excel will know how to reference it. Note: This is case-sensitive. 5 Required The argument names, i.e., an xltypeNil or xltypeMissing xloper/xloper12, since commands take no arguments. 6 Required The function type: 2 = Command. An exported command will always be of the following form: 272 Excel Add-in Development in C/C++ int __stdcall xll_command(void) { bool all_ok = is_everything_ok(); if(!all_ok) return 0; return 1; } In practice, Excel does not care about the return value, although the above is a good standard to conform to. As there are always 6 arguments to be passed to xlfRegister,itisbestcalledusing Excel4()/Excel12(), in contrast to functions which are most easily registered using Excel4v()/Excel12v(). The following code demonstrates how to register Excel commands, requiring only the name of the command as exported in the DLL and the name as Excel will refer to it. The code uses the cpp_xloper class, described in section 6.4 on page 146, to simplify the handling of Excel4() arguments and return values. xloper register_command(char *code_name, char *Excel_name) { cpp_xloper RetVal, DllName; // // Get the full path and name of the DLL. // Passed as the first argument to xlfRegister, so need // to set first pointer in array to point to this. // if(DllName.Excel(xlGetName) != xlretSuccess) return *p_xlNil; // // Set up the rest of the arguments. // cpp_xloper CodeName(code_name); cpp_xloper ExcelName(Excel_name); cpp_xloper RtnType("J"); cpp_xloper MacroType(2); // Command cpp_xloper NilArgs; // defaults to xltypeNil int xl_ret_val = RetVal.Excel(xlfRegister, 6, &DllName, &CodeName, &RtnType, &ExcelName, & NilArgs, &MacroType); if(xl_ret_val != xlretSuccess) display_register_error(code_name, xl_ret_val, (int)RetVal); return (xloper)RetVal; } Commands to be exported can simply be described by the two strings that need to be passed to the above function. These strings can be held in a static array that is looped through in the xlAutoOpen function. The following code shows the declaration and initialisation of an array for the example command from section 8.1.2, and a very simple implementation of xlAutoOpen which cycles through the array, registering each com- mand. #define NUM_COMMANDS 1 char *CommandExports[NUM_COMMANDS][2] = Accessing Excel Functionality Using the C API 273 { // Name in code, Name that Excel uses {"define_new_name", "DefineNewName"}, }; xloper cmd_ID[NUM_COMMANDS]; int __stdcall xlAutoOpen(void) { for(int i = 0 ; i < NUM_COMMANDS; i++) cmd_ID[i] = register_command(CommandExports[i][0], CommandExports[i][1]); return 1; } A bug prevents the function and command IDs from being used for their intended purpose of unregistration. Therefore the above code can be replaced with: int __stdcall xlAutoOpen(void) { for(int i = 0 ; i < NUM_COMMANDS; i++) register_command(CommandExports[i][0], CommandExports[i][1]); return 1; } 8.7.1 Accessing XLL commands There are a number of ways to access commands that have been exported and registered as described above. 1. Via custom menus. (See section 8.12 Working with Excel menus on page 326.) 2. Via custom toolbars. (See section 8.13 Working with toolbars on page 344.) 3. Via a Custom Button on a toolbar. (See below.) 4. Directly via the Macro dialog. (See below.) 5. Via a VBA module. (See below.) 6. Via one of the C API event traps. (See section 8.15 Trapping events with the C API on page 356.) In addition, there are a number of C API functions that take a command reference (the name of the command as registered with Excel), for example xlfCancelKey. Pre-Excel 2007, to assign a command (or macro, as Excel often refers to commands) to a custom button, you need to drag a new custom button onto the desired toolbar from the Tools/Customize /Commands dialog under the Macro category. Still with the customi- sation dialog showing, right-clicking on the new button shows the properties menu which enables you to specify the appearance of the button and assign the macro (command) to it. To access the command directly from the Macro dialog, you need simply to type the command’s name as registered. The command will not be listed in the list box as Excel treats XLL commands as if they had been defined on a hidden macro sheet, and therefore are themselves hidden. One limitation of current versions of Excel is the inability to assign XLL commands directly to control objects on a worksheet. You can, however, access an XLL command in 274 Excel Add-in Development in C/C++ any VBA module, subject to scope, using the Application.Run("CmdName") VBA statement. If you wish to associate an XLL command with worksheet control, you simply place this statement in the control’s VBA code. 8.7.2 Breaking execution of an XLL command The C API provides two functions xlAbort and xlfCancelKey. The first checks for user breaks (the Esc key being pressed in Windows) and is covered in section 8.8.7 Yielding processor time and checking for user breaks: xlAbort on page 282. xlfCancelKey disables/enables interruption of the currently executing task. If enabled, the default state, it also permits the specification of another command to be run on interruption to do any cleaning up before control is returned to Excel. The function xlfCancelKey takes 2 arguments: (1) an optional Boolean specifying whether interruption is permitted (true) or not (false), and (2) a command name registered with Excel as a string. If the function is called with the first argument set to true or omitted, then the command will be terminated if the user presses the Esc key. This is the default state whenever Excel calls a command, so it is not necessary to call this function except explicitly to disable or re-enable user breaks. If breaks have been disabled, it is not strictly necessary to re-enable them before terminating a command, as Excel automatically restores the default, but it is good practice. 8.8 FUNCTIONS DEFINED FOR THE C API ONLY 8.8.1 Freeing Excel-allocated memory within the DLL: xlFree Overview: Frees memory allocated by Excel during a call to Excel4()/Excel12() or Excel4v()/Excel12v() for the return xloper/xloper12 value. This is only necessary where the returned type involves the allocation of memory by Excel. There are only 3 types that can have memory associated with them in this way, xltypeStr, xltypeRef and xltypeMulti, so it is only necessary to call xlFree if the return type is or could be one of these. It is always safe to call this function even if the type is not one of these. It is not safe to call this function on an xloper/xloper12 that was passed into the DLL as a function argument from Excel, or one that has been initialised by the DLL with either static or dynamic memory. xlFree sets the pointer contained in any xloper/xloper12 to NULL after freeing memory and is the only Excel callback function to modify its arguments. (See Chapter 7 Memory Management on page 203 for an explanation of the basic concepts and more examples of the use of xlFree.) Enumeration value: 16384 (x4000) Callable from: Commands, worksheet and macro sheet functions. [...]... the Windows API is a 4-byte long The returned value is therefore the low part of the full handle The following code shows how to obtain the full handle using the Windows API EnumWindows() function in Excel 2003– In Excel 2007 and later versions, when called using Excel1 2(), the returned xltypeInt xloper12 contains a 4-byte signed integer which is the full handle 284 Excel Add -in Development in C/C++... needs to distinguish between them This is far less necessary than it used to be under 16- bit Windows, where different instances shared the same DLL memory The function takes no arguments In Excel 2003 – it returns an xltypeInt xloper containing the low part of the instance handle In Excel 2007+ when called using Excel1 2() it returns an xltypeInt xloper12 containing the full handle 8.8.9 Getting the handle... it before exiting BreakState .Excel( xlAbort); if(BreakState.IsTrue()) // then reset it { BreakState .Excel( xlAbort, 1, &False); return 0; } } return 1; } 8.8.8 Getting Excel s instance handle: xlGetInst This function, enumeration 0x4007, obtains an instance handle for the running instance of Excel that made this call into the DLL This is useful if there are multiple instances of Excel running and your... returning the converted value returned via the passed -in pointer Note that the caller of this function must take responsibility for ensuring that any memory allocated by Excel4 () for the xloper ret_val is eventually freed by Excel 278 Excel Add -in Development in C/C++ bool coerce_xloper(const xloper *p_op, xloper &ret_val, int target_type) { // Target will contain the information that tells Excel. .. sheet contains an array formula Excel seems to be checking the wrong sheet before assigning the values In failing, Excel displays the alert “You cannot change part of an array” This bug is fixed in Excel 2007 (version 12) 8.8.5 Getting the internal ID of a named sheet: xlSheetId Overview: Every worksheet in every open workbook is assigned an internal DWORD ID by Excel This ID can be obtained from the... condition } Accessing Excel Functionality Using the C API 281 8.8 .6 Getting a sheet name from its internal ID: xlSheetNm Overview: Every worksheet in every open workbook is assigned an internal DWORD ID by Excel This ID can be obtained from the text name of the sheet with the function xlSheetId (see above) Conversely, the text name, in the form [Book1.xls]Sheet1, can be obtained from the ID using this function... are 163 96/ x400c and 163 97/x400d respectively.) Apart from this method of storing data being more memory-efficient, accessing a table of data in the DLL is quicker than accessing the same data from the workbook, even if the table is small and despite Excel providing some fairly efficient ways to do this This may be a consideration in optimising the performance of certain workbook recalculations 2 86 Excel. .. workbook • Get a list of all the names in a given worksheet 4 Straightforward means using standard Excel or C API functions Reading the workbook file as a binary file and interpreting the contents directly is one very non-straightforward way Accessing Excel Functionality Using the C API 287 The first of these last two operations involves changing the active worksheet, something that can only be done from a... return Big .Excel( xlGetBinaryName, 1, &Name) && Big.IsBigData(); } 8.9.5 Example worksheet functions The following exportable worksheet functions demonstrate the creation, deletion and retrieval of a text string as a binary name in the active sheet These functions are Accessing Excel Functionality Using the C API 289 included in the example project in the source file BigData.cpp and are called in the example... } 8.8.10 Getting the path and file name of the DLL: xlGetName Overview: It is sometimes necessary to get the path and file name of the DLL that is currently being invoked The one place this information is required is in the registration of XLL functions using xlfRegister, where the first argument is exactly this information Accessing Excel Functionality Using the C API Enumeration value: 163 93 (x4009) . following code shows how to obtain the full handle using the Windows API EnumWindows() func- tion in Excel 2003–. In Excel 2007 and later versions, when called using Excel1 2(), the returned xltypeInt. the instance handle. In Excel 2007+ when called using Excel1 2() it returns an xltypeInt xloper12 containing the full handle. 8.8.9 Getting the handle of the top-level Excel window: xlGetHwnd This. always 6 arguments to be passed to xlfRegister,itisbestcalledusing Excel4 () /Excel1 2(), in contrast to functions which are most easily registered using Excel4 v() /Excel1 2v(). The following code