Exportservice API

Funktionscodes

Folgende Funktionscodes werden von der API unterstützt.

Funktion

Code

Beschreibung

ccfCode_ES_Initialize

100

Initialisierung der Schnittstelle.

ccfCode_ES_GetInterfaceVersion

101

Abfrage der Interface Version (Default ist 1).

ccfCode_ES_GetVersion

105

Versionsabfrage.

ccfCode_ES_SetConfig

110

Übergabe der Konfigurationsdaten vom aufrufenden Programm.

ccfCode_ES_SetParameter       

115

Parameterübergabe.

ccfCode_ES_SetOEMInfos

116

OEM Informationen übergeben.

ccfCode_ES_GetDocPath

120

Abfrage des Ablageverzeichnisses für Dateien.

ccfCode_ES_SetDestination

130

Übergabe des Exportziels (z.B. Archivname).

ccfCode_ES_SetExpBuffer   

160

Exportpuffer setzen.

ccfCode_ES_GetExpBuffer   

170

Exportpuffer abfragen (Daten für Zwischenspeicherung).

ccfCode_ES_StartDoc  

200

Start eines neuen Dokuments.

ccfCode_ES_StartStack

250

Start eines neuen Stapels.

ccfCode_ES_AddTitle  

300

Übergabe des Dokumenten-Titels.

ccfCode_ES_AddDocId350Übergabe der internen CLARC Dokumenten-Id (32 stellige GUID).

ccfCode_ES_AddField  

400

Übergabe eines Indizes.

ccfCode_ES_AddTableData

450

Übergabe von Positionsdaten.

ccfCode_ES_AddTableRow460Übergabe von Positionszeileninformationen

ccfCode_ES_AddBlob  

500

Übergabe eines Blobs als Pfadangabe (full qualified).

ccfCode_ES_AddBlobName

510

Übergabe eines Blobbezeichners (optional).

ccfCode_ES_AddBlobDocType

530

Übergabe eines Dokumenttyps (optional).

ccfCode_ES_EndDoc    

600

Abschluss eines Dokuments.

ccfCode_ES_EndStack

650

Abschluss eines Stapels.

ccfCode_ES_RollBack

700

Rollback des letzten Stapels.

ccfCode_ES_CallCfgDlg

800

Aufruf des Konfigurationsdialogs (im Return die Konfigurationsdaten .übergeben).

ccfCode_ES_GetConfig 

850

Abfrage der Konfigurationsdaten.

ccfCode_ES_Finalize  

900

Freigabe der Schnittstelle.

Funktionsdeklaration ANSI

function ccExport( fCode : LongInt;
                   fData : PChar;
                   fSize : LongInt;
                   Msg   : PChar ) : LongInt;

Mit der Übergabe eines Funktionscodes in der Variable fCode wird die entsprechende Funktion ausgewählt (s. Tab.).

Im Erfolgsfall wird im Funktionsresult 0 zurückgegeben. Im Fehlerfall ein Wert von -1 (grundsätzlich <> 0). Als Besonderheit kann in Kombination mit eWork und dem Error-Return von -2 das Dokument zurück in die Benutzerqueue geleitet werden. Der Returncode -3 zeigt ein Lizenzproblem an.

Die Variable Msg nimmt einen Meldungstext auf welcher im Problemfall durch die aufrufende Anwendung im entsprechenden Logfile protokolliert wird. Eine Erfolgsmeldung nach ccfCode_ES_EndDoc wird je nach Anwendung ebenfalls protokolliert.

fData nimmt alle übrigen Übergabedaten, wie z.B. die Indexfelder, auf. Zugehörig muss immer fSize mit der entsprechenden Größe von fData gesetzt werden.

Das ANSI Interface ist optional und nur zur Abwärtskompatibilität erforderlich (z.B. eWork 2.x).

Funktionsdeklaration UNICODE

function ccWideExport( fCode : LongInt;
                       fData : PWideChar;
                       fSize : LongInt;
                       Msg   : PWideChar ) : LongInt;

ANSI und UNICODE Interfaces können in einem Exportservice gleichzeitig verwendet werden.

Ab Version 5.x wird ausschließlich das Unicode Interface unterstützt.

Übergabe von Metadaten (Interface Version 1)

Die Übergabe erfolgt als String und hat den nachfolgenden Aufbau.

Datentypen werden in dieser Schnittstellen-Version nur indirekt unterstützt (länderspezifische Formatierungen können im C4 konfiguriert werden).

Bei der Übergabe von Tabelleninformationen ist zu beachten, dass die Zeilennummer Row mit 0 beginnt.

Funktion

Übergabestruktur

ccfCode_ES_AddField  

FieldName=Value

ccfCode_ES_AddTableDataColumnName,Row=Value

Beispiel für ccfCod_ES_AddField

Example=Hi There

Übergabe von Metadaten (Interface Version 2)

Die Übergabe erfolgt als String und hat nachfolgenden Aufbau.

Datentypen werden direkt unterstützt und als Variant-Type mit übergeben. 

Alle Informationen zu den möglichen Datentypen und deren Formatierung finden Sie unter Engine API's.

Funktion

Übergabestruktur

ccfCode_ES_AddField  

FieldName[DataType]=Value

ccfCode_ES_AddTableDataColumnName[DataType],Row=Value

Beispiel für ccfCod_ES_AddField

Example[UCS4STR]=Hi There

Beispiel für ccfCode_ES_AddTableData

CellExample[DATE],0=2016-01-01

Übergabe von Metadaten (Interface Version 3)

Die Schnittstellen-Version 3 erlaubt es zusätzlich zum Namen, Typ und Inhalt eines Feldes, dessen Position innerhalb eines Dokuments, inklusive Vertrauenswert (Confidence), zu übergeben. Die Übergabe erfolgt als String und hat nachfolgenden Aufbau.

Der Parameter Page ist 0 basierend, heißt die erste Seite hat den Wert 0 usw. Die Positionsangaben Left, Top, Width und Height erfolgen in Twips. Der Vertrauenswert Confidence ist eine ganzzahlige Prozentangabe zwischen 0 und 100. 0 bedeutet in diesem Zusammenhang, dass der Inhalt nicht vertrauenswürdig ist, 100 hingegen zeigt eine 100%ige Sicherheit für den Inhalt an.

Funktion

Übergabestruktur

ccfCode_ES_AddField  

FieldName[DataType,Page,Left,Top,Width,Height,Confidence]=Value

ccfCode_ES_AddTableData

ColumnName[DataType,Page,Left,Top,Width,Height,Confidence],Row=Value

ccfCode_ES_AddTableRowRowNum=[Page,Left,Top,Width,Height,Confidence]

Beispiel für ccfCod_ES_AddField

Example[UCS4STR,0,10,10,1000,500,90]=Hi There

Beispiel für ccfCode_ES_AddTableData

CellExample[DATE,0,10,10,400,200,100],0=2016-01-01

Beispiel für ccfCode_ES_AddTableRow

0=[0,10,10,400,200,100]

Übergabe von Metadaten (Interface Version 4)

Die Schnittstellen-Version 4 beinhaltet alle Funktionen der Version 3. Hinzu kommt die Übergabe der Zeileninformationen wie unten beschrieben.

Der Parameter Page ist 0 basierend, heißt die erste Seite hat den Wert 0 usw. Die Positionsangaben Left, Top, Width und Height erfolgen in Twips. Der Vertrauenswert Confidence ist eine ganzzahlige Prozentangabe zwischen 0 und 100. 0 bedeutet in diesem Zusammenhang, dass der Inhalt nicht vertrauenswürdig ist, 100 hingegen zeigt eine 100%ige Sicherheit für den Inhalt an.

Funktion

Übergabestruktur

ccfCode_ES_AddTableRowRowNum=[Page,Left,Top,Width,Height,Confidence]

Beispiel für ccfCode_ES_AddTableRow

0=[0,10,10,400,200,100]

Grundlegender Ablauf eines Exports

1.

ccfCodeInitialize

2.

ccfCodeGetInterfaceVersion

3.

ccfCodeGetVersion    

4.

ccfCodeSetConfig   

5.

ccfCodeGetDocPath  


6.

ccfCodeSetDestination


7.

ccfCodeSetParameter  


8.

ccfCodeStartStack


9.

ccfCodeStartDoc 


10.

ccfCodeAddTitle 


11.ccfCodeAddDocId


12.

ccfCodeAddField (n-fach)


13.ccfCodeAddTableRow (n-fach)


14.

ccfCodeAddTableData (n-fach)


15.

ccfCodeAddBlob (n-fach)


16.

ccfCodeAddBlobName (n-fach)


17.

ccfCodeEndDoc   


18.

ccfCodeEndStack

19.

ccfCodeFinalize   

Die Punkte 9-15 werden ggf. mehrfach wiederholt – pro Ablagevorgang einmal. Ebenfalls die Punkte 8 und 16 – je Verarbeitungsstapel einmal. Zudem kann über den Aufruf 6 das Exportziel vor jedem Vorgang geändert werden.

Die Initialisierungs- und Finalize-Routine wird je nach Anwendung einmal pro Exportvorgang oder einmal pro Anwendungsstart (aktuell) aufgerufen. In letzterem Fall kann dies auch bei Konfigurationsänderungen erfolgen.

Delphi Codeframe

Auf Basis von Delphi XE5 bzw. Lazarus.

library ccExampleExport;

// ================================================================
{$R *.res}
{$WARN UNIT_PLATFORM OFF}
{$WARN SYMBOL_PLATFORM OFF}

// ================================================================
uses
  Classes;

// ================================================================
const
  Version          = '1.0.0';
  InterfaceVersion = '1';

// ----------------------------------------------------------------
const
  ccfCode_ES_Initialize         = 100;
  ccfCode_ES_GetInterfaceVersion= 101;
  ccfCode_ES_GetVersion         = 105;
  ccfCode_ES_SetConfig          = 110;
  ccfCode_ES_SetParameter       = 115;
  ccfCode_ES_SetOEMInfos        = 116;
  ccfCode_ES_GetDocPath         = 120;
  ccfCode_ES_SetDestination     = 130;
  ccfCode_ES_SetExpBuffer       = 160;
  ccfCode_ES_GetExpBuffer       = 170;
  ccfCode_ES_StartDoc           = 200;
  ccfCode_ES_StartStack         = 250;
  ccfCode_ES_AddTitle           = 300;
  ccfCode_ES_AddField           = 400;
  ccfCode_ES_AddTableData       = 450;
  ccfCode_ES_AddBlob            = 500;
  ccfCode_ES_AddBlobName        = 510;
  ccfCode_ES_AddBlobDocType     = 530;
  ccfCode_ES_AskBlobDelete      = 550;
  ccfCode_ES_EndDoc             = 600;
  ccfCode_ES_EndStack           = 650;
  ccfCode_ES_RollBack           = 700;
  ccfCode_ES_CallCfgDlg         = 800;
  ccfCode_ES_GetConfig          = 850;
  ccfCode_ES_Finalize           = 900;

// ----------------------------------------------------------------
const
  ccfCode_FB_Common             = 100;

// ================================================================
// Unicode Interface
// ================================================================
function ccWideExport( fCode : LongInt;
                       fData : PWideChar;
                       fSize : LongInt;
                       Msg   : PWideChar ) : LongInt;

begin
  Result := 0;
  try
    case fCode of

      // ---------------------------------
      // Initialisierung
      // ---------------------------------
      ccfCode_ES_Initialize :
      begin
      end;

      // ---------------------------------
      // Get Interface Version
      // ---------------------------------
      ccfCode_ES_GetInterfaceVersion :
      begin
        strpcopy(fData,InterfaceVersion);
      end;

      // ---------------------------------
      // Get Version
      // ---------------------------------
      ccfCode_ES_GetVersion :
      begin
        strpcopy(fData,Version);
      end;

      // ---------------------------------
      // Konfiguration übergeben
      // ---------------------------------
      ccfCode_ES_SetConfig :
      begin
      end;

      // ---------------------------------
      // Dokumentablage
      // ---------------------------------
      ccfCode_ES_GetDocPath :
      begin
      end;

      // ---------------------------------
      // Destination übergeben
      // ---------------------------------
      ccfCode_ES_SetDestination :
      begin
      end;

      // ---------------------------------
      // Dokumentstart
      // ---------------------------------
      ccfCode_ES_StartDoc :
      begin
      end;

      // ---------------------------------
      // Stapelstart
      // ---------------------------------
      ccfCode_ES_StartStack :
      begin
      end;

      // ---------------------------------
      // Titel
      // ---------------------------------
      ccfCode_ES_AddTitle :
      begin
      end;

      // ---------------------------------
      // Indizes (Feld=Wert)
      // ---------------------------------
      ccfCode_ES_AddField :
      begin
      end;

      // ---------------------------------
      // Tabellendaten (ColName,Row=Wert)
      // ---------------------------------
      ccfCode_ES_AddTableData :
      begin
      end;

      // ---------------------------------
      // Blobs (voller Pfad)
      // ---------------------------------
      ccfCode_ES_AddBlob :
      begin
      end;

      // ---------------------------------
      // Blobbezeichnung
      // ---------------------------------
      ccfCode_ES_AddBlobName :
      begin
      end;

      // ---------------------------------
      // Blob-Dokumenttyp
      // ---------------------------------
      ccfCode_ES_AddBlobDocType :
      begin
      end;

      // ---------------------------------
      // Dokumentende
      // ---------------------------------
      ccfCode_ES_EndDoc :
      begin
      end;

      // ---------------------------------
      // Stapelende
      // ---------------------------------
      ccfCode_ES_EndStack :
      begin
      end;

      // ---------------------------------
      // Stapel Rollback
      // ---------------------------------
      ccfCode_ES_RollBack :
      begin
      end;

      // ---------------------------------
      // Exportservice schliessen
      // ---------------------------------
      ccfCode_ES_Finalize :
      begin
      end;


      // ---------------------------------
      // Konfigurationsdialog öffnen
      // ---------------------------------
      ccfCode_ES_CallCfgDlg :
      begin
      end;

      // ---------------------------------
      // Konfiguration abfragen
      // ---------------------------------
      ccfCode_ES_GetConfig :
      begin
      end;

    end;
  except
    on e: exception do
    begin
      Result := -1;
      strpcopyw(msg,'Process exception (' + e.message + ')');
    end;
  end;
end;

// ================================================================
// clarc final builder Engine Test Function
// ================================================================
function ccBuildTest( fCode   : LongInt;
                      fData   : PWideChar;
                      Msg     : PWideChar ) : LongInt;
begin
  Result := -1;

  case fCode of
    // ---------------------------------
    // Common
    // ---------------------------------
    ccfCode_FB_Common:
    begin
      // Test something...
      Result := 0;
    end;
  end;
end;

// ================================================================
Exports
  ccWideExport,
  ccBuildTest;

begin
end.

Delphi Beispielprojekt

Komplettes Delphi Beispielprojekt inkl. Konfigurationsdialog und Exportfunktion. 

C++ Snippet

Pojekt.cpp

#include "stdafx.h"
#include <atlstr.h>
#include <msclr\marshal.h>
#include <msclr\marshal_cppstd.h>
#include <string>

using namespace std;
using namespace System::Diagnostics;
#pragma warning(disable: 4996) // because of wcscpy


extern "C" int  __declspec(dllexport) __stdcall ccSTDCALLSupport()
{
  return 0;
}


extern "C" int  __declspec(dllexport) __stdcall ccWideExport(long fCode, wchar_t* data, long fSize, wchar_t* pMsg)
{
  int ret = 0;
  System::String^ szCaptureValue = 
    gcnew System::String(reinterpret_cast<const wchar_t*>(data));
  
  if (fCode == 850)
  {
    msclr::interop::marshal_context c3;
    System::String^ szTempString = gcnew System::String("TestNeu");
    wcscpy(data, c3.marshal_as<const wchar_t*>(szTempString));
  }
  return 0;
}

Projekt.def

LIBRARY "ExportWrapper.dll"
EXPORTS
; Explicit exports can go here
       ccWideExport
       ccSTDCALLSupport