從 DLL 或 XLL 呼叫 Excel

適用於：Excel 2013 |Office 2013 |Visual Studio

Microsoft Excel 可讓您的 DLL 存取內建 Excel 命令、工作表函數和宏工作表函式。 這些可從 Visual Basic for Applications (VBA) 呼叫的 DLL 命令和函式，以及 Excel 直接呼叫的已註冊 XLL 命令和函式取得。

Excel4、Excel4v、Excel12 和 Excel12v 函式

Excel 可讓您的 DLL 透過回呼函式 Excel4、Excel4v、Excel12 和 Excel12v 來存取命令和函式。

Excel4 和 Excel4v 函式是在 Excel 第 4 版中引進的。 它們會使用 XLOPER 數據結構。 Excel 2007 導入了兩個新的回呼函式 Excel12 和 Excel12v，可使用 XLOPER12 數據結構。 Excel4 和 Excel4v 函式是由連結庫 Xlcall32.lib 匯出，其必須包含在您的 DLL 或 XLL 專案中。 Excel12 和 Excel12v 包含在 SDK C++原始程式檔Xlcall.cpp中，如果您想要使用 XLOPER12 結構來存取 Excel 功能，則必須包含在您的專案中。

下列程式代碼顯示這四個函式的函式原型。 前三個自變數相同，不同之處在於第二個自變數是第一個配對中 XLOPER 的指標，以及第二個配對中 XLOPER12 的指標。 呼叫慣例 會在Excel4 和 Excel12 中_cdecl，以允許變數自變數清單。 省略號代表Excel4的 XLOPER 值指標，以及Excel12的XLOPER12值。 指標數目等於 count 參數的值。

Excel 的所有版本

int _cdecl Excel4(int xlfn, LPXLOPER operRes, int count,... );

int pascal Excel4v(int xlfn, LPXLOPER operRes, int count, LPXLOPER opers[]);

從 Excel 2007 開始

int _cdecl Excel12(int xlfn, LPXLOPER12 operRes, int count,... );

int pascal Excel12v(int xlfn, LPXLOPER12 operRes, int count, LPXLOPER12 opers[]);

若要讓 DLL 能夠呼叫 Excel4、 Excel4v、 Excel12 或 Excel12v，Excel 必須將控制權傳遞給 DLL。 這表示這些 C API 回呼只能在下列案例中呼叫：

• 從 Excel 直接或透過 VBA 呼叫的 XLL 命令內。

• 從 Excel 直接或透過 VBA 呼叫的 XLL 工作表或宏工作表函式內。

在下列案例中，您無法呼叫 Excel C API：

• 例如，從操作系統事件 (，從 DllMain 函式) 。

• 從 DLL 建立的背景線程。

傳回值

這四個函式都會傳回整數值，告知呼叫端是否已成功呼叫函式或命令。 傳回的值可以是下列其中一項：

如果函式傳回數據表中其中一個失敗值， (亦即，它不會傳回 xlretSuccess) ，XLOPER 或 XLOPER12 傳回值也會設定 為 #VALUE！。 在某些情況下，檢查此情況可能足以測試是否成功，但您應該注意，呼叫可以同時傳回 xlretSuccess 和 #VALUE！。

如果對 C API 的呼叫導致 xlretUncalced 或 xlretAbort，則 DLL 或 XLL 程式代碼應該先將控制權傳回 Excel，再進行任何其他 C API 呼叫， (呼叫 xlfree 函式，以釋放 XLOPER 中 Excel 配置的記憶體資源，並 XLOPER12 值) 。

命令或函式列舉自變數：xlfn

xlfn 自變數是回調函式的第一個自變數，並且是 32 位帶正負號的整數。 其值應該是 SDK 頭檔 Xlcall.h 中定義的其中一個函式或命令列舉，如下列範例所示。

// Excel function numbers. 
#define xlfCount 0
#define xlfIsna 2
#define xlfIserror 3
#define xlfSum 4
#define xlfAverage 5
#define xlfMin 6
#define xlfMax 7
#define xlfRow 8
#define xlfColumn 9
#define xlfNa 10
...
// Excel command numbers. 
#define xlcBeep (0 | xlCommand)
#define xlcOpen (1 | xlCommand)
#define xlcOpenLinks (2 | xlCommand)
#define xlcCloseAll (3 | xlCommand)
#define xlcSave (4 | xlCommand)
#define xlcSaveAs (5 | xlCommand)
#define xlcFileDelete (6 | xlCommand)
#define xlcPageSetup (7 | xlCommand)
#define xlcPrint (8 | xlCommand)
#define xlcPrinterSetup (9 | xlCommand)
...

所有工作表和宏工作表函式的範圍從 0 (xlfCount) 到0x0fff十六進位，雖然 Excel 2013 中指派的最高指派數位是 547 十進位，0x0223十六進位 (xlfFloor_precise) 。

雖然 Excel 2013 中指派的最高指派數位0x8328十六進位 ( (xlcHideallInkannots) 0x8fff，但所有命令函式都位於 xlcBeep) 0x8000 十六進位0x8328範圍中。 這些會在頭檔中定義為 (n | xlCommand) ，其中 n 是大於或等於0的小數，而 xlCommand 則定義為0x8000十六進位。

叫用使用對話框的Excel命令

某些命令程式代碼會對應至 Excel 中使用對話框的動作。 例如， xlcFileDelete 會採用單一自變數：檔名或遮罩。 這可以使用對話框叫用，讓用戶有機會取消或修改刪除作業。 它也可以在沒有對話框的情況下呼叫，在此情況下，檔案或檔案會在沒有任何進一步互動的情況下刪除，前提是它們存在且呼叫端具有許可權。 若要在其對話框表單中呼叫這類命令，命令列舉必須使用位 OR 運算搭配 xlPrompt) 0x1000 (。

下列程式代碼範例會刪除目前目錄中符合 mask my_data*.bak的檔案，只有在自變數為 true 時才會顯示對話方塊。

bool delete_my_backup_files(bool show_dialog)
{
    XLOPER12 xResult, xFilter;
    xFilter.xltype = xltypeStr;
    xFilter.val.str = L"\014my_data*.bak"; // String length: 14 octal
    int cmd;
    if(show_dialog)
        cmd = xlcFileDelete | xlPrompt;
    else
        cmd = xlcFileDelete;
// xResult should be Boolean TRUE if successful, in which
// case return true; otherwise, false.
    return (Excel12(cmd, &xResult, 1, &xFilter) == xlretSuccess
        && xResult.xltype == xltypeBool
        && xResult.val.xbool == 1);
}

在國際版本中呼叫函式和命令

您可以設定 Excel 以各種語言顯示函式和 XLM 命令名稱。 某些 C API 命令和函式會在解譯為函式或命令名稱的字串上運作。 例如， xlcFormula 會採用要放在指定儲存格中的字串自變數。 若要讓載入宏使用所有語言設定，您可以提供英文字串名稱，並在函式或命令列舉中設定 xlIntl) 位0x2000 (。

下列程式代碼範例會將 的 =SUM(X1:X100) 對等專案放在使用中工作表的儲存格 A2 中。 請注意，它會使用 Framework 函式 TempActiveRef 來建立暫時的外部參考 XLOPER。 公式會以正確的地區設定決定語言顯示在 A2 中 (例如， =SOMME(X1:X100) 如果語言是法文) 。

int WINAPI InternationlExample(void)
{
    XLOPER12 xSum, xResult;
    xSum.xltype = xltypeStr;
    xSum.val.str = L"\015=SUM(X1:X100)";
    Excel12(xlcFormula | xlIntl, &xResult, 2,
        &xSum, TempActiveRef(2,2,1,1));
    return 1;
}

DLL-Only 函式和命令

Excel 支持少數只能從 DLL 或 XLL 存取的函式。 這些會在頭檔中定義為 (n | xlSpecial) ，其中 n 是大於或等於0的小數，並 xlSpecial 定義為0x4000十六進位。 下表列出這些函式，並記載於 API 函數參考中。

傳回值 XLOPER/XLOPER12： operRes

operRes 自變數是回呼的第二個自變數，也是 XLOPER (Excel4 和 Excel4v) 或XLOPER12 (Excel12 和 Excel12v) 的指標。 成功呼叫之後，它會包含函式或命令的傳回值。 如果不需要傳回值，則 operRes 可以設定為零 (NULL 指標) 。 系統會覆寫 先前的 operRes 內容，因此必須先釋放先前所指向的任何記憶體，才能呼叫 ，以避免記憶體流失。

例如，如果無法呼叫函式或命令 (，如果自變數) 不正確，則 operRes 會設定為錯誤 #VALUE！。 如果成功，命令一律會傳回 布爾值 TRUE ;如果失敗或使用者取消，則傳回 FALSE 。

後續自變數的數目：計數

count 自 變數 是回呼的第三個自變數，是 32 位帶正負號的整數。 它應該設定為後續自變數的數目，從 1 算起。 如果函式或命令不接受任何自變數，則應該設定為零。 在 Microsoft Office Excel 2003 中，任何函式可接受的自變數數目上限為 30，雖然大部分的自變數都少於此數目。 從 Excel 2007 開始，任何函式可以接受的自變數數目上限已增加到 255。

使用 Excel4 和 Excel12 時， count 是要傳遞之 XLOPER 或 XLOPER12 值的指標數目。 您應該非常小心，不要傳遞比計數設定的值少的自 變數 。 這會導致 Excel 直接讀入堆疊，並嘗試處理無效的 XLOPER 或 XLOPER12 值，這可能會導致應用程式當機。

使用 Excel4v 和 Excel12v 時， count 是 XLOPER 指標數位的大小，或 是XLOPER12 傳遞為下一個和最後一個自變數的值。 同樣地，您應該非常小心，不要傳遞小於 大小計數 元素的陣列，因為這會導致數位的界限溢出。

將自變數傳遞至 C API 函式

Excel4 和 Excel12 都會採用可變長度自變數清單，在計數之後，分別解譯為 XLOPER 和XLOPER12值的指標。 Excel4v 和 Excel12v 會在 count 之後採用單一自變數，這是 Excel4v 案例中 XLOPER 值之指標數位的指標，並在 Excel12v 的情況下XLOPER12值。

數位表單 Excel4v 和 Excel12v可讓您在自變數數目為變數時，以全新方式撰寫 C API 呼叫的程式代碼。 下列範例顯示的函式會採用可變大小的數字數位數組，並透過 C API 使用 Excel 工作表函數來計算總和、平均、最小和最大值。

void Excel12v_example(double *dbl_array, int size, double &sum, double &average, double &min, double &max)
{
// 30 is the limit in Excel 2003. 255 is the limit in Excel 2007.
// Use the lower limit to be safe, although it is better to make
// the function version-aware and use the correct limit.
    if(size < 1 || size > 30)
        return;
// Create an array of XLOPER12 values.
    XLOPER12 *xOpArray = (XLOPER12 *)malloc(size * sizeof(XLOPER12));
// Create an array of pointers to XLOPER12 values.
    LPXLOPER12 *xPtrArray =
        (LPXLOPER12 *)malloc(size * sizeof(LPXLOPER12));
// Initialize and populate the array of XLOPER12 values
// and set up the pointers in the pointer array.
    for(int i = 0; i < size; i++)
    {
        xOpArray[i].xltype = xltypeNum;
        xOpArray[i].val.num = dbl_array[i];
        xPtrArray[i] = xOpArray + i;
    }
    XLOPER12 xResult;
    int retval;
    int fn[4] = {xlfSum, xlfAverage, xlfMin, xlfMax};
    double *result_ptr[4] = {&sum, &average, &min, &max};
    for(i = 0; i < 4; i++)
    {
        retval = Excel12v(fn[i], &xResult, size, xPtrArray);
        if(retval == xlretSuccess && xResult.xltype == xltypeNum)
            *result_ptr[i] = xResult.val.num;
    }
    free(xPtrArray);
    free(xOpArray);
}

在上述程式代碼中，將 XLOPER12 值的參考取代為 XLOPER，並將 Excel12v 取代為 Excel4v，將會產生可搭配所有 Excel 版本使用的函式。 Excel 函 式 SUM、 AVERAGE、 MIN 和 MAX 的這項作業非常簡單，因此以 C 撰寫它們的程式代碼會更有效率，並避免準備自變數和呼叫 Excel 的額外負荷。 不過，Excel 包含的許多函式都比較複雜，因此在某些情況下，這種方法很有用。

xlfRegister 主題提供另一個使用 Excel4v 和 Excel12v 的範例。 註冊 XLL 工作表函式時，您可以為 [ 貼上 函式] 對話框中使用的每個自變數提供描述性字串。 因此，提供給 xlfRegister 的總自變數數目取決於 XLL 函式所採用的自變數數目，而且會因一個函式而異。

當您一律使用相同數目的自變數呼叫 C API 函式或命令時，您想要避免為這些自變數建立指標陣列的額外步驟。 在這些情況下，使用 Excel4 和 Excel12 會更簡單且更簡潔。 例如，註冊 XLL 函式和命令時，您必須提供 DLL 或 XLL 的完整路徑和檔名。 您可以在呼叫 xlfGetName 時取得檔名，然後使用 xlFree 的呼叫來釋放它，如下列 Excel4 和 Excel12 範例所示。

XLOPER xDllName;
if(Excel4(xlfGetName, &xDllName, 0) == xlretSuccess)
{
    // Use the name, and 
    // then free the memory that Excel allocated for the string.
    Excel4(xlFree, 0, 1, &xDllName);
}
XLOPER12 xDllName;
if(Excel12(xlfGetName, &xDllName, 0) == xlretSuccess)
{
    // Use the name, and
    // then free the memory that Excel allocated for the string.
    Excel12(xlFree, 0, 1, &xDllName);
}

在實務 上，Excel12v_example函式可藉由建立單一 xltypeMultiXLOPER12 自變數，以及使用 Excel12 呼叫 C API，以更有效率地撰寫程式代碼，如下列範例所示。

void Excel12_example(double *dbl_array, int size, double &sum, double &average, double &min, double &max)
{
// In this implementation, the upper limit is the largest
// single column array (equals 2^20, or 1048576, rows in Excel 2007).
    if(size < 1 || size > 1048576)
        return;
// Create an array of XLOPER12 values.
    XLOPER12 *xOpArray = (XLOPER12 *)malloc(size * sizeof(XLOPER12));
// Create and initialize an xltypeMulti array
// that represents a one-column array.
    XLOPER12 xOpMulti;
    xOpMulti.xltype = xltypeMulti;
    xOpMulti.val.array.lparray = xOpArray;
    xOpMulti.val.array.columns = 1;
    xOpMulti.val.array.rows = size;
// Initialize and populate the array of XLOPER12 values.
    for(int i = 0; i < size; i++)
    {
        xOpArray[i].xltype = xltypeNum;
        xOpArray[i].val.num = dbl_array[i];
    }
    XLOPER12 xResult;
    int fn[4] = {xlfSum, xlfAverage, xlfMin, xlfMax};
    double *result_ptr[4] = {&sum, &average, &min, &max};
    for(i = 0; i < 4; i++)
    {
        Excel12(fn[i], &xResult, 1, &xOpMulti);
        if(xResult.xltype == xltypeNum)
            *result_ptr[i] = xResult.val.num;
    }
    free(xOpArray);
}

XLCallVer

除了回呼 Excel4、 Excel4v、 Excel12 和 Excel12v 之外，Excel 還會導出 XLCallVer 函式，此函式會傳回目前執行的 C API 版本。

函式原型如下所示：

int pascal XLCallVer(void);

您可以從任何 XLL 命令或函式呼叫這個安全線程的函式。

在 Excel 97 到 Excel 2003 中， XLCallVer 會傳回 1280 = 0x0500十六進制 = 5 x 256，這表示 Excel 第 5 版。 從 Excel 2007 開始，它會傳回 3072 = 0x0c00 十六進位 = 12 x 256，這同樣表示第 12 版。

雖然您可以使用此值來判斷新的 C API 是否可在運行時間使用，但您可能想要使用 Excel4(xlfGetWorkspace, &version, 1, &arg)來偵測執行中的 Excel 版本，其中 arg 是設為 2 的數值 XLOPER 。 函式會傳回字串 XLOPER 版本，然後可以強制轉為整數。 依賴 Excel 版本而非 C API 版本的原因是，載入宏可能也需要偵測 Excel 2000、Excel 2002 和 Excel 2003 之間有差異。 例如，已對某些統計數據函式的精確度進行變更。

另請參閱

• 建立 XLL
• 在 Excel 中存取 XLL 程式代碼
• Excel XLL SDK API 函數參考
• C API 回呼函式 Excel4、Excel12
• 開發 Excel XLL