API関数の呼出し

各API関数には、接頭辞Ess (Cの場合)またはEsb (Visual Basicの場合)が付き、その後にverb-object命名ルールが続きます。たとえばEssGetDatabaseInfo()となります。製品の特定の領域に関係するいくつかの関数には、その関係を示すために追加の接頭辞が付いています。たとえば、アウトラインAPI関数にはすべてEssOtlまたはEsbOtlの接頭辞が付いています。

API関数はすべて、一連の引数をとります。引数は関数ごとに異なり、論理的な順序に従います。通常、ほとんどの関数で最初の引数はハンドルであり、インスタンス・ハンドル、コンテキスト・ハンドル、アウトライン・ハンドルまたはメンバー・ハンドルのいずれかです。「ハンドル」という用語は、(ファイル・ハンドルのように)システムにおいて異なるオブジェクトを追跡するため、APIが使用する識別子を意味します。異なるハンドルが、特定の関数によって戻されます。次に、ハンドルはプログラムに保管され、必要に応じて他のAPI関数に渡される必要があります。

ハンドルはCとVisual Basicで異なります。様々なタイプのAPIハンドルとその使用方法の詳細は、CのメインAPIの使用およびVisual BasicのメインAPIの使用。を参照してください。

関数へ渡す引数がある場合、通常、引数は順序で次にきます。最後に、関数が値を戻す場合、それらの戻り値を保管する変数は、引数リストの終わりで渡されます。

次の例では、最初の引数はコンテキスト・ハンドル(hCtx)です。次の2つの引数(アプリケーションとデータベースの名前、SampleとBasic)が渡され、戻ってくる引数(データベース情報構造体、ESX_DBINFO_T)が最後に渡されます:

      /* C Example of passing arguments to an API function */
ESS_STS_T       sts;
ESS_HCTX_T      hCtx;
ESS_PDBINFO_T   pDbInfo;
sts = EssGetDatabaseInfo (hCtx, "Sample", "Basic", &pDbInfo);
if (sts == ESS_STS_NOERR)
{
        do something;
}

' VB Example of passing arguments to an API function
Dim     sts as ESB_STS_T
Dim     hCtx as ESB_HCTX_T
Dim     DbInfo as ESB_DBINFO_T
sts = EsbGetDatabaseInfo (hCtx, "Sample", "Basic", DbInfo)
if (sts = ESB_STS_NOERR)
        do something
endif
   

Cの例では、戻された引数(pDbInfo)が、二重間接(ポインタへのポインタ)として関数に渡されることに注意してください。(&演算子を使用して)宣言された構造体ポインタ変数のアドレスを渡します。次に、この変数は、API関数が内部に割り当てたデータベース情報構造体のアドレスを割り当てられます。

Visual Basicの例では、呼出し元が最初に構造体(DbInfo)を割り当て、次に構造体をAPI関数に(参照で明示的に)渡しています。