この関数は、IEngine インターフェイスへのポインターを取得するために使用します。入力パラメーターとして Customer Project ID 番号を受け取ります。これは、プロジェクトで使用するすべての Developer ライセンスおよびランタイム ライセンスに共通の英数字の string です。
Linux および Windows のユーザーの場合、この関数を使用すると、必要に応じてオンライン ライセンス認証に簡単にアクセスできるほか、初期化時にいくつかの追加パラメーターを指定することもできます。
HRESULT __stdcall InitializeEngine (
BSTR CustomerProjectID ,
BSTR LicensePath ,
BSTR LicensePassword ,
BSTR FREngineDataFolder ,
BSTR FREngineTempFolder ,
VARIANT_BOOL IsSharedCPUCoresMode ,
IEngine** Engine
);
int InitializeEngine (
string CustomerProjectID ,
string LicensePath ,
string LicensePassword ,
string FREngineDataFolder ,
string FREngineTempFolder ,
bool IsSharedCPUCoresMode ,
ref IEngine Engine
);
Private Declare Function InitializeEngine Lib "FREngine.dll" ( _
CustomerProjectID As String , _
LicensePath As String , _
LicensePassword As String , _
FREngineDataFolder As String , _
FREngineTempFolder As String , _
IsSharedCPUCoresMode As Boolean , _
ByRef Engine As FREngine . IEngine ) _
As Integer
CustomerProjectID
[in] Customer Project ID を含む string です。
ライブラリの初期化時に、この Customer Project ID に対応する Developer または Runtime License が、使用可能なすべてのライセンスの一覧から検索されます。対応するライセンスが見つからない場合は、最後に確認されたライセンスに対するエラーが発生します。ただし、このパラメーターに 0 を渡しておき、他のライブラリ メソッドを呼び出す前に IEngine::SetCurrentLicense メソッドを呼び出すことで、後からライセンスを選択することもできます。
LicensePath
[in] オンライン ライセンス ファイルの完全なファイル名です。オンライン ライセンスを使用しない場合は、代わりに空の string "" または Null ポインターを渡します。空の string "" または Null ポインターを渡してください。
macOS ユーザー向け: このパラメーターは将来の使用のために予約されています。
LicensePassword
[in] オンライン ライセンスの password です。オンライン ライセンスを使用しない場合は、代わりに空の string "" または Null ポインターを渡します。
macOS ユーザー向け: このパラメーターは将来の使用のために予約されています。
FREngineDataFolder
[in] ABBYY FineReader Engine がユーザー固有のデータを保存するフォルダーへのパスを指定します。
既定では、自動インストールの場合:
%ProgramData%\ABBYY\SDK\12\FineReader Engine for auxiliary engine data
さらに、Linux および Windows の場合:
%ProgramData%\ABBYY\SDK\12\Licenses for license data
FREngineDataFolder の値を設定すると、すべての補助情報は新しいデータ フォルダーに書き込まれます。
たとえば、アプリケーションのインターフェイス言語設定を、FineReader Engine を使用する他のアプリケーションとは異なるものにする必要がある場合は、既定値を変更する必要があります。既定値を変更した後は、新しいデータ フォルダーに対するフル コントロール権限があることを確認してください。
FREngineTempFolder
[in] ABBYY FineReader Engine の一時ファイル用フォルダーへのパスを指定します。既定では、%TEMP%\ABBYY FineReader Engine 12 フォルダーです。
IsSharedCPUCoresMode
[in] CPU コアを共有モードで使用するかどうかを指定します。CPU コアの使用モードには、分離モードと共有モードの 2 つがあります。分離モードでは、ABBYY FineReader Engine はライセンスで許可されている数を超えるプロセスを使用しません。共有モードでは任意の数のプロセスを実行できますが、それらのプロセスで使用される CPU コアは、IMultiProcessingParams::SharedCPUCoresMask プロパティで指定されたものに限られます。
このパラメーターは、Windows 版 ABBYY FineReader Engine では無視されます。
Engine
[out, retval] 結果の Engine object への interface pointer を受け取る IEngine* ポインター変数へのポインターです。
この関数は、ABBYY FineReader Engine 関数の標準の戻り値 を返すことがあります。
ABBYY FineReader Engine を使用するアプリケーションの単一インスタンス内では、この関数を使用して作成できる Engine オブジェクトは 1 つだけです。Engine オブジェクトを繰り返し作成しようとしても、返されるのは同じオブジェクトです。
Engine オブジェクトの作成には、かなり時間がかかる場合があります。初期化中、エンジンは以下に示すメインライブラリに加えて、多数の追加の動的ライブラリを読み込みます。
Linux: libFREngine.so
macOS: libFREngine.dylib
Windows: FREngine.dll
ネットワーク ライセンスを使用している場合、Linux と Windows ではライセンスサーバーとの通信により、初期化にさらに時間がかかることがあります。ネットワーク接続が必要な性能を満たしていることを確認してください。ネットワーク ライセンスで安定して動作させるには、少なくとも 100 Kb/s の帯域幅を推奨します。
マルチプロセッサシステム上で Engine オブジェクトを作成して実行することは可能ですが、各プロセスで作成できる Engine オブジェクトは 1 つだけです。同じプロセス内で InitializeEngine を 2 回目に呼び出すと、既存のオブジェクトへの参照が返されます。したがって、InitializeEngine 関数を呼び出して、プロセスごとに個別の Engine オブジェクトを作成する必要があります。
マルチプロセッサシステムを含む ABBYY FineReader Engine for Windows の実装では、Engine オブジェクトを読み込むための他の方法 も役立つ場合があります。
ABBYY FineReader Engine の初期化および終了処理を、他の動的ライブラリのエントリポイントや、動的ライブラリ内で実装された static オブジェクトおよび global オブジェクトのコンストラクターやデストラクターで行わないでください。これらは動的ライブラリのエントリポイントで呼び出されるためです。
ユーザーは、ABBYY FineReader Engine の初期化および終了処理を別の場所で行う必要があります。たとえば、実行可能モジュールの main 関数または WinMain 関数です。
: Windows では、この制限は Win32 の LoadLibrary 関数および FreeLibrary 関数がリエントラントではないことに起因します。
初期化中に、ABBYY FineReader Engine は LC_CTYPE の設定をオペレーティングシステムの既定値にリセットします。アプリケーションがロケール依存のサービス (特に Windows の msvcrt.dll) に依存している場合は、この点を考慮する必要があります。
.NET を使用する Windows 開発者は、アプリケーションの main 関数に [STAThread] (シングルスレッド アパートメント モデル) 属性を必ず指定する必要があります。そうしないと、エラーが発生する場合があります。
[STAThread]
public static void Main()
{
...
}
有効な Customer Project ID 番号を入力パラメーターとして渡す必要があります。ただし、処理に使用するライセンスは、いずれの処理メソッドを呼び出す前でも、Engine オブジェクト の SetCurrentLicense メソッドを呼び出して選択できます。使用可能なアクティブ化済みライセンスの一覧を確認するには GetAvailableLicenses メソッドを使用し、現在どのライセンスが選択されているかを確認するには Engine オブジェクト の CurrentLicense プロパティを使用します。
// これらの変数を、FREngine.dll へのパス、FineReader Engine の Customer Project ID、
// および必要に応じて、オンライン ライセンス トークンへのパスとオンライン ライセンスのパスワードで初期化します
wchar_t * FreDllPath;
wchar_t * CustomerProjectId;
wchar_t * LicensePath; // オンライン ライセンスを使用しない場合は、これらの変数に空文字列を設定します
wchar_t * LicensePassword;
// FREngine.dll への HANDLE
static HMODULE libraryHandle = 0 ;
// グローバル FineReader Engine オブジェクト。
FREngine ::IEnginePtr Engine;
void LoadFREngine ()
{
if ( Engine != 0 ) {
// すでに読み込み済み
return ;
}
// 最初の手順: FREngine.dll を読み込む
if ( libraryHandle == 0 ) {
libraryHandle = LoadLibraryEx ( FreDllPath, 0 , LOAD_WITH_ALTERED_SEARCH_PATH );
if ( libraryHandle == 0 ) {
throw L"ABBYY FineReader Engine の読み込み中にエラーが発生しました" ;
}
}
// 2 番目の手順: Engine オブジェクトを取得する
typedef HRESULT ( STDAPICALLTYPE * InitializeEngineFunc )( BSTR, BSTR, BSTR, BSTR,
BSTR, VARIANT_BOOL, FREngine ::IEngine ** );
InitializeEngineFunc pInitializeEngine =
( InitializeEngineFunc ) GetProcAddress ( libraryHandle, "InitializeEngine" );
if ( pInitializeEngine == 0 || pInitializeEngine ( CustomerProjectId, LicensePath,
LicensePassword, L"" , L"" , VARIANT_FALSE, & Engine ) != S_OK ) {
UnloadFREngine ();
throw L"ABBYY FineReader Engine の読み込み中にエラーが発生しました" ;
}
}
public class EngineLoader : IDisposable
{
public EngineLoader ()
{
// これらの変数は、FREngine.dll へのフル パス、Customer Project ID、
// および必要に応じて、オンライン ライセンス トークン ファイルへのパスとオンライン ライセンスのパスワードで初期化してください
string enginePath = "" ;
string customerProjectId = "" ;
string licensePath = "" ;
string licensePassword = "" ;
// FREngine.dll ライブラリを読み込みます
dllHandle = LoadLibraryEx ( enginePath , IntPtr . Zero , LOAD_WITH_ALTERED_SEARCH_PATH );
try
{
if ( dllHandle == IntPtr . Zero )
{
throw new Exception ( "Can't load " + enginePath );
}
IntPtr initializeEnginePtr = GetProcAddress ( dllHandle , "InitializeEngine" );
if ( initializeEnginePtr == IntPtr . Zero )
{
throw new Exception ( "Can't find InitializeEngine function" );
}
IntPtr deinitializeEnginePtr = GetProcAddress ( dllHandle , "DeinitializeEngine" );
if ( deinitializeEnginePtr == IntPtr . Zero )
{
throw new Exception ( "Can't find DeinitializeEngine function" );
}
IntPtr dllCanUnloadNowPtr = GetProcAddress ( dllHandle , "DllCanUnloadNow" );
if ( dllCanUnloadNowPtr == IntPtr . Zero )
{
throw new Exception ( "Can't find DllCanUnloadNow function" );
}
// ポインターをデリゲートに変換します
initializeEngine = ( InitializeEngine ) Marshal . GetDelegateForFunctionPointer (
initializeEnginePtr , typeof ( InitializeEngine ));
deinitializeEngine = ( DeinitializeEngine ) Marshal . GetDelegateForFunctionPointer (
deinitializeEnginePtr , typeof ( DeinitializeEngine ));
dllCanUnloadNow = ( DllCanUnloadNow ) Marshal . GetDelegateForFunctionPointer (
dllCanUnloadNowPtr , typeof ( DllCanUnloadNow ));
// InitializeEngine 関数を呼び出し、
// オンライン ライセンス ファイルへのパスとオンライン ライセンスのパスワードを渡します
int hresult = initializeEngine ( customerProjectId , licensePath , licensePassword ,
"" , "" , false , ref engine );
Marshal . ThrowExceptionForHR ( hresult );
}
catch ( Exception )
{
// FREngine.dll ライブラリを解放します
engine = null ;
// FreeLibrary を呼び出す前にすべてのオブジェクトを削除します
GC . Collect ();
GC . WaitForPendingFinalizers ();
GC . Collect ();
FreeLibrary ( dllHandle );
dllHandle = IntPtr . Zero ;
initializeEngine = null ;
deinitializeEngine = null ;
dllCanUnloadNow = null ;
throw ;
}
}
// Kernel32.dll 関数
[ DllImport ( "kernel32.dll" )]
private static extern IntPtr LoadLibraryEx ( string dllToLoad , IntPtr reserved , uint flags );
private const uint LOAD_WITH_ALTERED_SEARCH_PATH = 0x00000008 ;
[ DllImport ( "kernel32.dll" )]
private static extern IntPtr GetProcAddress ( IntPtr hModule , string procedureName );
[ DllImport ( "kernel32.dll" )]
private static extern bool FreeLibrary ( IntPtr hModule );
// FREngine.dll 関数
[ UnmanagedFunctionPointer ( CallingConvention . StdCall , CharSet = CharSet . Unicode )]
private delegate int InitializeEngine ( string customerProjectId , string licensePath ,
string licensePassword , string tempFolder , string dataFolder , bool isSharedCPUCoresMode ,
ref FREngine . IEngine engine );
[ UnmanagedFunctionPointer ( CallingConvention . StdCall )]
private delegate int DeinitializeEngine ();
[ UnmanagedFunctionPointer ( CallingConvention . StdCall )]
private delegate int DllCanUnloadNow ();
// private 変数
private FREngine . IEngine engine = null ;
// FREngine.dll へのハンドル
private IntPtr dllHandle = IntPtr . Zero ;
private InitializeEngine initializeEngine = null ;
private DeinitializeEngine deinitializeEngine = null ;
private DllCanUnloadNow dllCanUnloadNow = null ;
}
この関数は、EnginesPool (Win) を除くすべてのコード サンプル で使用されています。
ライセンス管理
モジュール
DeinitializeEngine
Engine オブジェクトを読み込む方法の違い (Win)