Allgemein
CibPrJobHandle
CibPrJobCreate
CibPrJobFree
CibPrPrint
CibPrLoad
CibPrSave
CibMailSend
CibPrGetProperty
CibPrSetProperty
CibPrGetLastError
CibPrGetLastErrorText
CibPrGetVersion
CibPrGetVersionText
CibPrJobPrint
CibPrJobLoad
CibPrJobSave
CibPrJobConvert
CibPrJobMailSend
CibPrJobGetProperty
CibPrJobSetProperty
CibPrJobGetError
CibPrJobGetLastErrorText
CibPrShowPrintDialog
CibPrShowPrintSetupDialog
CibPrShowPageSetupDialog
MemoryOutputCallback

Allgemein

Dieses Kapitel gibt einen kurzen Überblick über die verfügbare API und derer Parameter. Allgemein gilt, daß man über die Funktion CibPrSetProperty seine gewünschten Parameter in CIB format/output setzt und dann eine Funktion CibPrPrint oder CibPrLoad/CibPrSave aufrufen.

CibPrJobHandle

typedef struct tagCibPrJobHandleStruct

{
            /* no data */
} CibPrJobHandleStruct;
typedef CibPrJobHandleStruct* CibPrJobHandle;

Das neue, ab der CIB format Version 5.2.94 verfügbare "Jobinterface", ordnet jedem Druck- oder Konvertierungsauftrag der durchgeführt werden soll ein "Auftragshandle" vom Typ CibPrJobHandle zu. Dieses Objekt dient als Stellvertreterobjekt des Auftrags. Sowohl das

• Setzen und Lesen von Properties (mit CibPrSetJobProperty/CibPrGetJobProperty) als auch das
• Ausführen des Auftrags (mit CibPrJobPrint, CibPrJobLoad, CibPrJobSave) sowie das
• Abholen von Fehlerinformationen (mit CibPrJobGetError, CibPrJobGetErrorText)

beziehen sich bei diesen Routinen stets auf ein solches Jobhandle.

Man eröffnet einen Auftrag, indem man ein Jobhandle (mit CibPrJobCreate) erzeugt. Nach dem Setzen der Properties und dem Ausführen der Konvertierung gibt man das Jobhandle wieder frei (mit CibPrJobFree).

CibPrJobCreate

BOOL EXPORTFUNC CibPrJobCreate (CibPrJobHandle*a_pJob, const char* a_pReserved);

Mit dieser Methode wird ein JobHandle erzeugt, welches dann mit Hilfe von CibPrJobFree wieder freigegeben wird.

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

Parameter:

Typ:	Variable:	Bedeutung:
CibPrJobHandle	*a_pJob	Handle des auszuführenden Auftrags
char*	a_pReserved

CibPrJobFree

BOOL EXPORTFUNC CibPrJobFree (CibPrJobHandle*a_pJob);

Mit dieser Methode wird ein, mit Hilfe von CibPrJobCreate erzeugtes, JobHandle wieder freigegeben.

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

Parameter:

Typ:	Variable:	Bedeutung:
CibPrJobHandle	*a_pJob	Handle des auszuführenden Auftrags

CibPrPrint

BOOL EXPORTFUNC CibPrPrint(void);

Mit dieser Methode wird ein Druckvorgang gestartet. Wobei mit der Funktion CibPrSetProperty vorher mindestens die Eigenschaften InputFilename gesetzt worden sein muss.

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrLoad

BOOL EXPORTFUNC CibPrLoad(void);

Mit dieser Methode wird eine Eingabedatei in die interne Dokumentstruktur der CIB format/output DLL umgesetzt.

Mit der Funktion CibPrSetProperty muss vorher mindestens die Eigenschaft COMOD_PROP_INPUT_FILENAME gesetzt worden sein. 

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrSave

BOOL EXPORTFUNC CibPrSave(void);

Mit dieser Methode wird eine Ausgabedatei in einem vorzugebenden Format erzeugt.

Mit der Funktion CibPrSetProperty müssen vorher mindestens die Eigenschaften COMOD_PROP_INPUT_FILENAME, COMOD_PROP_OUTPUT_FILENAME und COMOD_PROP_OUTPUT_FORMAT gesetzt worden sein.

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibMailSend

BOOL EXPORTFUNC CibMailSend ();

Mit dieser Funktion wird versucht eine MAPI-Session aufzubauen. Als E-Mail-Programm wird der auf dem System eingerichtete Standard-Email-Client verwendet. Es ist möglich, sowohl E-Mails dialoggeführt zu versenden, als auch im Batchbetrieb.

Zu den MAPI-fähigen Email-Clients gehören Outlook, Outlook Express, Netscape Messenger etc.

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrGetProperty

BOOL EXPORTFUNC CibPrGetProperty(const char* a_pOptionName, void* a_pOptionValue, long a_lBufferLength);

Mit dieser Funktion können die aktuell gesetzten Eigenschaften der CIB format/output Komponente abgefragt werden.

Parameter:

Typ	Variable	Bedeutung
Char*	a_pOptionName	Name des gewünschten Konfigurationsparameters
Void*	a_pOptionValue	Wert des gewünschten Konfigurationsparameters
Long	a_lBufferLength	Länge des Puffers für den Optionsinhalt

Die Funktion liefert TRUE zurück, wenn kein Fehler aufgetreten ist und sonst FALSE.

CibPrSetProperty

BOOL EXPORTFUNC CibPrSetProperty(const char* a_pOptionName, void* a_pOptionValue);

Mit dieser Funktion werden zusätzliche Eigenschaften für den Druck gesetzt.

Für eine ASCII-Konvertierung müssen vorher mindestens die Eigenschaften InputFilename und OutputFilename gesetzt worden sein.

Für eine normale Druckausgabe muss vorher mindestens die Eigenschaft InputFilename gesetzt worden sein.

CibPrGetLastError

BOOL EXPORTFUNC CibPrGetLastError(int *a_iError);

Mit dieser Funktion kann der aktuelle Fehlerstatus der CIB format/output Komponente nach dem Ausführen verschiedener Funktionen abgefragt werden.

Parameter:

Typ	Variable	Bedeutung
int *	a_iError	Platzhalter für die aktuelle Fehlernummer

Ein Fehlercode größer 0 bedeutet, daß ein Problem aufgetreten ist und der Druckauftrag nicht ordentlich zu Ende geführt wurde. Ein Fehlercode kleiner 0 bedeutet, daß der Benutzer den Druckauftrag bewußt abgebrochen hat.

Die Funktion liefert TRUE wenn kein Fehler beim Ausführen dieser Funktion aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrGetLastErrorText

BOOL EXPORTFUNC CibPrGetLastErrorText(char *a_pTextBuffer, long a_lBufferLength);

Mit dieser Funktion kann der aktuelle Fehlertext der CIB format/output Komponente nach dem Ausführen einer Funktion abgefragt werden.

Parameter:

Typ	Variable	Bedeutung
char*	a_pTextBuffer	Textpuffer für den Fehlertext
long	a_lBufferLength	Länge des verfügbaren Textpuffers

Die Funktion liefert TRUE wenn kein Fehler beim Abholen des Fehlertextes aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrGetVersion

BOOL EXPORTFUNC CibPrGetVersion(unsigned long &a_lVersion)

Die Funktion liefert die aktuelle Versionsnummer der CIB format/output Komponente zurück. Damit können Sie in Ihrer Applikation sicherstellen, daß eine Mindestversion vorliegt, wenn Sie etwa spezielle Programmeigenschaften benutzen, die erst ab einem bestimmten Release zur Verfügung gestellt wurden.

Parameter:

Maßgeblich für die Parameterübergabe ist das mitgelieferte Headerfile cibprt.h

Typ	Variable	Bedeutung
unsigned long &	a_lVersion	a_lVersion liefert die aktuelle Versionsnummer der CIB format/output Komponente zurück. Der unsigned long-Wert liefert die Information in zwei Bereichen. Die ersten zwei Bytes enthalten den Versionszähler des Hauptreleases. Die Bytes 3 und 4 enthalten den zugehörigen aktuellen Releasezähler. Je nach Programmiersprache sind die Hi- und Lowbereiche entsprechend zu beachten (siehe Codebeispiele unten).

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

C++ - Code-Beispiel:

unsigned long a_lVersion;
int          loWordVersion;
int          hiWordVersion;

CibPrGetVersion( &a_lVersion);                     // aktuelle Versionsnummer der CIB format/output Komponente
loWordVersion  = LOWORD(a_lVersion);              // Versionszähler des Hauptreleases
hiWordVersion  = HIWORD(a_lVersion);              // aktuelle Releasezähler

CibPrGetVersionText

BOOL EXPORTFUNC CibPrGetVersionText(char* a_pText, size_t a_MaxLength)

Die Funktion liefert die aktuelle Versionsnummer der CIB format/output Komponente als Text zurück. Diese kann in Programmoberflächen ausgegeben werden.

Parameter:

Typ	Variable	Bedeutung
char*	a_pText
size_t	a_MaxLength

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobPrint

BOOL EXPORTFUNC CibPrJobPrint(CibPrJobHandle a_hJob);

Mit dieser Methode wird ein Druckvorgang gestartet.

Mit der Funktion CibPrSetProperty muss vorher mindestens die Eigenschaften InputFilename gesetzt worden sein. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobLoad

BOOL EXPORTFUNC CibPrJobLoad(CibPrJobHandle a_hJob);

Mit dieser Methode wird eine Eingabedatei in die interne Dokumentstruktur der CIB format/output DLL umgesetzt. Mit der Funktion CibPrJobSetProperty muss vorher mindestens die Eigenschaft COMOD_PROP_INPUT_FILENAME gesetzt worden sein. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobSave

BOOL EXPORTFUNC CibPrJobSave(CibPrJobHandle a_hJob);

Mit dieser Methode wird eine Ausgabedatei in einem vorzugebenden Format erzeugt. Mit der Funktion CibPrJobSetProperty müssen vorher mindestens die Eigenschaften COMOD_PROP_INPUT_FILENAME, COMOD_PROP_OUTPUT_FILENAME und COMOD_PROP_OUTPUT_FORMAT gesetzt worden sein. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobConvert

BOOL EXPORTFUNC CibPrJobConvert(CibPrJobHandle a_hJob);

Mit dieser Methode wird CibPrJobLoad und CibPrJobSave nacheinander aufgerufen, so daß eine Konvertierung mit einem einzigen Aufruf durchgeführt wird. Weiterhin findet dies in einer Schleife statt, wenn die Eingabedatei eine Multi-RTF-Datei ist, so daß alle in der Eingabedatei enthaltenen Einzeldokumente mit einem einzigen Aufruf konvertiert werden. Je nach Einstellung der Property COMOD_PROP_MULTIRTF_SINGLEOUTPUT entstehen dabei mehrere oder eine einzige Ausgabedatei. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobMailSend

BOOL EXPORTFUNC CibPrJobMailSend (CibPrJobHandle a_hJob);

Mit dieser Funktion wird versucht eine MAPI-Session aufzubauen. Als E-Mail-Programm wird der auf dem System eingerichtete Standard-E-Mail-Client verwendet. Es ist möglich, sowohl E-Mails dialoggeführt zu versenden, als auch im Batchbetrieb. Zu den MAPI-fähigen E-Mail-Clients gehören Outlook, Outlook Express, Netscape Messenger etc. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobGetProperty

BOOL EXPORTFUNC CibPrJobGetProperty (CibPrJobHandle a_hJob, const char* a_pName, void*a_pValue, size_t a_MaxLength);

Mit dieser Funktion können die aktuell gesetzten Eigenschaften der CIB format/output Komponente abgefragt werden.

Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)
Char*	a_pOptionName	Name des gewünschten Konfigurationsparameters
Void*	a_pOptionValue	Wert des gewünschten Konfigurationsparameters
Long	a_lBufferLength	Länge des Puffers für den Optionsinhalt

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobSetProperty

BOOL EXPORTFUNC CibPrJobSetProperty (CibPrJobHandle a_hJob, const char* a_pName, void*a_pValue, size_t a_Length);

Mit dieser Funktion werden zusätzliche Eigenschaften für den Druck gesetzt. Für eine ASCII-Konvertierung müssen vorher mindestens die Eigenschaften InputFilename und OutputFilename gesetzt worden sein. Für eine normale Druckausgabe muss vorher mindestens die Eigenschaft InputFilename gesetzt worden sein.

Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags (siehe CibPrJobHandle)
char*	a_pOptionName	Name des gewünschten Konfigurationsparameters
void*	a_pOptionValue	Wert des gewünschten Konfigurationsparameters Achtung: Beachten Sie den jeweiligen Datentyp des jeweiligen Wertes
size_t	a_Length

Die Funktion liefert TRUE wenn kein Fehler aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobGetError

BOOL EXPORTFUNC CibPrJobGetError (CibPrJobHandle a_hJob, int*a_pErrorCode);

Mit dieser Funktion kann der aktuelle Fehlerstatus der CIB format/output Komponente nach dem Ausführen verschiedener Funktionen abgefragt werden. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
long	a_hJob	Handle des auszuführenden Auftrags
int *	a_iError	Platzhalter für die aktuelle Fehlernummer

Die Funktion liefert TRUE wenn kein Fehler beim Ausführen dieser Funktion aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrJobGetLastErrorText

BOOL EXPORTFUNC CibPrJobGetLastErrorText(CibPrJobHandle a_hJob, char* a_pText, size_t a_MaxLength);

Mit dieser Funktion kann der aktuelle Fehlertext zu einem Auftrag nach dem Ausführen einer Funktion abgefragt werden. Das JobHandle muss mit CibPrJobCreate erzeugt werden, und mit CibPrJobFree wieder freigegeben werden.

Parameter:

Typ	Variable	Bedeutung
CibPrJobHandle	a_hJob	Handle des auszuführenden Auftrags
char*	a_pTextBuffer	Textpuffer für den Fehlertext
long	a_lBufferLength	Länge des verfügbaren Textpuffers

Die Funktion liefert TRUE wenn kein Fehler beim Abholen des Fehlertextes aufgetreten ist. Ansonsten wird FALSE zurückgegeben.

CibPrShowPrintDialog

BOOL EXPORTFUNC CibPrShowPrintDialog(int *a_iButtonID);

Unter Windows startet diese Funktion mit dem Standard Seitenauswahl-/Druckertreiberdialog vom Betriebssystem. Hierüber können entsprechende Druckerkonfigurationen und Seitenauswahlen getroffen werden, die beim anschließenden Drucken berücksichtigt werden. Diese Funktion ist für Anwendungen interessant, die den Druck immer mit einem Benutzerdialog ausführen wollen.

Parameter:

Typ	Variable	Bedeutung
int*	a_iButtonId	Rückgabe der ButtonId die innerhalb der Druckauswahl gedrückt wurde. 1 (COMOD_ID_OK)       OK-Button (=> es sollte von Ihnen CibPrPrint im Anschluß aufgerufen werden) 3 (COMOD_ID_CLOSE) Schließen-Button (=> der Anwender hat den Drucker gewechselt möchte aber nicht sofort drucken) 2 (CIB_ID_CANCEL)      Abbrechen-Button

Die Funktion liefert TRUE zurück wenn kein Fehler aufgetreten ist.

CibPrShowPrintSetupDialog

BOOL EXPORTFUNC CibPrShowPrintSetupDialog(int *a_iButtonID);

Unter Windows startet diese Funktion mit dem Druckereigenschaftendialog des jeweiligen Treiberherstellers des gerade aktivierten Druckers. Hierüber können entsprechende Druckerkonfigurationen getroffen werden, die beim anschließenden Drucken berücksichtigt werden. Diese Funktion ist für Anwendungen interessant, die den Druck immer mit einem Benutzerdialog ausführen wollen.

Parameter:

Typ	Variable	Bedeutung
int*	a_iButtonId	Rückgabe der ButtonId die innerhalb der Druckauswahl gedrückt wurde. 1 (COMOD_ID_OK)       OK-Button (=> es sollte von Ihnen CibPrPrint im Anschluß aufgerufen werden) 3 (COMOD_ID_CLOSE) Schließen-Button (=> der Anwender hat den Drucker gewechselt möchte aber nicht sofort drucken) 2 (CIB_ID_CANCEL)      Abbrechen-Button

Die Funktion liefert TRUE zurück wenn kein Fehler aufgetreten ist.

CibPrShowPageSetupDialog

BOOL EXPORTFUNC CibPrShowPageSetupDialog(int *a_iButtonID);

Unter Windows startet diese Funktion mit dem Standard Druckertreiberdialog vom Betriebssystem. Hierüber können entsprechende Druckerkonfigurationen getroffen werden, die beim anschließenden Drucken berücksichtigt werden. Diese Funktion ist für Anwendungen interessant, die den Druck immer mit einem Benutzerdialog ausführen wollen.

Parameter:

Typ	Variable	Bedeutung
int*	a_iButtonId	Rückgabe der ButtonId die innerhalb der Druckauswahl gedrückt wurde. 1 (COMOD_ID_OK)       OK-Button (=> es sollte von Ihnen CibPrPrint im Anschluß aufgerufen werden) 3 (COMOD_ID_CLOSE) Schließen-Button (=> der Anwender hat den Drucker gewechselt möchte aber nicht sofort drucken) 2 (CIB_ID_CANCEL)      Abbrechen-Button

Die Funktion liefert TRUE zurück wenn kein Fehler aufgetreten ist.

MemoryOutputCallback

Diese Schnittestelle gilt auch für “AnalysisOutputCallback“.

COMOD_CALLBACK_TYPE(COMOD_BOOL, MemoryOutputCallbackType) (const char* a_TextOutput, size_t a_Length, void*a_pUserdata, int a_Error)

Callback-Prototyp für Daten-Ausgabe im Speicher.

Parameter:

Typ	Variable	Bedeutung
char*	a_TextOutput	Die Daten, die über die Callbackfunktion übergeben werden.
size_t	a_Length	Die Byte-Anzahl der Daten.
void*	a_pUserdata	Zeiger auf beliebige Nutzerdaten. Konkreter Typ hängt von der Implementierung der Callbackfunktion ab.
Int*	a_Error	Fehlercode, der vom Aufrufer an die Callbackfunktion übergeben wird.

Die Funktion liefert FALSE zurück wenn Fehler aufgetreten ist.