MailCom API für klicktel

Transkript

1 MailCom Adressentools MailCom API für klicktel Programmierer-Schnittstelle für KlickTel Server Informationen für Softwareentwickler MailCom e.k. Nur für internen Gebrauch. Die Weitergabe ist nur an beteiligte Softwareentwickler erlaubt!

2 Dokumentationshinweise: MailCom e.k. oder Laforsch Software-Studio verfügen möglicherweise über eingetragene Patente und/oder Patentanmeldungen für einzelne Themen in diesem Handbuch. Dieses Dokument verleiht Ihnen keinerlei Verfügungsrechte über diese Patente. COPYRIGHT 1998/2009. Alle Rechte vorbehalten. MailCom ist ein eingetragenes Warenzeichen von Laforsch Software-Studio. Andere aufgeführte Waren- oder Produktbezeichnungen sind Warenzeichen oder eingetragene Warenzeichen der jeweiligen Rechteinhaber. Einschränkung der Gewährleistung: Es wird keine Garantie für die Richtigkeit des Inhaltes dieses Handbuches übernommen. Da sich Fehler, trotz aller Bemühungen, nie vollständig vermeiden lassen, sind wir für Hinweise jederzeit dankbar. Dokumentiformation: Titel: MailCom API für KlickTel Server Thema: MailCom Schnittstelle (API) für KlickTel Server Zuletzt aktualisiert am: Dokumentenname:!Beschreibung MailCom-KlickTel-Schnittstelle.doc Dokumentenvorlage: GLIEDER.DOT Gesamtseitenzahl: 10 Satz & Acrobat-Bearbeitung: MailCom e.k. Herausgeber: MailCom e.k. Postfach Langen Telefon Telefax Internet: 2 MailCom Schnittstelle für klicktel Server

3 Inhaltsverzeichnis KlickTel-Server Programmierer-Schnittstelle 1 Allgemeine Beschreibung zur Schnittstelle 4 Demo-Projekt zur Schnittstelle 4 Benötigte Dateien im neuen Programm-Verzeichnis 4 Beschreibung aller Funktionen 5 dsktel_init 5 dsktel_deinit 5 dsktel_sucheunique_mit_telefon 6 dsktel_sucheunique_mit_adresse 7 Beschreibung Rückgabe-Treffer 10 Technische Dokumentation 3

4 Allgemeine Beschreibung zur Schnittstelle Mit der MailCom-Schnittstelle für den KlickTel-Server können Adressen im KlickTel- Server gesucht und zurückgegeben werden. Die Schnittstelle wurde für Entwickler erstellt, die mit Programmier-Systemen arbeiten, die kompatibel mit der Windows-API sind. Alle Funktionen dieser Schnittstelle arbeiten mit gängigen Parametern wie z.b. Nullterminierte Strings. Die Verarbeitung funktioniert nach dem folgenden Schema: 1. KlickTel-Schnittstelle initialisieren 2. Start Schleife: 3. Adresse im KlickTel-Server suchen 4. Gefundene Adresse(n) auswerten oder anzeigen 5. Ende Schleife: 6. KlickTel-Schnittstelle freigeben 7. Programm-Ende Demo-Projekt zur Schnittstelle Der Schnittstelle ist ein Demo-Projekt beigefügt, welches die Funktionsweise der Schnittstelle zeigt. Dieses Demo-Projekt ist in der Programmier-Sprache Delphi programmiert und ist so strukturiert, dass Programmierer anderer Sprachen den Quelltext ebenfalls lesen und portieren können. Die Datei DLL_Funktionen.PAS enthält alle Funktionen und kann für die Programmiersprache Delphi direkt in eigene Projekte eingebunden werden. Benötigte Dateien im neuen Programm-Verzeichnis Folgende Dateien werden von der Schnittstelle benötigt und müssen mit in das neue Programm-Verzeichnis kopiert werden: - BORLNDMM.DLL - MCADRFKT1.DLL - MCDBFKT1.DLL - MCFKT1.DLL - MC_KTEL_INTERFACE.DLL (Diese Schnittselle) 4 MailCom Schnittstelle für klicktel Server

5 Beschreibung aller Funktionen dsktel_init Diese Funktion initialisiert die Schnittstelle und muss direkt beim Start aufgerufen werden. Ohne diesen Funktionsaufruf beim Start, können die anderen Funktionen dieser Schnittstelle auch nicht aufgerufen werden. FUNCTION dsktel_init( AKlickServer_IP : PChar; AKlickServer_Port : PChar; AShowFehlermeldung : bool) : integer; stdcall; AKlickServer_IP: Nullterminierter String mit der IP-Adresse des KlickTel-Servers. z.b AKlickServer_Port: Nullterminierter String mit der Port-Adresse des KlickTel-Servers z.b AShowFehlermeldung: True oder False. Bei True werden die Fehlermeldungen angezeigt, wenn die Verbindung zum KlickTel-Server fehlgeschlagen ist. Bei False muss der Rückgabe-Wert ausgewertet werden. Rückgabe: Integer-Wert. 1 = Alles OK Negativ, dann Fehler beim Initialisieren der Schnittstelle dsktel_deinit Diese Funktion gibt die Schnittstelle wieder frei und trennt die Verbindung zum KlickTel- Server. Diese Procedure muss auf alle vor dem Programm-Ende aufgerufen werden, da sonst eine Exception ausgelöst werden könnte. PROCEDURE dsktel_deinit; stdcall; Keine Parameter erwartet Technische Dokumentation 5

6 dsktel_sucheunique_mit_telefon Diese Funktion sucht einen Teilnehmer im KlickTel-Server anhand der Telefonnummern- Rückwärtssuche. Es werden nur eindeutige Treffer zurückgegeben. Sollten mehrere Einträge mit der gleichen Telefonnummer existieren, so wird kein Treffer zurückgegeben und dies im Fehlercode beschrieben. Wenn der Teilnehmer der Telefonnummern-Rückwärts-Suche widersprochen hat, wird dieser nicht zurückgegeben und das Ergebnis 0 zurückgeliefert. FUNCTION dsktel_sucheunique_mit_telefon( ATelefonnummer : PChar; AShowManuelleMaske : integer; ARueckgabeTreffer : PChar) : integer; stdcall; ATelefonnummer: Nullterminierter String mit der zu suchenden Telefonnummer. Die Telefonnummer besteht aus Vorwahl und Rufnummer. Sonderzeichen werden ignoriert. AShowManuelleMaske: 0 = Keine manuelle Maske anzeigen 1 = Wenn mehrere mögliche Teilnehmer gefunden werden, wird eine manuelle Maske angezeigt, in der der Anwender suchen kann und einen entsprechenden Teilnehmer manuell auswählen kann. 2 = Wenn kein oder mehrere mögliche Teilnehmer gefunden werden, wird eine manuelle Maske angezeigt, in der der Anwender suchen kann und einen entsprechenden Teilnehmer manuell auswählen kann. ARueckgabeTreffer: Zeiger auf einen Buffer, der mindestens 3000 Zeichen reserviert haben sollte. In diesen Buffer wird der gefundene Treffer als Semikolongetrennter String geschrieben. Wenn kein Treffer gefunden wird, wird hier ein Leerstring zurückgegeben. (Siehe Demo-Projekt) Rückgabe: Integer-Wert. 1 = Treffer wurde gefunden 0 = kein Treffer wurde gefunden -1 = mehrere Treffer gefunden oder Anwender-Abbruch bei Maske -2 = Fehler durch KlickTel-Server -3 = Interner Fehler oder Schnittstelle wurde nicht initialisiert -4 = gefundener Teilnehmer hat der Rückwärts-Suche widersprochen 6 MailCom Schnittstelle für klicktel Server

7 dsktel_sucheunique_mit_adresse Diese Funktion sucht einen Teilnehmer im KlickTel-Server anhand der kompletten Anschrift. Sollten mehrere Einträge mit der gleichen Anschrift und den gleichen Namens- Bedingungen existieren, so wird kein Treffer zurückgegeben und dies im Fehlercode beschrieben. FUNCTION dsktel_sucheunique_mit_adresse( AName : PChar; AVorname : PChar; AStrasse : PChar; AHausnr : PChar; APLZ : PChar; AOrt : PChar; ANameGleichProzent : integer; AShowManuelleMaske : integer; ARueckgabeTreffer : PChar) : integer; stdcall; AName: AVorname: AStrasse: AHausnr: APLZ: AOrt: Nullterminierter String mit dem zu suchenden Nachnamen oder Firmennamen. Wenn der Vorname nicht gefüllt wird, wird davon ausgegangen, dass eine Firma gesucht wird. Ist der Vorname gefüllt, wird AName als Nachname behandelt. AName muss gefüllt sein, sonst wird kein Treffer gefunden. Nullterminierter String mit dem zu suchenden Vornamen. Ist AVorname gefüllt, dann wird nach einer Privat-Person gesucht, ansonsten wird nach einem Firmennamen gesucht. Nullterminierter String mit der gesuchten Strasse. Die Strasse muss ohne die Hausnummer übergeben werden. AStrasse muss gefüllt sein, sonst wird kein Treffer gefunden. Nullterminierter String mit der zu gesuchten Hausnummer. Nullterminierter String mit der gesuchten Postleitzahl. APLZ muss gefüllt sein, sonst wird kein Treffer gefunden. Nullterminierter String mit dem gesuchten Ort. AOrt muss gefüllt sein, sonst wird kein Treffer gefunden. Technische Dokumentation 7

8 ANameGleichProzent: Prozent-Wert von Dieser Prozent-Wert gibt bei unklaren Firmennamen an, bis zu welchem Prozentsatz die Firmennamen als gleich angesehen werden. (z.b. Müller GmbH P. Müller Gesellschaft mbh) AShowManuelleMaske: 0 = Keine manuelle Maske anzeigen 1 = Wenn mehrere mögliche Teilnehmer gefunden werden, wird eine manuelle Maske angezeigt, in der der Anwender suchen kann und einen entsprechenden Teilnehmer manuell auswählen kann. 2 = Wenn kein oder mehrere mögliche Teilnehmer gefunden werden, wird eine manuelle Maske angezeigt, in der der Anwender suchen kann und einen entsprechenden Teilnehmer manuell auswählen kann. ARueckgabeTreffer: Zeiger auf einen Buffer, der mindestens 3000 Zeichen reserviert haben sollte. In diesen Buffer wird der gefundene Treffer als Semikolongetrennter String geschrieben. Wenn kein Treffer gefunden wird, wird hier ein Leerstring zurückgegeben. (Siehe Demo-Projekt) Rückgabe: Integer-Wert. 1 = Treffer wurde gefunden 0 = kein Treffer wurde gefunden -1 = mehrere Treffer gefunden oder Anwender-Abbruch bei Maske -2 = Fehler durch KlickTel-Server -3 = Interner Fehler oder Schnittstelle wurde nicht initialisiert dsktel_show_manuelle_suchmakse Diese Funktion sucht einen Teilnehmer im KlickTel-Server anhand der kompletten Anschrift und anschließend wird eine Maske angezeigt, in der der Anwender einen Teilnehmer manuell nachsuchen und auswählen kann. Wenn in der manuellen Maske nach einer (abgekürzten) Telefonnummer gesucht wird, werden keine Teilnehmer zurückgegeben, die der Telefonnummern-Rückwärts-Suche widersprochen haben. FUNCTION dsktel_show_manuelle_suchmaske ( AName : PChar; AVorname : PChar; AStrasse : PChar; AHausnr : PChar; APLZ : PChar; AOrt : PChar; 8 MailCom Schnittstelle für klicktel Server

9 ARueckgabeTreffer : PChar) : integer; stdcall; AName: AVorname: AStrasse: AHausnr: APLZ: AOrt: Nullterminierter String mit dem zu suchenden Nachnamen oder Firmennamen. Wenn der Vorname nicht gefüllt wird, wird davon ausgegangen, dass eine Firma gesucht wird. Ist der Vorname gefüllt, wird AName als Nachname behandelt. AName muss gefüllt sein, sonst wird kein Treffer gefunden. Nullterminierter String mit dem zu suchenden Vornamen. Ist AVorname gefüllt, dann wird nach einer Privat-Person gesucht, ansonsten wird nach einem Firmennamen gesucht. Nullterminierter String mit der gesuchten Strasse. Die Strasse muss ohne die Hausnummer übergeben werden. AStrasse muss gefüllt sein, sonst wird kein Treffer gefunden. Nullterminierter String mit der zu gesuchten Hausnummer. Nullterminierter String mit der gesuchten Postleitzahl. APLZ muss gefüllt sein, sonst wird kein Treffer gefunden. Nullterminierter String mit dem gesuchten Ort. AOrt muss gefüllt sein, sonst wird kein Treffer gefunden. ARueckgabeTreffer: Zeiger auf einen Buffer, der mindestens 3000 Zeichen reserviert haben sollte. In diesen Buffer wird der gefundene Treffer als Semikolongetrennter String geschrieben. Wenn kein Treffer gefunden wird, wird hier ein Leerstring zurückgegeben. (Siehe Demo-Projekt) Rückgabe: Integer-Wert. 1 = Treffer wurde gefunden 0 = kein Treffer wurde gefunden -1 = mehrere Treffer gefunden oder Anwender-Abbruch bei Maske -2 = Fehler durch KlickTel-Server -3 = Interner Fehler oder Schnittstelle wurde nicht initialisiert Technische Dokumentation 9

10 dsktel_maximaleanzahlsuchmaske Diese Prozedur setzt die Anzahl der Teilnehmer, die gleichzeitig auf der manuellen Suchmaske angezeigt werden sollen. Bedenken Sie, dass es einige Momente dauern kann, bis das Fenster bei größeren Treffermengen aufgebaut wird. FUNCTION dsktel_maximaleanzahlsuchmaske ( AMaxAnzahl : integer); stdcall; AMaxAnzahl: Integer mit maximal anzuzeigender Teilnehmer auf der manuellen Suchmaske. 500 ist die Vorgabe Beschreibung Rückgabe-Treffer In den Buffer ARueckgabeTreffer wird der aktuelle Treffer als Semikolon-getrennter String geschrieben. Der String setzt sich folgendermaßen zusammen: 1. Nachname bzw. Firmenname 2. Vorname 3. Titel 4. Strasse 5. Hausnummer 6. Postleitzahl 7. Ort 8. Telefon 1 9. Telefon Telefax 11. Zusatz Zusatz Branche 14. Referenz-Nummer 10 MailCom Schnittstelle für klicktel Server