xlfRegister (形式 1)

[アーティクル]
04/04/2023

適用対象: Excel 2013 | Office 2013 | Visual Studio

Microsoft Excel から直接呼び出すように、 DLL コマンドや XLL コマンドを使って呼び出すことができます。これは、Excel XLM マクロシートからの REGISTER の呼び出しと同等です。

xlfRegister は、2 つの形式で呼び出すことができます。

xlfRegister (形式 1): コマンドまたは関数を個々に登録します。
xlfRegister (形式 2): XLL を読み込んでアクティブ化します。

この関数を「形式 1」で呼び出すと、Excel が DLL の関数またはコマンドを使用できるようになります。使用カウントを 1 に設定すると、登録 ID が返されます。この登録 ID は、後から関数を呼び出すときに使用できます (xlUDF 関数または xlfCall 関数を使用)。登録 ID は、xlfUnregister (形式 1) を使用している関数の登録解除にも使用されます。関数が登録されていると、xlfRegister を呼び出すたびに使用カウントが増分されます。

この形式の関数では、関数テキスト引数 pxFunctionText である非表示名も定義され、関数またはコマンドの登録 ID に評価されます。関数を登録解除するときには、この名前を xlfSetName を使用して削除します。詳しくは、「Excel XLL 開発での既知の問題」をご覧ください。

Excel12(xlfRegister, LPXLOPER12 pxRes, int iCount,
    LPXLOPER12 pxModuleText,   LPXLOPER12 pxProcedure,
    LPXLOPER12 pxTypeText,     LPXLOPER12 pxFunctionText,
    LPXLOPER12 pxArgumentText, LPXLOPER12 pxMacroType,
    LPXLOPER12 pxCategory,     LPXLOPER12 pxShortcutText,
    LPXLOPER12 pxHelpTopic,    LPXLOPER12 pxFunctionHelp,
    LPXLOPER12 pxArgumentHelp1, LPXLOPER12 pxArgumentHelp2,
        ...);

パラメーター

pxModuleText (xltypeStr)

関数が含まれている DLL の名前。この名前は、登録されている関数も現在実行中の DLL 内にある場合、XLL 専用の関数 xlGetName を呼び出すことで取得できます。

pxProcedure (xltypeStr または xltypeNum)

文字列の場合は、呼び出す関数の名前です (DLL コード内で示された名前)。数字の場合は、呼び出す関数のエクスポートの順序番号です。明確にするために、常に文字列形式を使用します。

pxTypeText (xltypeStr)

関数への引数の型と関数の戻り値の型を指定する、省略可能な文字列。詳しくは、「解説」セクションを参照してください。この引数は、xlAutoRegister function または xlAutoRegister12 を含むスタンドアロン DLL (XLL) では省略できます。

注:

xlAutoRegister12 は Excel 2007 でのみサポートされています。

この引数なしで xlfRegister が呼び出されると、Excel は関数を適切に登録するために、この情報を提供する xlAutoRegister または xlAutoRegister12 を呼び出します (指定した DLL に、どちらかが存在する場合)。

pxFunctionText (xltypeStr)

関数ウィザードに表示される関数名。この引数は省略可能です。省略した場合、関数は関数ウィザードでは使用できません。また、XLM マクロシートの関数登録 ID を使用して CALL 関数を使用してのみ呼び出すことができます。したがって、通常のワークシートでは、この引数を必要に応じて処理する必要があります。

pxArgumentText (xltypeStr)

関数への引数について説明する、省略可能な文字列。この文字列は関数ウィザードでユーザーに表示されます。省略すると、Excel は pxTypeText から基本的な説明を作成します。

pxMacroType (xltypeNum または xltypeInt)

XLL のエントリポイントの種類を示す、省略可能な引数。既定値 (省略した場合) は 1 です。

pxMacroType value	0	1	2
ワークシートから呼び出し可能	はい	はい	いいえ
マクロシートから呼び出し可能	はい	はい	はい
定義済みの名前の定義から呼び出し可能	はい	はい	はい
条件付き書式の式から呼び出し可能	はい	はい	いいえ
ワークシート関数の関数ウィザードに表示される	いいえ	はい	いいえ
マクロシート関数の関数ウィザードに表示される	いいえ	はい	はい

実際には、ワークシート関数には 1、ワークシートから呼び出すマクロシートと同等の関数 (タイプ # として登録されたもの) には 1、コマンドには 2 を使用する必要があります。

注:

XLL コマンドは隠されているため、実行中のマクロのダイアログボックスには表示されません。ただし、有効なコマンド名が必要になる場所では、その名前を入力できます。

pxCategory (xltypeStr または xltypeNum)

新しい関数またはコマンドが属するカテゴリを指定できる省略可能な引数。関数ウィザードは、関数を型 (カテゴリ) で除算します。カテゴリ名または連番を指定できます。ここで、数値は関数ウィザードに表示されるカテゴリの位置です。詳細については、「カテゴリ名」セクションを参照してください。省略すると、ユーザー定義カテゴリが想定されます。

pxShortcutText (xltypeStr)

このコマンドに割り当てられた制御キーを指定する、大文字と小文字を区別する 1 文字の文字列。たとえば、"A" は、このコマンドを CONTROL + SHIFT + A に割り当てます。この引数は省略可能であり、コマンドにのみ使用されます。

pxHelpTopic (xltypeStr)

ヘルプファイル (.chm または .hlp) への省略可能な参照。このファイルは、カスタム関数が表示されているときに、ユーザーが [ヘルプ] ボタンをクリックすると表示されます。フォーム filepath!HelpContextID または https://address/path_to_file_in_site!0を指定できます。 "!" の前と後のどちらの部分も必須です。 HelpContextID には単一引用符を含めないでください。Excel によって 10 進形式で 4 バイトの符号なし整数に変換されます。 URL 形式を使用すると、Excel は参照されるヘルプファイルのみを開きます。

pxFunctionHelp (xltypeStr)

省略可能な文字列。カスタム関数が選択されたときに関数ウィザードに表示される説明です。

pxArgumentHelp1 (xltypeStr)

省略可能。関数ウィザードで関数が選択されたときに、その関数のカスタム引数を説明する最初の文字列。 Excel 2003 以前では、xlfRegister は最大 30 個の引数を受け取ることができるため、関数の最初の 20 個のみの引数に関するヘルプを提供できます。 Excel 2007 以降では、xlfRegister は最大 255 個の引数を受け取ることができるため、最大 245 個の関数のパラメーターに関するヘルプを提供できます。

プロパティの値/戻り値

登録が成功した場合、この関数は関数のレジスタ ID (xltypeNum) を返します。これは、DLL の xlUDF と xlfUnregister の呼び出しで使用することも、XLM マクロシートの CALL と UNREGISTER を使用して使用することもできます。それ以外の場合は、#VALUE を返します。エラーを返します。

備考

データ型

pxTypeText 引数は、戻り値のデータ型と、DLL 関数またはコードリソースに対するすべての引数のデータ型を指定します。 pxTypeText の最初の文字は、戻り値のデータ型を指定します。残りの文字で、すべての引数についてのデータ型を示します。たとえば、浮動小数点数を返し、引数として整数と浮動小数点数を受け取る DLL 関数では、 pxTypeText 引数に "BIB" が必要になります。

XLL とのデータ交換のために Excel で使用されるデータ型と構造体については、次の 2 つの表にまとめています。

最初の表は、Excel のすべてのバージョンでサポートされる型を示しています。

データ型	値渡し	参照渡し (ポインター)	コメント
Boolean	A	L	short [int] (0 = false または 1 = true)
double	B	E
char *		C、F	Null で終了する ASCII バイト文字列
unsigned char *		D、G	カウント付き ASCII バイト文字列
unsigned short [int]	H		16 ビットの Word
[signed] short [int]	I	M	16 ビットの符号付き整数
[signed long] int	J	N	32 ビットの符号付き整数
FP		K	浮動小数点配列構造
配列		O	次の 3 つの引数が渡されます。 - 符号なし short int * - 符号なし short int * - double []
XLOPER		P	可変型のワークシートの値および配列
	値	R	値、配列、および範囲の参照

Excel 2007 では、大規模なグリッドと長い Unicode 文字列をサポートするために、次のデータ型が導入されました。

データ型	値渡し	参照渡し (ポインター)	コメント
unsigned short *		C%、F%	Null で終了する Unicode ワイド文字文字列
unsigned short *		D%、G%	カウント付き Unicode ワイド文字文字列
FP12		K%	大きなグリッドの浮動小数点配列構造
配列		O%	次の 3 つの引数が渡されます。 - signed int * / RW * - signed int * / COL * - double []
XLOPER12		Q	可変型のワークシートの値および配列
	値	U	値、配列、および範囲の参照

Excel 2010 以降には、次のデータ型が導入されています。

データ型	値渡し	参照渡し (ポインター)	コメント
XLOPER12		X	非同期ハンドルは、保留中の非同期関数呼び出しを追跡するために Excel と XLL で使用されます。型文字列にパラメーター型があることで、その関数を非同期としても指定しています。非同期関数の詳細については、「非同期のユーザー定義関数」を参照してください。

文字列型 F、F%、G、G% は、インプレースで変更される引数に使用します。

前の表に示されたデータ型を使用する場合は、次の点に注意してください。

C 言語の宣言では、コンパイラが既定で 8 バイトの double、2 バイトの short integer、4 バイトの long integer を使用すると想定しています。
DLL およびコードリソース内のすべての関数は、__stdcall の呼び出し規則を使用して呼び出されます。
データ型を参照で返す関数 (何かへのポインターを返す関数) は、安全に NULL ポインターを返せます。 Excel は、NULL ポインターを #NUM! エラーを返します。

追加のデータ型の情報

このセクションでは、E、F、F%、G、G%、K、O、P、Q、R、および U データ型と、pxTypeText 引数の追加情報について詳細に説明します。

E データ型

Excel は、E データ型を使用する DLL がスタック上の浮動小数点数へのポインターを渡すことを期待します。これは、コプロセッサエミュレータースタック上の数値が渡されることを期待する一部の言語 (Borland C++ など) で問題を起こす可能性があります。回避策としては、コプロセッサスタック上の数値へのポインターを渡します。次の例は、Borland C++ から double が返される方法を示しています。

typedef double * lpDbl;
extern "C" lpDbl __stdcall AddDbl(double D1,
    double D2, WORD npDbl)
{
    lpDbl Result;
    Result = (lpDbl)MK_FP(_SS, npDbl);
    *Result = D1 + D2;
    return (Result);
}

F、F%、G、G% データ型

F、F%、G、G% データ型により、Excel が割り当てた文字列バッファーを関数で変更できるようになります。戻り値の型コードが、これらの型のいずれかの場合、Excel は関数から返された値を無視します。その代わりに、Excel は最初に一致するデータ型 (F、F%、G、または G% ) について関数の引数リストを検索して、割り当てられた文字列バッファーの現在のコンテンツを戻り値として受け取ります。 Excel のすべてのバージョンが F および Gの ASCII 文字列に 256 バイトを割り当てます。Excel 2007 以降では、F% および G% の Unicode 文字列に 65,536 バイトを割り当てます (32,768 文字の Unicode 文字が十分に収まります)。バッファーにはカウント文字 (G 型と G% 型) または NULL で終了する文字 (F 型と F% 型) を含める必要があるため、実際の最大文字列の長さは 255 と 32,767 になる点に注意してください。 Unicode 文字列、つまりF% 型と G%型の引数は、Excel の C API からのみ使用できます。

K および K% データ型

KおよびK% のデータ型は、それぞれ可変サイズの FP および FP12 構造体へのポインターを使用します。これらの構造体は XLLCALL.H で定義されています。 FP12 構造体の K% 型の引数は、Excel 2007 以降でのみサポートされます。

O および O% データ型

O と O% のデータ型は引数にのみ使用でき、戻り値には使用できませんが、O または O% 型の引数を変更すると値を返すことができます。それぞれが、配列内の行数へのポインター、配列内の列数へのポインター、浮動小数点の 2 次元配列へのポインターの 3 つの項目を渡します。

O または O% のデータ型によって渡される配列を変更するには、pxTypeText 引数として ">O" または ">O%" を使用できます。配列の変更の詳細については、このトピックの「インプレースの変更: Void として宣言される関数」セクションを参照してください。

O データ型は、引数を参照で渡す Fortran DLL との直接互換性のために作成されたものです。

O% は Excel 2007 以降でサポートされ、Excel がサポートする巨大な行数に対応します。

P および Q データ型

DLL 関数の引数が P 型の XLOPER または Q 型の XLOPER12 を受け取るように登録されている場合、これらの引数を準備するときに、Excel は単一セルの参照を単純な値と複数セルの配列への参照に変換します。言い換えると、P および Q 型は常に逆参照されるため、xltypeRef、xltypeSRef ではなく、必ず xltypeNum、xltypeStr、xltypeBool、xltypeErr、xltypeMulti、xltypeMissing または xltypeNil のいずれかとして入力されます。 XLOPER12 や Q 型の引数は、Excel 2007 以降でのみサポートされます。

xltypeMissing 型または xltypeNil 型が戻り値に使用されている場合、それらの戻り値は Excel によって数値のゼロと解釈されます。呼び出し元が引数を省略したときには、xltypeMissing が渡されます。呼び出し元が空のセルへの参照を渡したときには、xltypeNil が渡されます。 P 型または Q 型として渡すために、セルの範囲が xltypeMulti に変換されるときには、範囲内にある空白のセルが xltypeNil 配列の要素に変換されます。同様に、リテラル配列内で欠落している要素も xltypeNil 要素として渡されます。

揮発性関数と再計算

ワークシート上で、DLL 関数またはコードリソースを揮発性にすることができるため、ワークシートが再計算されるたびに再計算するようになります。これを行うには、 pxTypeText 引数の最後の引数コードの後に感嘆符 (!) を追加します。

注:

既定では、R 型の XLOPER または U 型の XLOPER12 を受け取り、マクロシートと同等 (# 型: 次のセクションを参照) として登録された関数は、Excel では揮発性として処理されます。

Void として宣言される関数

void を返すように関数を宣言する必要があるケースは 2 つあります。どちらのケースも、関数は別の方法で結果を返します。

インプレースの変更

pxTypeText の戻り値の型コードには 1 桁の n を使用できます。n は 1 から 9 までの数値です。これにより、戻り値の_n_th引数が指す位置にある変数の値in_pxTypeText_as受け取るように Excel に指示されます。これはインプレースの変更とも呼ばれます。 The_n_th引数は、参照渡しデータ型である必要があります (C、D、E、F、F、F%、G、G%、K、K%、L、M、N、O、O%、P、Q、R、U)。さらに、DLL 関数またはコードリソースは、C/C++ 言語の void キーワード (または Pascal 言語のプロシージャ キーワード) を使用して宣言されている必要もあります。

たとえば、引数として NULL で終了する文字列と、整数への 2 つのポインターを受け取る DLL 関数の場合は、文字列をインプレースで変更できます。 pxTypeText 引数として "1FMM" を使用し、関数を void として宣言します。

以前のバージョンの Excel では、pxTypeText の開始時に、関数が void として宣言され、最初の引数が所定の位置に変更されることを示すために使用>されていました。最初の引数以外の引数を変更する方法はありませんでした。 >は、現在の Excel バージョンでは n = 1 に相当し、同期関数でのこの使用>は下位互換性のためにのみサポートされています。

非同期関数

非同期関数 (pxTypeText に X 型のパラメーターを使用して示されます) では、最初の関数呼び出しからの結果は返しません。その代わりに、非同期関数は void として宣言して、後からアドインでコールバックを通じて結果を返す必要があります。非同期関数は、pxTypeTextの先頭に > を使用して登録する必要があります。非同期関数では、その関数が void として宣言されたことを >で示しますが、最初の引数がインプレースで変更されるという意味ではありません。非同期関数の詳細については、「非同期のユーザー定義関数」を参照してください。

ワークシート関数のマクロシート同等としての登録 (計算されないセルの処理)

# pxTypeText で最後のパラメーターコードの後に文字を配置すると、関数にはマクロシートの関数と同じ呼び出しアクセス許可が与えられます。これらは次のとおりです。

この再計算サイクルでは、まだ計算されていないセルの値を取得できる関数。
どの XLM 情報 (Class 2) 関数でも呼び出せる関数 (xlfGetCell など)。
番号記号 (#) が存在しない場合: 計算されていないセルを評価すると xlretUncalced エラーになり、そのセルが計算されると現在の関数が再度呼び出される。xlfCaller 以外の XLM 情報関数を呼び出すと xlretInvXlfn エラーになる。

ワークシート関数をスレッドセーフとして登録する

Excel 2007 以降の Excel は、マルチスレッドでブックの再計算を実行できます。つまり、スレッドセーフな関数の別々のインスタンスを再評価するときに同時実行スレッドに割り当てできるということです。 Excel 2007 以降では、ほとんどの組み込みのワークシート関数がスレッドセーフになっています。また、Excel 2007 以降の Excel では、XLL でワークシート関数をスレッドセーフとして登録することもできます。これを行うには、pxTypeText の$最後のパラメーターコードの後に文字を含めます。

注:

スレッドセーフとして宣言できる関数は、ワークシート関数のみです。 Excel では、マクロシートと同等の関数がスレッドセーフであるとは見なされないため、pxTypeText 引数に文字と $ 文字の両方#を追加することはできません。

関数をスレッドセーフとして登録している場合は、スレッドセーフな方法で動作することを確認する必要があります。ただし、Excel は C API を介してスレッドセーフでない呼び出しを拒否します。たとえば、スレッドセーフ関数が xlfGetCell を呼び出そうとすると、 xlretNotThreadSafe エラーで呼び出しが失敗します。

ワークシート関数をクラスターセーフとして登録する

Excel 2010 以降の Excel では、指定の計算クラスタープロバイダーに関数呼び出しをオフロードできます。詳細については、「クラスターセーフ関数」を参照してください。クラスターセーフとして登録された XLL ワークシート関数はオフロードに加わります (クラスターが利用可能な場合)。クラスターセーフな関数は、pxTypeText 引数の最後のパラメーターコードの後に & 文字を含めることで登録します。

クラスターセーフとして関数を登録した場合は、その関数がクラスターセーフな方法で動作することを保証する必要があります。詳細については、「クラスターセーフ関数」を参照してください。

注:

クラスターセーフとして宣言できる関数は、ワークシート関数のみです。 Excel では、マクロシートと同等の関数がクラスターセーフであるとは見なされないため、pxTypeText 引数に文字と & 文字の両方#を追加することはできません。ワークシート関数は、クラスターセーフとスレッドセーフの両方として宣言できます。この場合、Excel は該当する関数がマルチスレッド再計算に加わることを許可します (クラスターオフローディングが無効な場合)。

カテゴリ名

次のガイドラインを使用して、カスタムの XLL 関数の分類先カテゴリについて判断します。

関数がユーザーが実行できることをアドインユーザーインターフェイスの一部として実行する場合は、その関数をコマンド カテゴリに分類します。
関数がアドインの状態に関する情報などの有用な情報を返す場合は、その関数を情報カテゴリに分類する必要があります。
アドインでは、関数やコマンドをユーザー定義カテゴリに追加してはいけません。このカテゴリは、エンドユーザー専用です。

-カテゴリは、 pxCategory パラメーターを使用して xlfRegister に指定します。これは、ハードコードされた標準カテゴリの 1 つに対応する番号またはテキストになるか、DLL で指定した新しいカテゴリのテキストになります。指定されたテキストが存在していない場合は、その名前の新しいカテゴリが Excel によって作成されます。

次の表は、標準カテゴリの一覧です。これは、ワークシートで [関数の貼り付け] ダイアログボックスを表示すると確認できます。

数値	テキスト
1	財務
2	日付/時刻
3	数学/三角
4	テキスト
5	論理演算子
6	検索/行列
7	データベース
8	統計
9	情報
14	ユーザー定義
	エンジニアリング (Excel 2007 以降)
	キューブ (Excel 2007 以降)

また、マクロシートで [関数の貼り付け] ダイアログボックスを表示すると、次のカテゴリも確認できます。

数値	テキスト
10	コマンド
11	DDE/外部
12	ユーザー設定
13	マクロ制御

例

の xlAutoOpen 関数のコードを\SAMPLES\GENERIC\GENERIC.C参照してください。

次の方法で共有

xlfRegister (形式 1)

パラメーター

プロパティの値/戻り値

備考

データ型

追加のデータ型の情報

E データ型

F、F%、G、G% データ型

K および K% データ型

O および O% データ型

P および Q データ型

揮発性関数と再計算

Void として宣言される関数

インプレースの変更

非同期関数

ワークシート関数のマクロシート同等としての登録 (計算されないセルの処理)

ワークシート関数をスレッドセーフとして登録する

ワークシート関数をクラスターセーフとして登録する

カテゴリ名

例

関連項目

フィードバック

その他のリソース

次の方法で共有

xlfRegister (形式 1)

パラメーター

プロパティの値/戻り値

備考

データ型

追加のデータ型の情報

E データ型

F、F%、G、G% データ型

K および K% データ型

O および O% データ型

P および Q データ型

揮発性関数と再計算

Void として宣言される関数

インプレースの変更

非同期関数

ワークシート関数のマクロ シート同等としての登録 (計算されないセルの処理)

ワークシート関数をスレッドセーフとして登録する

ワークシート関数をクラスターセーフとして登録する

カテゴリ名

例

関連項目

フィードバック

その他のリソース

ワークシート関数のマクロシート同等としての登録 (計算されないセルの処理)