TIGA API Version 2.5

Dokument: Version 2.5 Stand: 15. Mai 1999

TIGA API

i

TIGA API

ii

Version 2.5

Inhaltsverzeichnis

Inhaltsverzeichnis Kapitel 1

Einführung Allgemeine Hinweise. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Glossar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Kapitel 2

Fragen und Antworten Allgemein . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Datenbank. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Programmierung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Kapitel 3

Funktionsbeschreibung Strategien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Der billigste Anbieter (in einem Zeitraum) . . . . . . . . . . . . Vis-a-Vis-Tarife . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programmierung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Übersicht. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Funktionsbeschreibung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Strategien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vis-a-Vis-Tarife . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programmierung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Kapitel 4

Programmierung Verbindungsaufbau. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Konstanten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typen und Strukturen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TCountryRec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TProviderRec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TModelRec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TZoneRec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TCostRec (intern !!!) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Funktionen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initialisierung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgDone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Verbindungsaufbau. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgConnectToLocalServer . . . . . . . . . . . . . . . . . . . . tgConnectToNTServer . . . . . . . . . . . . . . . . . . . . . . tgConnectToNovellServer . . . . . . . . . . . . . . . . . . . tgConnectViaIP . . . . . . . . . . . . . . . . . . . . . . . . . . . tgDisconnectFromServer . . . . . . . . . . . . . . . . . . . . Abfragen und Einstellungen. . . . . . . . . . . . . . . . . . . . . . . tgSetCountry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetCountry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgSetLocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgSetPreselect . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgSetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Datenbankinhalt ermitteln . . . . . . . . . . . . . . . . . . . . . . . . . tgGetProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgProviderFindFirst . . . . . . . . . . . . . . . . . . . . . . . . tgProviderFindNext . . . . . . . . . . . . . . . . . . . . . . . . tgSetProviderFilter . . . . . . . . . . . . . . . . . . . . . . . . .

TIGA API

13 13 13 13 13 14 14 14 14

15 15 15 15 17 18 19 20 21 21 22 23 23 24 25 26 27 28 28 29 30 31 32 33 33 34 35 36 37

iii

TIGA API

tgGetModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgModelFindFirst . . . . . . . . . . . . . . . . . . . . . . . . . . tgModelFindNext . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetProviderFromModelID . . . . . . . . . . . . . . . . . . tgGetZone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetTakt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validierungsfunktionen . . . . . . . . . . . . . . . . . . . . . . . . . . . tgIsValidPhoneNumber . . . . . . . . . . . . . . . . . . . . . tgIsValidLocation . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetCityName . . . . . . . . . . . . . . . . . . . . . . . . . . . Kostenermittlung. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetCheapest . . . . . . . . . . . . . . . . . . . . . . . . . . . tgGetCheapestinPeriod . . . . . . . . . . . . . . . . . . . . . tgClearCheapestPool . . . . . . . . . . . . . . . . . . . . . . tgSetCheapestPool . . . . . . . . . . . . . . . . . . . . . . . .

Kapitel 5

Anhang Kontakt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formulare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIGA Fehler Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Firmenname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bestellung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

iv

38 39 40 41 42 43 43 44 45 46 46 47 48 49 51 52

53 53 53 53 54

Version 2.5

Inhaltsverzeichnis

TIGA API

v

Version 2.5

6

Einführung

KAPITEL 1

Einführung

1.1 Allgemeine Hinweise ...

1.2 Glossar Die hier aufgeführten Begriffe sind nicht genormt und werden in diesem Text mit den folgenden Definitionen belegt. Es ist möglich, daß einige Begriffe von Dritten mit einer anderen Bedeutung verwendet werden und deshalb unterschiedlich definiert sind.

Anbieter

Eine Firma, die alternativ zur Deutschen Telekom AG (DTAG) (Telefon-)Verbindungen anbietet.

Anmelden

Um die unterschiedlichen Anbieter alle nutzen zu können, müssen Sie sich bei einigen vorher anmelden. Erst nach erfolgter Anmeldung steht Ihnen dieser Anbieter zur Verfügung.

Call-by-Call (CC) Bei jedem Anruf wird immer wieder neu entschieden, über welchen Anbieter die Verbindung abgewickelt wird. Direktwahlverfahren

Der Anrufer kann den gewünschten Zielort direkt über eine Ziffernfolge erreichen, ohne den Service eines Operators in Anspruch zu nehmen. Die meisten Anrufe werden im Direktwahlverfahren durchgeführt.

Echtes Call-byCall (eCC)

Wie Call-by-Call, jedoch muß man sich zur Nutzung des Anbieters nicht vorher anmelden.

Gespräch

siehe Verbindung

Gesprächskosten

siehe Kosten

Kosten

Der Betrag der für eine Verbindung mit einer bestimmten Dauer zu entrichten ist.

Modell

Die meisten Anbieter haben unterschiedliche Modelle im Angebot, um individuell auf Anforderungen der Kunden zu reagieren, z.B. ein Privat- oder ein BusinessModell. Die Aufteilung in Modelle ist bei jedem Anbieter unterschiedlich, die Telekom z.B. bietet die Modelle T-Net (der analoge Zugang) T-ISDN (der digitale Zugang) und T-Online (Internetzugang) an.

Netzkennzahl (NKZ)

Die Nummer, die zur Auswahl eines Anbieters vor die Telefonnummer gestellt werden muß. In Deutschland ist das eine fünf, oder sechsstellige Zahl die mit 010xx beginnt. Um einen speziellen Anbieter zu nutzen, wählt man dessen NKZ, dann Vorwahl und Rufnummern, z.B. 01070 089 123456

Version 2.5

7

Preise

Die Gebühren, die für ein bestimmte Verbindung anfallen. Damit sind nicht die Kosten für ein Gespräch gemeint, sondern die Preisangaben der Anbieter für eine Einheit oder eine Minute.

Preselection

Alle Verbindungen werden über einen vorher festgelegten Anbieter geführt, ohne daß der Rufnummer eine NKZ vorangestellt werden muß. In den meisten Fällen ist es möglich, auch noch andere Anbieter zu nutzen.

Provider

siehe Anbieter

Tarifmodell

siehe Modell

Tarifzone

siehe Zonen

TIGA

TarifInformation und GebührenAuswertung, Akronym für die verschiedenen Produkte, die basierend auf der Tarifdatenbank entwickelt wurden.

TIGA Tarifa

Eine Anwendung für Windows 95/98 und NT, die den jeweils günstigsten Anbieter für eine Verbindung ermittelt.

TIGA Tarifservera

Eine Anwendung, die zentral von einem Server, die TIGA Tarifdatenbank den TIGA Clients bereitstellt.

TIGA Tarifdaten- Datenbank mit allen Anbietern und Tarifmodellen für ein Land. Für die verschiedebank nen Länder gibt es jeweils unterschiedliche Tarifdatenbanken. TIGA Controllera Eine Anwendung, die mit dem TIGA API entwickelt wurde, Programm zur hausinternen Telefonabrechnung TIGA Proofera

Vergleicht Telefonrechnung mit den Preislisten des Anbieters.

TIGA API

Application Programming Interface für die TIGA Tarifdatenbank und den TIGA Tarifserver. Diese Programmierschnittstelle ermöglicht es Dritten, die Tarifdatenbank in ihre Anwendung zu integrieren.

Verbindung

Damit ist allgemein eine Telefonverbindung gemeint, diese kann beispielsweise für eine Telefonat, ein Fax oder die Datenübertragung genutzt werden

Zonen

Jede Zonenklasse unterteilt sich wiederum in einzelne Zonen. Diese Unterteilung ist je nach Anbieter unterschiedlich. Bei der Telekom wird die Zonenklasse „Inland“ z.B. in die Zonen „CityCall“, „RegioCall“ und „GermanCall“ unterteilt. Die Datenbank führt die Zonen des jeweiligen Anbieters auf.

Zonenklassen

Sämtliche Telefonnummern werden in einzelne Zonenklassen zugeordnet. Die Rufnummern werden dazu in die Zonenklassen Inland, Mobilfunk, Ausland, Sonder, Inmarsat, Auskunft und Internet eingeteilt.

a. Alle TIGA Anwendungen basieren auf dem TIGA API und greifen darüber auf die TIGA Tarifdatenbank zu.

Version 2.5

8

Fragen und Antworten

KAPITEL 2

Fragen und Antworten

2.1 Allgemein Was ist das TIGA API? Das TIGA API ist eine Programmbibliothek, die den Zugriff auf die TIGA Tarifdatenbank ermöglicht. Zusätzlich enthält es verschiedene Funktionen zur Berechnung von Telefonkosten. TIGA kann als Einzelplatzsystem (LocalServer) genutzt werden oder als Client-Server-System (RemoteServer). . Die Tarifdatenbank wird also entweder auf jedem einzelnen PC oder zentral auf dem Server gespeichert. Wie kann man TIGA API nutzen? Die Funktionalität des TIGA API wurde in eine 32Bit-DLL verpackt. Damit steht die TIGA Tarifdatenbank allen Anwendungen zur Verfügung, die auf eine 32Bit-DLL zugreifen können. Um das TIGA API möglichst komfortabel in ihre Entwicklungsumgebung zu integrieren, haben wir spezielle Programmiersprachenmodule entwickelt (Wrapper), z.B. für Borland Delphi, Microsoft Visual C++ und Microsoft Visual Basic. Welche Betriebssysteme werden vom TIGA API unterstützt? Das TIGA API ermöglicht den Zugriff auf die TIGA Datenbank über eine 32Bit-DLL. ClientAnwendungen, die auf die DLL zugreifen wollen, müssen unter Windows 95 / Windows 98 oder NT 4.0 oder höher laufen. Die TIGA Engine selbst kann auf einem Win9x PC, einem Windows NT Server oder einem Novell 3.12 Server (oder höher) installiert werden. Was benötigt man, um mit dem TIGA API zu arbeiten? Sie müssen das TIGA API als LocalServer oder RemoteServer erwerben. Dies enthält die Wrapper für alle momentan entwickelten Programmiersprachen und die Tarifdatenbanken für zwei Länder. Damit können Sie bereits anfangen eigene Anwendungen zu entwickeln. Für den späteren Einsatz sollten sind die Tarifdatenbanken abonnieren um immer die aktuellen Tarifdaten zu besitzen. In welcher Form wird das Update der Tarifdatenbank angeboten? Prinzipiell gibt es zwei Formen. Die Einzellizenz, die für jede Anwendung erworben werden muß, oder die Lizenzierung, die Ihnen das Recht gibt, die Datenbank an ihre Kunden weiterzugeben. Das Update der Tarifdatenbank erscheint 14tägig und kann über den Postweg oder Email bezogen werden. Wieviel Speicherplatz wird für Client und Server benötigt? Der Client benötigt nur die TIGA-DLL, die etwa 350kB groß ist. Auf dem Server muß zusätzlich die Datenbank vorgehalten werden. Pro Land sind ca. 2MB zu veranschlagen. Sind mit dem TIGA API entwickelte Anwendungen auch von CD-ROM lauffähig? Ja, bei Verwendung der lokalen Datenbank lassen sich die Anwendungen auch von einer CDROM aus starten. Kann man Tariftabellen oder Webseiten mit dem TIGA API erzeugen? Das TIGA API stellt keine direkten Funktionen zum Drucken einer Preisübersicht oder zum Generieren von HTML-Seiten bereit, aber alle Informationen die für diese Anwendungen benötigt werden, stehen Ihnen zur Verfügung. Es gibt zwei einfache Beispiele, mit denen man eine Preisliste oder eine HTML-Seite erzeugen kann.

Version 2.5

9

TIGA API

2.2 Datenbank Für welche Länder sind TIGA Tarifdatenbanken vorhanden? Momentan für die Länder: Deutschland, Schweiz (mit Liechtenstein) und Österreich. Weitere europäische Länder (Frankreich, Italien und England) sind in Planung. Kann man selbst weitere Anbieter der Datenbank hinzufügen? Die Daten der Datenbank liegen in einem speziell dafür entwickelten komprimierten Format vor, das kein nachträgliches Hinzufügen der Daten erlaubt. Wenn Sie einen von uns nicht aufgeführten Anbieter benötigen, setzten sie sich mit uns in Verbindung, in der meisten Fällen können wir den gewünschten Anbieter in unsere Datenbank aufnehmen. Welche Preisinformationen sind in der Datenbank enthalten? Die aktuelle Datenbank enthält immer die momentan gültigen Preise, und - soweit bekannt zukünftige Preisänderungen. Alte Preise, die keine Gültigkeit mehr haben, werden aus der Datenbank entfernt. Es ist also nicht möglich, Preise für einen Zeitraum zu berechnen, wenn bereits eine Preisänderung stattgefunden hat. Falls Sie trotzdem auch auf historische Preise zurückgreifen wollen, z.B. um nachträglich Telefonabrechnungen zu erstellen, bieten wir Ihnen eine erweiterte TIGA Tarifdatenbank mit allen historischen Preise seit Anfang 1998. Entsprechen die Kosten für ein Gespräch von A nach B immer exakt den Kosten von B nach A? Obwohl man das normalerweise erwarten dürfte, ist dies nicht der Fall. Im Inlandsbereich ist die Tarifdatenbank nicht symmetrisch, was in den Entfernungszonen der DTAG begründet liegt. Bei Auslandsgesprächen kommen die Gebührenstrukturen der einzelnen Länder zu Zuge und die sind fast immer unterschiedlich. In der TIGA Tarifdatenbank sind alle diese Unterschiede gespeichert. Kann man mit dem TIGA Tarifdatenbank auch Verbindungen vom Handy berechnen Die TIGA Tarifdatenbank enthält momentan nur Informationen über Verbindungen vom Festnetz zu einem beliebigen Teilnehmer (Inland, Ausland, Mobilfunk, Sondernummern).

2.3 Programmierung Wie bekommt man den schnellsten Einstieg in die Programmierung des TIGA API? Schauen Sie sich die Beispielprogramme an und experimentieren Sie damit. Erweitern Sie die Programme nach Ihren Vorstellungen. Die meisten Probleme lassen sich mit ein paar Funktionen lösen. Wie kann man den günstigsten Anbieter ermitteln? Es gibt mehrere Möglichkeiten. Zuerst sollten Sie klären, welche Anbieter bei der Ermittlung berücksichtigt werden. Sie können dann den Anbieter „von Hand“ ermitteln, indem Sie für alle in Frage kommenden Anbieter die Funktion GetCost aufrufen um so den günstigsten zu ermitteln. Die zweite Möglichkeit besteht darin, die Funktion GetCheapest zu nutzen, die Ihnen aus einer konfigurierbaren Menge direkt den günstigsten Anbieter liefert. Über die Funktion tgSetCheapestPool / tgClearCheapestPool können Sie festlegen, welche Anbieter bei der Ermittlung berücksichtigt werden. In der Voreinstellung sind alle Anbieter enthalten, die echtes Call by Call bundesweit bieten. Die Beispielprogramme lassen sich nicht übersetzten oder es entstehen Fehlermeldungen beim kompilieren Prüfen Sie zuerst, ob Sie die empfohlenen Einstellungen in ihrer Entwicklungsumgebung eingestellt haben. Versuchen Sie danach, die Beispielprogramme zu übersetzen. Lassen die sich übersetzen und funktionieren korrekt, dann liegt der Fehler möglicherweise in Ihrem weiteren Programm-Code. Sollten die Beispielprogramme trotz der richtigen Einstellungen nicht funktionieren, dann schicken Sie uns eine Email mit Fehlerbeschreibung und/oder einem kleinen Beispielprogramm. Laufzeitfehler bei der Initialisierung der Bibliothek Sie sollten Ihre Anwendung zuerst mit der lokalen Datenbank testen (ConnectToLocalServer). Dabei ist darauf zu achten, daß die Datenbank (txx_ztvv.dat und txx_ptvv.dat, mit xx = Ländercode DE, CH, AT und vv=Version 23, 24, usw.) im entsprechenden Verzeichnis zur Verfügung steht und daß die TIGA API-DLL im aktuellen oder einem Suchpfad (z.B.: c:\windows) zu finden ist.

10

Version 2.5

Fragen und Antworten

Was ist bei der Entwicklung mit dem Tarifserver zu beachten? Sie brauchen die Entwicklung zwischen lokaler und Remote-Datenbank nicht zu unterscheiden. Eine Änderung im Verbindungsaufbau (tgConnectTo...) genügt, und Sie arbeiten mit der lokalen Datenbank oder dem zentralen Tarifserver. Sie sollten jedoch bedenken, daß Sie sich bei Nutzung der Remote-Datenbank die TIGA Funktionalität mit anderen Benutzern teilen.

Version 2.5

11

Version 2.5

12

Funktionsbeschreibung

KAPITEL 3

Funktionsbeschreibung

3.1 Strategien Provider können entweder nach und nach oder blockweise (die ersten fünf) abgefragt werden. Erhalten Sie die Meldung „Verbindung besetzt" sollten sie nicht sofort zum nächsten Anbieter wechseln. Wiederholen Sie Ihren Versuch! In der Regel erhalten Sie schnell eine Verbindung. Es ist sinnvoll, sich bei den Anbietern anzumelden, die eine kostenlose Anmeldung anbieten. Die meisten Anbieter geben nämlich in stark genutzten Zeiten den angemeldeten Kunden Vorrang vor den unangemeldeten Nutzern.

3.1.1 Der billigste Anbieter (in einem Zeitraum) Oft wird die Frage nach dem billigsten Anbieter gestellt. Dabei kann man zwei Fälle unterscheiden. · Synchroner Dienst: Zum Telefonieren ist man an dem günstigsten Anbieter zum Zeitpunkt des Telefonats interessiert. · Asynchroner Dienst: Möchte man dagegen ein Fax verschicken, würde es gegebenenfalls genügen, das Fax innerhalb eines vorgegebenen Zeitraums (z.B. bis zum nächsten Morgen) zu versenden. Zur Ermittlung des billigsten Anbieters muß die geschätzte Verbindungsdauer innerhalb des Zeitfensters eingegeben werden. Die Auflösung, mit der das Zeitfenster untersucht wird, ist entscheidend für die Performance. In Deutschland ändern sich die Tarife immer nur zur vollen Stunde, folglich ist das der minimale Zeitraum der untersucht werden muß.

3.1.2 Vis-a-Vis-Tarife Für Telefonate in das benachbarte Ausland gibt es spezielle Vis-a-Vis-Tarife, die ihrem Kunden günstigere Verbindungen zwischen den jeweiligen Grenzregionen erlauben. Die meisten Telefongesellschaften berechnen ihren Kunden dafür spezielle günstigere Tarife, ohne daß die Kunden eine gesonderte Rufnummer wählen müssen. Dies ist jedoch nicht in allen Ländern so. In der Schweiz müssen beispielsweise zur Nutzung der Vis-a-Vis-Tarife spezielle Verbindungsnummern gewählt werden. TIGA erbringt hier eine besondere Leistung, indem nicht nur der günstigste Anbieter, sondern auch der spezielle Grenztarif angegeben wird.

3.2 Programmierung 3.2.1 Übersicht Die gesamte Funktionalität von TIGA wird in einer einzigen DLL zusammengefaßt. Diese DLL (und das zugehörige API) wird von Ihrer Anwendung benötigt, um auf die Funktionen des Tarifservers zurückzugreifen. Um Ihnen einen möglichst unkomplizierten Umgang mit der DLL zu gewährleisten, haben wir für einige Programmiersprachen einen „Wrapper“ geschrieben. Dieser Wrapper legt sich als Schale um die DLL und ermöglicht Ihnen alle Funktionen aus ihrer gewohnten Programmiersprache heraus zu nutzen. Momentan sind Wrapper für Microsoft Visual C++, Microsoft Visual Basic und Inprise Delphi vorhanden. Weitere Wrapper können auf Wunsch von uns erstellt werden. Da sich die DLL an Standard Windowskonventionen hält, ist es aber auch möglich, eigene Wrapper zu entwickeln (z.B. Clipper / Foxpro). Da es sich dabei um eine 32Bit-DLL handelt, muß die Programmiersprache eine solche auch unterstützen. Wir übernehmen jedoch keine Garantie für nicht von SK-Software entwickelte Wrapper.

Version 2.5

13

TIGA API

3.3 Funktionsbeschreibung 3.3.1 Strategien Provider können entweder nach und nach oder blockweise (die ersten fünf) abgefragt werden. Erhalten Sie die Meldung „Verbindung besetzt“ sollten sie nicht sofort zum nächsten Anbieter wechseln. Wiederholen Sie Ihren Versuch! In der Regel erhalten Sie schnell eine Verbindung. Es ist sinnvoll, sich bei den Anbietern anzumelden, die eine kostenlose Anmeldung anbieten. Die meisten Anbieter geben nämlich in stark genutzten Zeiten den angemeldeten Kunden Vorrang vor den unangemeldeten Nutzern ihrer Netze. Der billigste Anbieter (in einem Zeitraum) Oft wird die Frage nach dem billigsten Anbieter gestellt. Dabei kann man zwei Fälle unterscheiden. · Synchroner Dienst: Zum Telefonieren ist man an dem günstigsten Anbieter zum Zeitpunkt des Telefonats interessiert. · Asynchroner Dienst: Möchte man dagegen ein Fax verschicken, würde es gegebenenfalls genügen, das Fax innerhalb eines vorgegebenen Zeitraums (z.B. bis zum nächsten Morgen) zu versenden. Zur Ermittlung des billigsten Anbieters muß die geschätzte Verbindungsdauer innerhalb des Zeitfensters eingegeben werden. Die Auflösung, mit der das Zeitfenster untersucht wird, ist entscheidend für die Performance. In Deutschland ändern sich die Tarife immer nur zur vollen Stunde, folglich ist das der minimale Zeitraum der untersucht werden muß.

3.3.2 Vis-a-Vis-Tarife Für Telefonate in das benachbarte Ausland gibt es spezielle Vis-a-Vis-Tarife, die ihrem Kunden günstigere Verbindungen zwischen den jeweiligen Grenzregionen erlauben. Die meisten Telefongesellschaften berechnen ihren Kunden dafür spezielle günstigere Tarife, ohne daß die Kunden eine gesonderte Rufnummer wählen müssen. Dies ist jedoch nicht in allen Ländern so. In der Schweiz müssen beispielsweise zur Nutzung der Vis-a-Vis-Tarife spezielle Verbindungsnummern gewählt werden. TIGA erbringt hier eine besondere Leistung, indem nicht nur der günstigste Anbieter, sondern auch der spezielle Grenztarif angegeben wird.

3.3.3 Programmierung Übersicht Die gesamte Funktionalität von TIGA wird in einer einzigen DLL zusammengefaßt. Diese DLL (und das zugehörige API) wird von Ihrer Anwendung benötigt, um auf die Funktionen des Tarifservers zurückzugreifen. Um Ihnen einen möglichst unkomplizierten Umgang mit der DLL zu gewährleisten, haben wir für einige Programmiersprachen einen „Wrapper" geschrieben. Dieser Wrapper legt sich als Schale um die DLL und ermöglicht Ihnen alle Funktionen aus ihrer gewohnten Programmiersprache heraus zu nutzen. Momentan sind Wrapper für Microsoft Visual C++, Microsoft Visual Basic und Inprise Delphi vorhanden. Weitere Wrapper können auf Wunsch von uns erstellt werden. Da sich die DLL an Standard Windowskonventionen hält, ist es aber auch möglich, eigene Wrapper zu entwickeln (z.B. Clipper / Foxpro). Da es sich dabei um eine 32Bit-DLL handelt, muß die Programmiersprache eine solche auch unterstützen. Wir übernehmen jedoch keine Garantie für nicht von SK-Software entwickelte Wrapper.

14

Version 2.5

Programmierung

KAPITEL 4

Programmierung

4.1 Verbindungsaufbau Bevor die Datenbank zu Abfragezwecken genutzt werden kann, muß eine Verbindung dorthin aufgebaut werden. Das geschieht, indem man den TIGA Tarifserver und das Transportverfahren auswählt. Danach können Abfragen in Form von Funktionsaufrufen an die Datenbank gesandt werden. Wird die Verbindung zum Server nicht mehr benötigt, sollte die Verbindung zum TIGA Tarifserver wieder getrennt werden.

4.2 Konstanten Es werden hier nur die wichtigen Konstanten aufgeführt. Weitere Details, sowie der aktuelle Stand sind immer im Sourcecode nachzulesen. Ländercodes für TCountryID Deutschland Schweiz Österreich Liechtenstein Italien Großbritannien Frankreich Niederlande Portugal Spanien Belgien Irland Finnland

coGermany coSwitzerland coAustria coLiechtenstein coItalia coUnitedKingdom coFrance coNetherlands coPortugal coSpain coBelgium coIrishRepublic coFinland

Rückgabewerte für den Verbindungsaufbau TG_CONNECTED TG_NOTCONNECTED TG_ALREADYCONNECTED Rückgabewerte für den Zugriff auf die Datenbank (tgSetCountry) TG_LICENSEVALID TG_LICENSEINVALID TG_LICENSEOUTOFDATE

4.3 Typen und Strukturen In diesem Abschnitt werden die am häufigsten verwendeten Strukturen beschrieben, die in den Funktionsaufrufen verwendet werden. Für den aktuellen Stand sowie die anderen Strukturen wird auf die Programmmodule/Bibliotheken der einzelnen Programmiersprachen verwiesen.

4.3.1 TCountryRec Deklaration

Version 2.5

15

Delphi

TCountryInfo = record countryID : TCountryID; countryName : TCountryNameLR; countryNameShort : TCountryNameShortLR; currency : TCurrencyLR; DialCode : TVorwahlAuslandLR; eurorate, vat : float8; end; TCountryRec = record lizLenInfo : integer; countryInfo : TCountryInfo; referenceModel : TModelId; NKZPrefix : TNKZLR; end;

C/C++

typedef struct { TCountryID countryID; char countryName[21]; char countryNameShort[3]; char currency[4]; char DialCode[12]; double eurorate; double vat; } TCountryInfo; typedef struct TCountryInfo countryInfo; TModelID referenceModel; char NKZPrefix[7]; } TCountryRec;

Visual Basic

Type TCountryInfo countryID As Long countryName As String * 20 countryNameShort As String * 2 currency As String * 3 DialCode As String * 11 eurorate As Double vat As Double End Type Type TCountryRec CountryInfo As Long referenceModel As Long NKZPrefix As String * 6 End Type

Felder CountryId Die ID des Landes, dessen Tarife in der Datenbank enthalten sind. Die Konstanten, die diese Werte definieren, beginnen mit coXXX, siehe Seite 15 countryName Der Name des Landes. countryNameShort

Version 2.5

16

Programmierung

Das zweistellige Kürzel des Landes, das in internationalen Domainangaben verwendet wird (de für Deutschland, ch für die Schweiz usw.). currency Das internationale Währungskennzeichen des Landeswährung (DEM, SFR, ATS, usw.). dialCode Die internationale Auslandsvorwahl des Landes (0049 für Deutschland, 0033 für die Schweiz, usw.). eurorate Der Wechselkurs der Landeswährung zum Euro nach der offiziellen Trianglierungsregel (1,95583 für Deutschland) vat Der Mehrwertsteuersatz des Landes für Telefonkosten. Dies muß nicht unbedingt der normale / volle Steuersatz sein. In Deutschland beträgt er 16%. countryInfo Eine Struktur, die sich wie oben definiert. referenceModel Die ID des Modells, welches standardmäßig bei Berechnungen benutzt wird, wenn kein Anbieter ausgewählt wurde, weil der Rufnummer keine NKZ vorangestellt wurde. Das voreingestellte Modell kann über tgSetPreselect geändert werden NKZPrefix Der Teil der NKZ, der bei allen Anbietern eines Landes gleich ist. In Deutschland beginnen alle NKZs mit den Ziffern 010...

4.3.2 TProviderRec Deklaration Delphi

TproviderRec = record Id : TProviderID; Name : TProviderName; NKZ : TNKZ; hotline : www : end;

C/C++

typedef struct { TProviderID id; char name[21]; char nkz[7]; char hotline[24]; char www[41]; } TProviderRec;

Visual Basic

Type TProviderRec id As Long name As String * 20 nkz As String * 6

Version 2.5

17

TIGA API

hotline As String * 23 www As String * 40 End Type Felder ID ist eine eindeutiger Wert, über den auf den Anbieter zugegriffen werden kann. Dieser Wert wird einmalig vergeben und auch nach dessen Entfernung aus der Tarifdatenbank nicht erneut vergeben. Name liefert die Bezeichnung der Anbieters. Entspricht meist der offiziellen Firmenbezeichnung. NKZ enthält die Ziffernfolge, die gewählt werden muß, um über diesen Anbieter zu telefonieren. Die Anzahl der Stellen und der Aufbau der NKZ kann sich in Zukunft ändern (schon heute gibt es 5- und 6-stellige NKZs). hotline Die vom Anbieter angegebene Rufnummer bei Fragen und Problemen. www Die Internet-Adresse des Anbieters.

4.3.3 TModelRec Deklaration Delphi

TModelRec = record id : TModelId; provid : TProviderID; name : TModelNameLR; ChargeUnit : TChargeUnit; suppCharge, minimumCharge : TCost; validFrom : TDateTime; registrationRequired : boolean; separateBill : boolean; end;

C/C++

typedef struct { TModelID id; TProviderID provid; char name[21]; TChargeUnit chargeUnit; TCost suppCharge; TCost minimumCharge; DATE validFrom; bool registrationRequired; bool separateBill; } TModelRec;

Visual Basic

Type TModelRec id As Long provId As Long name As String * 20 chargeUnit As Byte

18

Version 2.5

Programmierung

suppCharge As Double minimumCharge As Double validFrom As Date registrationRequired As Boolean separateBill As Boolean End Type Die Felder modelID ein eindeutiger Wert, über den auf das Modell zugegriffen werden kann. ProvID die ID des Anbieters, dem dieses Modell zugeordnet ist. name Textuelle Beschreibung des Modells, wenn möglich wird die offizielle Bezeichnung des Anbieters verwendet. ChargeUnit Legt die Einheit der nachfolgenden beiden Parameter (suppCharge, minCharge) fest. Bei 0 wird der nachfolgende Parameter als Zeitdauer, bei 1 als Betrag interpretiert. Ist die Einheit Zeit (ChargeUnit = 0), wird der Wert in Sekunden angegeben. SuppCharge=5 bedeutet, zu jeder Verbindung werden 5 Sekunden dazugerechnet. Ist die Einheit Betrag (ChargeUnit = 1), wird der Wert als Basiseinheit der jeweiligen Landeswährung eingegeben. MinCharge=0.05 in Deutschland bedeutet, daß die Kosten einer Verbindung mindestens 5 Pfennige betragen. suppCharge Der Betrag / die Zeitdauer, der/die zusätzlich zu jeder Verbindung berechnet wird. Es sind positive und negative Werte möglich. Um festzulegen, daß die ersten 15 Sekunden eines Gespräches kostenlos sind, muß man ChargeUnit=0 und SuppCharge = -15 setzen. minimumCharge Der Betrag / die Zeitdauer, der/die mindestens bei jeder Verbindung berechnet wird. Es sind positive und negative Werte möglich (s.o.). validFrom Der Zeitpunkt, ab dem dieses Modell gültig ist. registrationRequired Angabe, ob man sich zur Nutzung des Modells beim Anbieter anmelden muß (true) oder dieses Modell auch ohne Anmeldung nutzen kann (false). separateBill Angabe, ob die Abrechnung über den Anbieter selbst (true) oder die Deutsche Telekom (false) erfolgt.

4.3.4 TZoneRec Deklaration Delphi

Version 2.5

TZoneRec = record absNr, relNr name

: TZoneNr; : TZoneNameLR;

19

TIGA API

ClassID : TZoneClass; ClassName : TZoneClassNameLR; end; C/C++

typedef struct { TZoneNr absNr; TZoneNr relNr; char name[21]; TZoneClass ClassID; char ClassName[13]; } TZoneRec;

Visual Basic Type TZoneRec absNr As Integer relNr As Integer name As String * 20 ClassID As Byte ClassName As String * 12 End Type Die Felder absNr Die absolute Nummer der Zone innerhalb des Modells. relNr Die relative Nummer der Zone innerhalb der Zonenklasse (Bei der Telekom ist RegioCall die zweite Zone innerhalb der Zonenklasse Inland und GermanCall ist die dritte Zone). name Der Name der Zone innerhalb des Modells. ClassID Die ID der Zonenklasse. ClassName Der Name der Zonenklasse.

4.3.5 TCostRec (intern !!!) Deklaration Delphi

C/C++

20

TCostRec = record gueltigAb, gueltigBis : TDateTime; wt : TWochentag; wtName : array[0..20] of char; bis : TZeit; amount : TCost; end; typedef struct { DATE gueltigAb; DATE gueltigBis; TWochentag wt; char wtName[21];

Version 2.5

Programmierung

TZeit bis; TCost betrag; } TCostRec; Visual Basic Die Felder gueltigAb gueltigBis TDateTime: Der Zeitraum, in dem die angegebenen Kosten gelten Wochentag Die Tage, an denen die Kosten gelten. Jeder Tag ist ein Bit So=7 Sa = 0 ??? wtName array[0..20] of char; zeit Die Uhrzeit bis zu der die Kosten gelten amount Die Kosten einer Verbindung bis zur angegebenen Uhrzeit, in den Zeiten gültigAb, gültigBis.

4.4 Funktionen 4.4.1 Initialisierung

Version 2.5

21

TIGA API

tgInit Diese Funktion dient zur Initialisierung der TIGA API und muß vor der Nutzung der Bibliotheksfunktionen einmalig aufgerufen werden. Deklaration Delphi

procedure tgInit( licenseNo : string );

C/C++

void tgInit( char* licenseNo );

Visual Basic

Sub tgInit( ByVal LicenseNo As String );

Parameter

licenseNo [in] Die Lizenznummern aller benötigten Datenbanken. Die einzelnen Lizenznummern müssen durch Kommata getrennt werden. Eine Prüfung der Lizenzen geschieht erst, wenn mit tgSetCountry auf eine Datenbank zugegriffen wird.

Rückgabe

keine.

Siehe auch

tgDone, tgSetCountry

22

Version 2.5

Programmierung

tgDone Mit tgDone werden angeforderte Speicherstrukturen der TIGA API wieder freigegeben. Diese Funktion muß am Ende der Benutzung der TIGA API aufgerufen werden. Deklaration Delphi

procedure tgDone;

C/C++

void tgDone();

Visual Basic

Sub tgDone()

Parameter

keine.

Rückgabe

keine.

Siehe auch

tgInit, tgConnectToLocalServer

4.4.2 Verbindungsaufbau

Version 2.5

23

TIGA API

tgConnectToLocalServer Die Verbindung zum lokalen TIGA Tarifserver wird mit tgConnectToLocalServer hergestellt. Deklaration Delphi

function tgConnectToLocalServer( databasePath : TFilename ): Integer;

C/C++

int tgConnectToLocalServer( char *databasePath );

Visual Basic

Function tgConnectToLocalServer( ByVal databasePath As String) As Long

Parameter

databasePath [in] Der Parameter databasePath gibt den Pfad an, in dem die lokale Datenbankdatei zu finden ist. Wird kein Pfad angegeben, so geht die TIGA API vom aktuellen Arbeitsverzeichnis aus.

Rückgabe

tgConnectToLocalServer liefert TG_CONNECTED, wenn die Datenbankverbindung erfolgreich hergestellt wurde TG_NOTCONNECTED, wenn die Datenbankverbindung nicht hergestellt werden konnte TG_ALREADYCONNECTED, wenn die Datenbankverbindung bereits besteht.

Siehe auch

tgConnectToNTServer, tgConnectToNovellServer

24

Version 2.5

Programmierung

tgConnectToNTServer Die logische Verbindung zum TIGA Tarifserver, der auf einem (entfernten) Microsoft Windows NT-Rechner läuft, wird durch die Funktion tgConnectToNTServer hergestellt. Deklaration Delphi

function tgConnectToNTServer( databasePath : TFilename; username : string; password : string ): Integer;

C/C++

int tgConnectToNTServer( char *databasePath, char *username, char *password );

Visual Basic

Function tgConnectToNTServer( ByVal databasePath As String, ByVal username As String, ByVal password As String) As Long

Parameter

databasePath [in] Der Parameter databasePath wird derzeit nicht ausgewertet. username [in] Der Parameter username gibt den Namen des Benutzers an den Server zu Anmeldezwecken weiter. password [in] Der Parameter password gibt das Paßwort des Benutzers an den Server zu Anmeldezwecken weiter.

Rückgabe

tgConnectToNTServer liefert TG_CONNECTED, wenn die Datenbankverbindung erfolgreich hergestellt wurde TG_NOTCONNECTED, wenn die Datenbankverbindung nicht hergestellt werden konnte TG_ALREADYCONNECTED, wenn die Datenbankverbindung bereits besteht.

Siehe auch

tgConnectToLocalServer, tgConnectToNovellServer, tgConnectViaIP

Version 2.5

25

TIGA API

tgConnectToNovellServer Die logische Verbindung zum TIGA Tarifserver, der auf einem (entfernten) Novell Netware-Server läuft, wird durch die Funktion tgConnectToNovellServer hergestellt. Deklaration Delphi

function tgConnectToNovellServer( databasePath : TFilename; username : string; password : string ): Integer;

C/C++

int tgConnectToNovellServer( char *databasePath, char *username, char *password );

Visual Basic

Function tgConnectToNovellServer( ByVal databasePath As String, ByVal username As String, ByVal password As String) As Long

Parameter

databasePath [in] Der Parameter databasePath wird derzeit nicht ausgewertet. username [in] Der Parameter username gibt den Namen des Benutzers an den Server zu Login-Zwecken weiter. password [in] Der Parameter password gibt das Paßwort des Benutzers an den Server zu Login-Zwecken weiter.

Rückgabe

tgConnectToNovellServer liefert TG_CONNECTED, wenn die Datenbankverbindung erfolgreich hergestellt wurde TG_NOTCONNECTED, wenn die Datenbankverbindung nicht hergestellt werden konnte TG_ALREADYCONNECTED, wenn die Datenbankverbindung bereits besteht.

Siehe auch

tgConnectToLocalServer, tgConnectToNTServer, tgConnectViaIP

26

Version 2.5

Programmierung

tgConnectViaIP Über das Protokoll TCP/IP wird eine physikalische Verbindung zum TIGA Tarifserver aufgebaut. Diese Funktion steht in enger Beziehung zu den Funktionen tgConnectToNTServer und tgConnectToNovellServer, welche die logische Verbindung zum TIGA Tarifserver herstellen. Deklaration Delphi

procedure tgConnectViaIP( ipadr : string; port : integer)

C/C++

void tgConnectViaIP( char *ipadr, int port );

Visual Basic

Sub tgConnectViaIP( ByVal ipadr As String, ByVal port As Long)

Parameter

ipadr [in] Der Parameter ipadr gibt die Zieladresse der aufzubauenden Verbindung zum TIGA Tarifserver an. Die Adresse muß das Format aa.bb.cc.dd aufweisen, wobei aa, bb, cc, dd jeweils ganze Zahlen im Bereich von 0 bis 255 darstellen. port [in] Über den Parameter port wird die Verbindung zum Server aufgebaut. Die angegebene Portadresse muß mit der Portadresse des TIGA Tarifservers übereinstimmen, damit es zu einer Verbindung kommen kann. Der Standardport für den TIGA Tarifserver ist tgPort, kann jedoch individuell konfiguriert werden.

Rückgabe

keine.

Siehe auch

tgConnectToNTServer, tgConnectToNovellServer

Version 2.5

27

TIGA API

tgDisconnectFromServer Um eine bestehende Verbindung tgDisconnectFromServer geeignet.

zum

TIGA

Tarifserver

zu

trennen

ist

Deklaration Delphi

procedure tgDisconnectFromServer;

C/C++

void tgDisconnectFromServer();

Visual Basic

Sub tgDisconnectFromServer()

Parameter

keine.

Rückgabe

keine.

Siehe auch

tgConnectToLocalServer, tgConnectToNTServer, tgConnectToNovellServer, tgConnectViaIP

4.4.3 Abfragen und Einstellungen Ist eine Verbindung zum TIGA Tarifserver aufgebaut, so können Informationen mit Hilfe von Abfragen abgerufen werden.

28

Version 2.5

Programmierung

tgSetCountry TIGA bietet Tarifdatenbanken für verschiedene europäische Länder. Mit tgSetCountry wählt man eine dieser Tarifdatenbanken für ein bestimmtes Land aus. Mit den Konstanten coXXX ist ein Land auszuwählen. Alle nachfolgenden Datenbankanfragen beziehen sich dann auf das gewählte Land. Deklaration Delphi

function tgSetCountry( countryID : TCountryID ) : integer;

C/C++

int tgSetCountry( TCountryID countryID );

Visual Basic

Sub tgSetCountry( ByVal countryID As Long );

Parameter

countryID [in] Der Parameter countryID gibt das Land an, für das die nachfolgenden Datenbankabfragen durchgeführt werden.

Rückgabe

TG_LICENSEVALID, wenn auf die Datenbank zugegriffen werden konnte TG_LICENSEOUTOFDATE, wenn die Lizenz für eine Datenbank abgelaufen ist TG_LICENSEINVALID, wenn ein Fehler bei dem Zugriff aufgetreten ist, weil die Datenbank nicht für die benutzte Lizenz registriert, oder die Datenbank beschädigt ist.

Siehe auch

tgGetCountry, Konstanten coXXX, siehe Seite 15

Version 2.5

29

TIGA API

tgGetCountry Diese Funktion liefert Informationen über das mit tgSetCountry gewählte Land. Deklaration Delphi

procedure tgGetCountry( var countryRec : TCountryRec );

C/C++

void tgGetCountry( TCountryRec *countryRec );

Visual Basic

Sub tgGetCountry( ByRef countryRec as TCountryRec );

Parameter

countryRec [out] Der Parameter countryRec beinhaltet nach dem Aufruf die Informationen über das mit tgSetCountry gewählte Land. Folgende Informationen werden zur Verfügung gestellt: countryInfo Informationen über das Land referenceModel Referenzmodell des Landes NKZPrefix Netzkennzifferprefix des Landes

Rückgabe

keine.

Siehe auch

tgSetCountry, TCountryInfo

30

Version 2.5

Programmierung

tgSetLocation Mit der Funktion tgSetLocation wird der Standort festgelegt, für den alle nachfolgenden Kostenberechnungen durchgeführt werden. Der Standort ist der, von wo aus der Anwender telefonieren möchte bzw. für welchen er seine Berechnungen durchführen lassen möchte. Deklaration Delphi

function tgSetLocation( phoneNumber : TPhoneNumber ): boolean;

C/C++

bool tgSetLocation( char *phoneNumber);

Visual Basic

Function tgSetLocation( ByVal phoneNumber as String ) As Boolean

Parameter

phoneNumber [in] Mit dem Parameter phoneNumber wird TIGA mitgeteilt, für welchen Standort die Kostenberechnungen durchgeführt werden sollen. Der Standort stellt hierbei die Vorwahl der Stadt des jeweilig gewählten Landes dar. Wird kein Standort angegeben, so wird vom Standort Darmstadt (06151) in Deutschland ausgegangen.

Rückgabe

True, wenn die gewählte Standortvorwahl für das gewählte Land gültig war. False, wenn die gewählte Standortvorwahl für das gewählte Land nicht gültig war.

Siehe auch

Version 2.5

31

TIGA API

tgSetPreselect Mit der Funktion tgSetPreselect wird die Telefongesellschaft festgelegt, die genutzt wird, wenn kein spezieller Anbieter (keine Netzkennzahl) angegeben wird. In den meisten Fällen wird in Deutschland die Deutsche Telekom als Standardanbieter genutzt. Wird beispielsweise die 089-1234567 gewählt, geht das Gespräche über die Deutsche Telekom. Deklaration Delphi

procedure tgSetPreselect( provID : TProviderID);

C/C++

void tgSetPreselect( TProviderID provID);

Visual Basic

Sub tgSetPreselect( ByVal provID as Long)

Parameter

provID [in] Mit dem Parameter provID wird TIGA mitgeteilt, für welche Telefongesellschaft die Kostenberechnungen durchgeführt werden sollen. Die Deutsche Telekom wird von TIGA als Standardtelefongesellschaft in Deutschland voreingestellt.

Rückgabe

keine.

Siehe auch

32

Version 2.5

Programmierung

tgSetDate Mit der Funktion tgSetDate wird der Zeitpunkt festgelegt, der Berücksichtigung bei den nachfolgenden Abfragen findet. So können damit die Anbieter, Modelle oder Kosten zu dem angegebenen Zeitpunkt ermittelt werden. Mit Hilfe der historischen Datenbank lassen sich auch zeitlich zurückliegende Berechnungen durchführen. Deklaration Delphi

procedure tgSetDate( date : TDateTime);

C/C++

void tgSetDate( DATE date);

Visual Basic

Sub tgSetDate( ByVal aDate As Date)

Parameter

date [in] Mit dem Parameter date wird TIGA mitgeteilt, für welchen Zeitpunkt die Berechnungen durchgeführt werden sollen.

Rückgabe

keine.

Siehe auch

4.4.4 Datenbankinhalt ermitteln Mit den nachfolgenden Funktionen bekommt man Informationen über die Anbieter, deren Modelle und die Zonen.

Version 2.5

33

TIGA API

tgGetProvider Die Funktion tgGetProvider liefert Informationen zu dem mit provID ausgewählten Provider. Wird eine ungültige provID gewählt, ist der provRec leer. Deklaration Delphi

procedure tgGetProvider( provID : TProviderID; var provrec : TProviderRec );

C/C++

void tgGetProvider( TProviderID provid, TProviderRec provrec );

Visual Basic

Sub tgGetProvider( ByVal provId As Long, ByRef pr As TproviderRec )

Parameter

provID [in] Der Parameter provID gibt den Provider an, für den nähere Informationen abgefragt werden sollen. provrec [out] Der Parameter provrec beinhaltet nach dem Funktionsaufruf die weiteren Providerinformationen.

Rückgabe

keine.

Siehe auch

tgProviderFindFirst, tgProviderFindNext, TProviderRec

34

Version 2.5

Programmierung

tgProviderFindFirst Liefert den ersten verfügbaren Provider, der zum gegebenen Zeitpunkt verfügbar war. Deklaration Delphi

function tgProviderFindFirst( var provrec : TProviderRec ) : Boolean;

C/C++

bool tgProviderFindFirst( TProviderRec *provrec );

Visual Basic

Function tgProviderFindFirst( ByRef provrec As TproviderRec ) as Boolean

Parameter

provrec [out] Der Parameter provrec liefert Informationen über den Provider. Beispiel b := tgProviderFindFirst( provrec ); while b do begin { action } b := tgProviderFindNext( provrec ); end;

Rückgabe

True, wenn ein Provider verfügbar war. False, wenn kein Provider verfügbar war.

Siehe auch

tgSetDate, tgProviderFindNext, tgGetProvider, TProviderRec

Version 2.5

35

TIGA API

tgProviderFindNext Liefert den nächsten verfügbaren Provider zum gegebenen Zeitpunkt. Vor dem ersten Aufruf von tgProviderFindNext muß immer ein tgProviderFindFirst durchgeführt worden sein. Deklaration Delphi

function tgProviderFindNext( var provrec : TProviderRec ) : Boolean;

C/C++

bool tgProviderFindNext( TProviderRec *provrec );

Visual Basic

Function tgProviderFindNext( ByRef provrec As TProviderRec ) as Boolean

Parameter

provrec [out] Der Parameter provrec liefert Informationen über den Provider. Beispiel b := tgProviderFindFirst( provrec ); while b do begin { action } b := tgProviderFindNext( provrec ); end;

Rückgabe

True, wenn ein Provider verfügbar war. False, wenn kein Provider verfügbar war.

Siehe auch

tgSetDate, tgGetProvider, tgProviderFindFirst, TProviderRec

36

Version 2.5

Programmierung

tgSetProviderFilter Über diesen Filter lassen sich bestimmte Provider auswählen. Z.B nur die Provider die einen Internetanschluß oder echtes Call-by-Call anbieten (derzeit nicht verfügbar). Siehe auch

Version 2.5

37

TIGA API

tgGetModel Mit der Funktion tgGetModel lassen sich zusätzliche Informationen über das Tarifmodell eines gewählten Anbieters abfragen. Diese Informationen sind im Parameter modrec beschrieben. Deklaration Delphi

procedure tgGetModel( modid : TModelID; var modrec : TModelRec );

C/C++

void tgGetModel( TModelID modid, TModelRec *modrec );

Visual Basic

Sub tgGetModel( ByVal modId As Long, ByRef modrec As TModelRec)

Parameter

modid [in] modid identifiziert das Tarifmodell eines Anbieters. modrec [out] Der Parameter modrec liefert Informationen über das gewählte Tarifmodell.

Rückgabe

keine.

Siehe auch

tgGetProvider. TModelRec

38

Version 2.5

Programmierung

tgModelFindFirst Die Funktion tgModelFindFirst liefert das erste Modell, das für den Provider provID verfügbar ist. Deklaration Delphi

procedure tgGetModelFindFirst( provID : TProviderID; var modrec : TModelRec );

C/C++

void tgGetModelFindFirst( TProviderID provID, TModelRec *modrec );

Visual Basic

Sub tgGetModelFindFirst( ByVal provID As Long, ByRef modrec As TModelRec)

Parameter

provID [in] provID identifiziert den Provider, für den das erste Modell geliefert werden soll. modrec [out] Der Parameter modrec liefert Informationen über das gewählte Tarifmodell.

Rückgabe

keine.

Siehe auch

tgModelFindNext, tgProviderFindFirst, tgProviderFindNext, TModelRec

Version 2.5

39

TIGA API

tgModelFindNext Die Funktion tgModelFindNext liefert das nächste verfügbare Modell für den ausgewählten Provider. Dem Aufruf dieser Funktion sollte ein Aufruf der Funktion tgModelFindFirst vorausgehen, um das erste gültige Modell eines Anbieters zu bekommen. Deklaration Delphi

function tgGetModelFindNext( var modrec : TModelRec ) : Boolean;

C/C++

bool tgGetModelFindNext( TModelRec *modrec );

Visual Basic

Function tgGetModelFindNext( ByRef modrec As TModelRec) As Boolean

Parameter

modrec [out] Der Parameter modrec liefert Informationen über das gewählte Tarifmodell. Folgende Informationen sind zu erfahren: Id Identifikationsnummer des Tarifmodells provid Provider-Identifikationsnummer name Name des Tarifmodells suppCharge Zusätzliche Gebühr zum Gespräch minimumCharge Minimale Gebühr für das Gespräch stand Datum der letzten Änderung registrationRequired Registrierung beim Anbieter notwendig separateBill Provider bietet gesonderte Rechnungsstellung

Rückgabe

keine.

Siehe auch

tgModelFindFirst, tgProviderFindFirst, tgProviderFindNext, TModelRec

40

Version 2.5

Programmierung

tgGetProviderFromModelID Die Funktion tgGetProviderFromModelID sucht den Provider, der zum angegebenen Tarifmodell gehört. Deklaration Delphi

function tgGetProviderFromModelID( modid : TModelID ) : TProviderID;

C/C++

TProviderID tgGetProviderFromModelID ( modid : TModelID );

Visual Basic

Function tgGetProviderFromModelID ( ByVal modid As Long) As Long

Parameter

modid [in] Der Parameter modid identifiziert das Tarifmodell, für das der Anbieter ermittelt werden soll.

Rückgabe

Die Funktion tgGetProviderFromModelID liefert die ProviderID zum angegeben Tarifmodell.

Siehe auch

tgGetProvider

Version 2.5

41

TIGA API

tgGetZone Die Funktion tgGetZone liefert die Tarifzone, in welche die angegebene Telefonnummer bei dem gewählten Tarifmodell fällt. Deklaration Delphi

procedure tgGetZone( modID : TModelID; phoneNumber : TPhoneNumber; var zoneRec : TZoneRec );

C/C++

void tgGetZone( TModelID modID, char *phoneNumber, TZoneRec *zoneRec );

Visual Basic

Sub tgGetZone( ByVal modID As Long, ByVal phoneNumber As String, ByRef zoneRec As TZoneRec)

Parameter

modID [in] Der Parameter modID identifiziert das Modell, das zusammen mit der angegebenen Telefonnummer für die Berechnung der Tarifzone herangezogen wird. phonenumber [in] Der Parameter phonenumber gibt die Telefonnummer an, die zusammen mit dem Parameter Tarifmodell modID für die Berechnung der Tarifzone herangezogen wird. zoneRec [out] Der Parameter zoneRec liefert die durch modID und phonenumber gekennzeichnete Tarifzone. Folgende Informationen werden geliefert: anr Nummer der Zone innerhalb des Modells (absolut) rnr Nummer der Zone innerhalb der Zonenklasse (relativ) name Name der Zone (z.B. RegioCall) aClass Nummer der Zonenklasse ClassName Name der Zonenklasse (z.B. Inland)

Rückgabe

keine.

Siehe auch

42

Version 2.5

Programmierung

tgGetTakt Die Funktion tgGetTakt ermittelt die Taktdauer des ersten und aller folgenden Takte für ein Modell, eine Rufnummer und einen Zeitpunkt. Deklaration Delphi

procedure tgGetTakt( modID : TModelID; phoneNumber : TPhoneNumber; date : TDateTime; var takt1 : TTaktDauer; var taktn : TTaktDauer );

C/C++

void tgGetTakt( TModelID modID, char *phoneNumber, DATE date, TTaktDauer *takt1, TTaktDauer *taktn );

Visual Basic

Sub tgGetTakt( ByVal ByVal ByVal ByRef ByRef

Parameter

modID As Long, phoneNumber As String, aDate As Date, takt1 As Single, taktn As Single )

modID [in] Der Parameter modID identifiziert das Modell, für das die Taktdauer ermittelt werden soll. phoneNumber [in] phoneNumber ist die Rufnummer des Angewählten. Date [in] Der Parameter Date gibt den Zeitpunkt an, für den die Taktdauer ermittelt werden soll. takt1 [out] Der Parameter takt1 beinhaltet nach dem Aufruf die Dauer des ersten Taktes für das gewählte Modell. taktn [out] Der Parameter taktn beinhaltet nach dem Aufruf die Dauer der nachfolgenden Takte für das gewählte Modell.

Rückgabe

keine.

Siehe auch

4.4.5 Validierungsfunktionen

Version 2.5

43

TIGA API

tgIsValidPhoneNumber Mit der Funktion tgIsValidPhoneNumber kann die angegebene Rufnummer auf ihre Gültigkeit überprüft werden. Eine Rufnummer ist dann gültig, wenn sie genügend Informationen enthält, um sie einer Tarifzone zuzuordnen. Wenn eine Rufnummer gültig ist, muß sie noch nicht ein gültiger Standort sein. Deklaration Delphi

function tgIsValidPhoneNumber( phoneNumber : TPhoneNumber ) : Boolean;

C/C++

bool tgIsValidPhoneNumber( char *phoneNumber );

Visual Basic

Function tgIsValidPhoneNumber( ByVal phoneNumber As String) As Boolean

Parameter

phoneNumber [in] Der Parameter phoneNumber gibt die Telefonnummer an, die auf ihre Gültigkeit hin überprüft werden soll.

Rückgabe

True, wenn die angegebene Telefonnummer gültig war. False, wenn die angegebene Telefonnummer ungültig war.

Siehe auch

tgIsValidLocation

44

Version 2.5

Programmierung

tgIsValidLocation Die Funktion tgIsValidLocation ermittelt, ob die angegebene Rufnummer einen gültigen Standort darstellt. Eine Rufnummer ist ein gültiger Standort, wenn die Rufnummer einen Ort im inländischen Festnetz beschreibt. Eine Rufnummer kann eine gültige Rufnummer sein, aber kein gültiger Standort. Deklaration Delphi

function tgIsValidLocation( phoneNumber : TPhoneNumber ) : Boolean;

C/C++

bool tgIsValidLocation( char *phoneNumber );

Visual Basic

Function tgIsValidLocation( ByVal phoneNumber As String) As Boolean

Parameter

phoneNumber [in] Der Parameter phoneNumber gibt die Telefonnummer an, deren Standort als Basis für weitere Berechnungen verwendet wird.

Rückgabe

True, wenn die angegebene Telefonnummer gültig war. False, wenn die angegebene Telefonnummer ungültig war.

Siehe auch

tgSetLocation, tgIsValidPhoneNumber

Version 2.5

45

TIGA API

tgGetCityName Die Funktion tgGetCityName ermittelt den Ortsnamen zu der gegebenen Rufnummer. Bei den inländischen Vorwahlen liefert die Funktion den Ortsnamen. Bei den ausländischen Rufnummern die Landesbezeichnung, bei Mobilfunknummern wird der Netzbetreiber geliefert und bei Sondernummern die Bezeichnung des Dienstes (z.B. Quix, Scall, usw.). Deklaration Delphi

function tgGetCityName( phoneNumber : TPhoneNumber ) : TCityName;

C/C++

void *tgGetCityName( char *phoneNumber, char *CityName );

Visual Basic

Sub tgGetCityName( ByVal phoneNumber As String, ByVal CityName As String)

Parameter

phoneNumber [in] Der Parameter phoneNumber gibt die Telefonnummer an, für die der Name der zugehörigen Stadt oder des zugehörigen Dienstes ermittelt werden soll. CityName [out] (nur C/C++ und Visual Basic) CityName nimmt den Städtenamen oder den Namen des Dienstes auf, der anhand der Telefonnummer ermittelt wurde.

Rückgabe

(nur Delphi) Name der Stadt oder des Dienstes, der anhand der Telefonnummer ermittelt wurde.

Siehe auch

4.4.6 Kostenermittlung

46

Version 2.5

Programmierung

tgGetCost Die Funktion tgGetCost berechnet die Kosten für ein Gespräch nach dem gegebenen Tarifmodell vom aktuellen Standort aus zur angegebenen Rufnummer. Der Anruf beginnt um startofCall und dauert duration Zeit. Zusätzlich wird die verbleibende Zeit ermittelt, die man noch über die Dauer hinaus telefonieren könnte, ohne weitere Kosten zu produzieren. Deklaration Delphi

function tgGetCost( modID : TModelID; phoneNumber : TPhoneNumber; startOfCall : TDateTime; duration: TDateTime; var remainingTime : TDateTime ) : TCost;

C/C++

TCost tgGetCost( TModelID modID, char *phoneNumber, DATE startofCall, DATE duration, DATE *remainingTime );

Visual Basic

Function tgGetCost( ByVal ByVal ByVal ByVal ByRef

Parameter

modId As Long, phoneNumber As String, startOfCall As Date, duration As Date, remainingTime As Date ) As Double

modID [in] Der Parameter modID identifiziert das Tarifmodell, das der Kostenberechnung zugrunde liegt. phoneNumber [in] Der Parameter phoneNumber ist die Zielrufnummer, die der Kostenberechnung zugrunde liegt. startOfCall [in] Der Parameter startOfCall gibt an, für welchem Zeitpunkt die Berechnung durchgeführt werden soll. duration [in] Der Parameter duration gibt an, für welchen Zeitraum die Berechnung durchgeführt werden soll. remainingTime [out] Der Parameter remainingTime beinhaltet nach dem Aufruf die verbleibende Zeit, die keine weiteren Kosten verursacht. Sie stellt also die Zeit der angefangenen Einheit dar.

Rückgabe

tgGetCost liefert die entstandenen Kosten für das Gespräch zur Zielrufnummer im gewählten Tarifmodell für den angegebenen Zeitraum.

Siehe auch

tgGetCheapest

Version 2.5

47

TIGA API

tgGetCheapest Die Funktion tgGetCheapest berechnet den günstigsten Anbieter für ein gegebenes Gespräch im angegebenen Zeitraum. Berücksichtigt werden alle Anbieter die mit tgSetCheapestPool ausgewählt wurden. Deklaration Delphi

function tgGetCheapest( phoneNumber : TPhoneNumber; startOfCall : TDateTime; duration : TDateTime; costRanking : Word var cost : TCost ) : TModelID;

C/C++

TModelID tgGetCheapest( char* phoneNumber, DATE startOfCall, DATE duration, unsigned short costRanking, TCost* cost);

Visual Basic

Function tgGetCheapest ( ByVal phoneNumber As String, ByVal startOfCall As Date, ByVal duration As Date, ByVal costRanking As Long, ByRef cost As Double) As Long

Parameter

phoneNumber [in] Der Parameter phoneNumber ist die Zielrufnummer, die der Kostenberechnung zugrunde liegt. startOfCall [in] Der Parameter startOfCall gibt an, für welchem Zeitpunkt die Berechnung durchgeführt werden soll. duration [in] Der Parameter duration gibt die Verbindungsdauer an. Für diesen Zeitraum werden die Berechnung durchgeführt. costRanking [in] Der Parameter costRanking gibt an, für welchen Anbieter die Kosten berechnet werden sollen. costRanking = 0 gibt den günstigsten Anbieter an, costRanking = 1 den zweitgünstigsten usw. Die Anbieter werden entsprechend ihrer Kosten fortlaufend numeriert. cost [out] Der Parameter cost beinhaltet nach dem Aufruf die berechneten Kosten für den mit costRanking gewählten Anbieter im gegebenen Zeitraum.

Rückgabe

Die Tarifmodell-ID des günstigsten Anbieters.

Siehe auch

tgGetCost, tgGetProviderFromModelID, tgGetCheapestInPeriod, tgSetCheapestPool, tgClearCheapestPool

48

Version 2.5

Programmierung

tgGetCheapestinPeriod Die Funktion tgGetCheapestinPeriod berechnet den günstigsten Anbieter für ein Telefonat in einem gegebenen Zeitfenster. Berücksichtigt werden alle Anbieter die mit tgSetCheapestPool ausgewählt wurden. Deklaration Delphi

function tgGetCheapestinPeriod( phoneNumber : TPhoneNumber; startOfTime : TDateTime; endOfTime : TDateTime; duration : TDateTime; costRanking : Word var cost : TCost ) : TModelID;

C/C++

TModelID tgGetCheapestinPeriod ( char* phoneNumber, DATE startOfTime, DATE endOfTime, DATE duration, unsigned short costRanking, TCost* cost);

Visual Basic

Function tgGetCheapestinPeriod( ByVal phoneNumber As String, ByVal startOfTime As Date, ByVal endOfTime As Date, ByVal duration As Date, ByVal costRanking As Long, ByRef cost As Double) As Long

Parameter

phoneNumber [in] Der Parameter phoneNumber ist die Zielrufnummer, die der Kostenberechnung zugrunde liegt. startOfTime [in] Der Parameter startOfTime gibt den Beginn des Zeitfensters an. endOfTime [in] Der Parameter endOfTime gibt das Ende des Zeitfensters an. duration [in] Der Parameter duration gibt die Verbindungsdauer an. Für diesen Zeitraum innerhalb des Zeitfensters werden die Berechnung durchgeführt. costRanking [in] Der Parameter costRanking gibt an, für welchen Anbieter die Kosten berechnet werden sollen. costRanking = 0 gibt den günstigsten Anbieter an, costRanking = 1 den zweitgünstigsten usw. Die Anbieter werden entsprechend ihrer Kosten fortlaufend numeriert. cost [out] Der Parameter cost beinhaltet nach dem Aufruf die berechneten Kosten für den mit costRanking gewählten Anbieter im gegebenen Zeitraum innerhalb des Zeitfensters.

Rückgabe

Version 2.5

Die Tarifmodell-ID des günstigsten Anbieters.

49

TIGA API

Siehe auch

50

tgGetCheapest, tgGetCost, tgClearCheapestPool, tgSetCheapestPool

Version 2.5

Programmierung

tgClearCheapestPool Mit der Funktion tgClearCheapestPool werden alle Anbieter aus dem Pool entfernt, die bei den Berechnungen mit der Funktion tgGetCheapest berücksichtigt werden sollen. Anbieter werden dem Pool mit tgSetCheapestPool hinzugefügt. Deklaration Delphi

procedure tgClearCheapestPool;

C/C++

void tgClearCheapestPool();

Visual Basic

Sub tgClearCheapestPool()

Parameter

keine.

Rückgabe

keine.

Siehe auch

tgSetCheapestPool, tgGetCheapest

Version 2.5

51

TIGA API

tgSetCheapestPool Mit der Funktion tgSetCheapestPool kann festgelegt werden, welche Tarifmodelle bei der Berechnung des günstigsten Anbieters berücksichtigt werden sollen. Die Voreinstellung enthält alle Anbieter, die echtes Call-by-Call anbieten. Deklaration Delphi

procedure tgSetCheapestPool( modID : TModelID; usedIt : Boolean );

C/C++

void tgSetCheapestPool( TModelID modID, bool useIt );

Visual Basic

Sub tgSetCheapestPool( ByVal modID As Long, ByVal useIt As Boolean )

Parameter

modID [in] Der Parameter modID gibt das Tarifmodell eines Anbieters an, das bei den Berechnungen des günstigsten Anbieters berücksichtigt werden soll. useIt [in] Der Parameter useIt gibt an, ob das mit modID gewählte Tarifmodell eines Anbieters bei den Berechnungen des günstigsten Anbieters berücksichtigt werden soll (true) oder nicht (false).

Rückgabe

keine.

Siehe auch

tgClearCheapestPool

52

Version 2.5

Anhang

KAPITEL 5

Anhang

5.1 Kontakt SK-Software Schulzengasse 9 D-64291 Darmstadt Email: [email protected] Fax: 06151-93344-20

5.2 Formulare 5.2.1 TIGA Fehler Report Falls ein Fehler oder eine Unstimmigkeit bei der Arbeit mit TIGA API auftreten sollte, schicken Sie bitte diesen Fehlerbericht an den Support

5.2.2 Firmenname Name _________________________________________________________________________ Telefonnummer _________________________________________________________________ Faxnummer ____________________________________________________________________ TIGA API Lizenznummer __________________________________________________________ TIGA API Version________________________________________________________________ Entwicklungssystem / Version / ServicePack __________________________________________ Betriebssystem / Version / ServicePack ______________________________________________ Problembeschreibung ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________ ______________________________________________________________________________

Version 2.5

53

TIGA API

5.2.3 Bestellung ...

54

Version 2.5

Anhang

Version 2.5

55

TIGA API

56

Version 2.5

Index

Index

N Name 18 Netzkennzahl 7 NKZ 7, 17, 18 NKZPrefix 17

A Anbieter 7 Anmelden 7

B

P Preise 8 Preselection 8 Provider 8

Borland Delphi 9

R C Call-by-Call 7 Echtes 7 CountryId 16 countryInfo 17 countryName 16 countryNameShort 16 currency 17

D dialCode 17 Direktwahlverfahren 7 DLL 9

E eurorate 17

G Gespräch 7 Gesprächskosten 7

H hotline 18

I ID 18

K Kosten 7

L LocalServer 9

M Microsoft Visual Basic 9 Microsoft Visual C++ 9 Modell 7

Version 2.5

referenceModel 17 RemoteServer 9

T Tarifmodell 8 Tarifzone 8 TCostRec 20 TCountryID 15 TCountryRec 15 tg ClearCheapestPool 51 ConnectToLocalServer 24 ConnectToNovellServer 26 ConnectToNTServer 25 ConnectViaIP 27 DisconnectFromServer 28 Done 23 GetCheapest 48 GetCheapestinPeriod 49 GetCityName 46 GetCost 47 GetCountry 30 GetModel 38 GetProvider 34 GetProviderFromModelID 41 GetTakt 43 GetZone 42 Init 22 IsValidLocation 45 IsValidPhoneNumber 44 ModelFindFirst 39 ModelFindNext 40 ProviderFindFirst 35 ProviderFindNext 36 SetCheapestPool 52 SetCountry 29 SetDate 33 SetLocation 31 SetPreselect 32 SetPreselection 17 SetProviderFilter 37 TIGA 8 Controller 8

57

TIGA API

Proofer 8 Tarif 8 Tarifdatenbank 8 Tarifserver 8 TModelRec 18 TProviderRec 17 TZoneRec 19, 42

V vat 17 Vis-a-Vis-Tarife 13

W www 18

58

Version 2.5