Vai al contenuto principale
Questa funzione serve per ottenere un puntatore all’interfaccia IEngine. Accetta come parametro di input il numero Customer Project ID, ovvero una stringa alfanumerica comune a tutte le licenze Developer e Runtime utilizzate dal progetto.
Per gli utenti Linux e Windows, questa funzione fornisce un accesso semplificato alla gestione delle licenze online, se necessario, e consente anche di specificare alcuni parametri aggiuntivi durante l’inizializzazione.

​
Sintassi

​
C++

HRESULT __stdcall InitializeEngine(
  BSTR CustomerProjectID,
  BSTR LicensePath,
  BSTR LicensePassword,
  BSTR FREngineDataFolder,
  BSTR FREngineTempFolder,
  VARIANT_BOOL IsSharedCPUCoresMode,
  IEngine** Engine
);

​
C#

int InitializeEngine(
  string CustomerProjectID,
  string LicensePath,
  string LicensePassword,
  string FREngineDataFolder,
  string FREngineTempFolder,
  bool IsSharedCPUCoresMode,
  ref IEngine Engine
);

​
Visual Basic .NET

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

​
Parametri

CustomerProjectID [in] Una string contenente il Customer Project ID.
Durante l’inizializzazione della libreria, nell’elenco di tutte le licenze disponibili viene cercata una License Developer o Runtime corrispondente a questo Customer Project ID. Se non viene trovata alcuna licenza corrispondente, si verificherà un errore relativo all’ultima licenza controllata. Tuttavia, è possibile passare 0 per questo parametro e selezionare la licenza in un secondo momento, chiamando il metodo IEngine::SetCurrentLicense prima di qualsiasi altro metodo della libreria.
LicensePath [in] Il nome completo del file della licenza online. Se non utilizzi una licenza online, passa invece una stringa vuota "" oppure un puntatore Null. In questo caso, occorre passare una stringa vuota "" oppure un puntatore Null. Per gli utenti macOS: questo parametro è riservato a un utilizzo futuro. LicensePassword [in] La password della licenza online. Se non utilizzi una licenza online, passa invece una stringa vuota "" oppure un puntatore Null. Per gli utenti macOS: questo parametro è riservato a un utilizzo futuro. FREngineDataFolder [in] Contiene il percorso della cartella in cui ABBYY FineReader Engine deve archiviare i dati specifici dell’utente. Per impostazione predefinita, per l’installazione automatica: %ProgramData%\ABBYY\SDK\12\FineReader Engine for auxiliary engine data Inoltre, per Linux e Windows: %ProgramData%\ABBYY\SDK\12\Licenses for license data Se imposti il valore di FREngineDataFolder, tutte le informazioni ausiliarie verranno scritte in una nuova cartella dati. Potrebbe essere necessario modificare il valore predefinito, ad esempio se le impostazioni della lingua dell’interfaccia della tua applicazione devono essere diverse da quelle di altre applicazioni che utilizzano FineReader Engine. Dopo aver modificato il valore predefinito, assicurati di disporre delle autorizzazioni di controllo completo per la nuova cartella dati. FREngineTempFolder [in] Contiene il percorso della cartella per i file temporanei di ABBYY FineReader Engine. Per impostazione predefinita, è la cartella %TEMP%\ABBYY FineReader Engine 12. IsSharedCPUCoresMode [in] Specifica se i core della CPU devono essere utilizzati in modalità condivisa. Esistono due modalità di utilizzo dei core della CPU: separata e condivisa. In modalità separata, ABBYY FineReader Engine non utilizza più processi di quanti ne siano consentiti dalla licenza. In modalità condivisa, può essere eseguito un numero qualsiasi di processi, ma tutti questi processi utilizzeranno solo i core della CPU specificati dalla proprietà IMultiProcessingParams::SharedCPUCoresMask.
Questo parametro viene ignorato in ABBYY FineReader Engine per Windows.
Engine [out, retval] Un puntatore alla variabile puntatore IEngine* che riceve il puntatore di interfaccia all’oggetto Engine risultante.

​
Valori di ritorno

La funzione può restituire i valori di ritorno standard delle funzioni di ABBYY FineReader Engine.

​
Osservazioni

È possibile creare un solo oggetto Engine tramite questa funzione in una singola istanza dell’applicazione che utilizza ABBYY FineReader Engine. I tentativi ripetuti di creare l’oggetto Engine restituiranno lo stesso oggetto.
La creazione dell’oggetto Engine può richiedere un tempo considerevole. Durante l’inizializzazione, il motore carica la libreria principale elencata di seguito insieme a un gran numero di librerie dinamiche aggiuntive:
  • Linux: libFREngine.so
  • macOS: libFREngine.dylib
  • Windows: FREngine.dll
Quando si utilizza una licenza di rete, l’inizializzazione su Linux e Windows potrebbe richiedere più tempo a causa della comunicazione con il server delle licenze. Assicurarsi che la connessione di rete soddisfi i requisiti di prestazione; per un funzionamento affidabile con una licenza di rete si raccomanda una larghezza di banda di almeno 100 Kb/s.
È possibile creare ed eseguire l’oggetto Engine su un sistema multi-processore, ma in ogni processo può esistere un solo oggetto Engine. Una seconda chiamata a InitializeEngine all’interno dello stesso processo restituirà il riferimento all’oggetto esistente. È quindi necessario creare un oggetto Engine separato per ogni processo richiamando la funzione InitializeEngine.
Per le implementazioni di ABBYY FineReader Engine per Windows su sistemi multi-processore, potrebbero risultare utili altri metodi di caricamento dell’oggetto Engine.
Non inizializzare e deinitializzare ABBYY FineReader Engine nei punti di ingresso di altre librerie dinamiche, né nei costruttori e distruttori di oggetti statici e globali implementati in librerie dinamiche, poiché questi vengono richiamati nei punti di ingresso delle librerie dinamiche.
L’utente deve inizializzare e deinitializzare ABBYY FineReader Engine in un contesto diverso, ad esempio nella funzione main o WinMain di un modulo eseguibile.
: In Windows, questa restrizione è dovuta al fatto che le funzioni Win32 LoadLibrary e FreeLibrary non sono rientranti.
Durante l’inizializzazione, ABBYY FineReader Engine reimposta l’impostazione LC_CTYPE ai valori predefiniti del sistema operativo. Questo aspetto deve essere tenuto in considerazione se l’applicazione dipende da servizi sensibili alle impostazioni locali (in particolare msvcrt.dll in Windows). Gli sviluppatori Windows che utilizzano .NET devono assicurarsi di specificare [STAThread] (modello apartment a thread singolo) come attributo sulla funzione principale dell’applicazione; in caso contrario, potrebbe verificarsi un errore: 
[STAThread]
public static void Main()
{
  ...
}
Devi passare un Customer Project ID valido come parametro di input. Tuttavia, puoi scegliere la licenza da utilizzare per l’elaborazione chiamando il metodo SetCurrentLicense dell’oggetto Engine prima di eseguire qualsiasi metodo di elaborazione. Usa il metodo GetAvailableLicenses per esaminare l’elenco delle licenze attivate disponibili che puoi utilizzare e la proprietà CurrentLicense dell’oggetto Engine per verificare quale licenza è già selezionata.

​
Esempi

// Inizializza queste variabili con il percorso di FREngine.dll, il tuo Customer Project ID di FineReader Engine,
// e, se necessario, il percorso del token della licenza online e la password della licenza online
wchar_t* FreDllPath;
wchar_t* CustomerProjectId;
wchar_t* LicensePath;  // se non utilizzi una licenza online, assegna stringhe vuote a queste variabili
wchar_t* LicensePassword;
// HANDLE di FREngine.dll
static HMODULE libraryHandle = 0;
// Oggetto globale FineReader Engine.
FREngine::IEnginePtr Engine;
void LoadFREngine()
{
    if( Engine != 0 ) {
    // Già caricato
    return;
    }
    // Primo passaggio: carica FREngine.dll
    if( libraryHandle == 0 ) {
        libraryHandle = LoadLibraryEx( FreDllPath, 0, LOAD_WITH_ALTERED_SEARCH_PATH );
        if( libraryHandle == 0 ) {
            throw L"Errore durante il caricamento di ABBYY FineReader Engine";
        }
    }
    // Secondo passaggio: ottieni l'oggetto 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"Errore durante il caricamento di ABBYY FineReader Engine";
    }
}

public class EngineLoader : IDisposable
{
    public EngineLoader()
    {
        // Inizializza queste variabili con il percorso completo di FREngine.dll, il Customer Project ID
        // e, se applicabile, il percorso del file token della licenza online e la relativa password
        string enginePath = "";
        string customerProjectId = "";
        string licensePath = "";
        string licensePassword = "";
        // Carica la libreria 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");
            }
            // Converte i puntatori in delegati
            initializeEngine = (InitializeEngine)Marshal.GetDelegateForFunctionPointer(
                initializeEnginePtr, typeof(InitializeEngine));
            deinitializeEngine = (DeinitializeEngine)Marshal.GetDelegateForFunctionPointer(
                deinitializeEnginePtr, typeof(DeinitializeEngine));
            dllCanUnloadNow = (DllCanUnloadNow)Marshal.GetDelegateForFunctionPointer(
                dllCanUnloadNowPtr, typeof(DllCanUnloadNow));
            // Chiama la funzione InitializeEngine 
            // passando il percorso del file della licenza online e la relativa password
            int hresult = initializeEngine(customerProjectId, licensePath, licensePassword, 
                "", "", false, ref engine);
            Marshal.ThrowExceptionForHR(hresult);
        }
        catch (Exception)
        {
            // Libera la libreria FREngine.dll
            engine = null;
            // Elimina tutti gli oggetti prima della chiamata a FreeLibrary
            GC.Collect();
            GC.WaitForPendingFinalizers();
            GC.Collect();
            FreeLibrary(dllHandle);
            dllHandle = IntPtr.Zero;
            initializeEngine = null;
            deinitializeEngine = null;
            dllCanUnloadNow = null;
            throw;
        }
    }
    // Funzioni di 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);
    // Funzioni di 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();
    // Variabili private
    private FREngine.IEngine engine = null;
    // Handle di FREngine.dll
    private IntPtr dllHandle = IntPtr.Zero;
    private InitializeEngine initializeEngine = null;
    private DeinitializeEngine deinitializeEngine = null;
    private DllCanUnloadNow dllCanUnloadNow = null;
}
La funzione viene usata in tutti gli esempi di codice, tranne EnginesPool (Win).

​
Vedi anche

Gestione delle licenze Moduli DeinitializeEngine Diversi modi per caricare l’oggetto Engine (Win)