Autor: Alexander
Berger
Headerdatei: imsourcemodule.h
Prototyp
Retcode_t MODULE_FUNCTION
IMGetFirstMessageSource(
Char_t* appType,
Char_t* platform,
PHEnum_t iterator,
Char_t* sourceName,
Char_t* subAddress );
Kurzbeschreibung
Das IMS System ruft diese Funktion auf, wenn alle Quellen des
Moduls ermittelt werden sollen. Auf diesen Aufruf folgt jeweils IMGetNextMessageSource, um die weiteren Quellen zu ermitteln. Das Modul
erhält mit dieser Funktion die Möglichkeit, interne
iterationsspezifische Daten zu initialisieren und diese im
Parameter 'iterator' zu speichern. Der 'iterator'-Parameter wird
vom IMS bei allen weiteren Aufrufen der Funktion IMGetNextMessageSource übergeben.
Parameter
appType - Der Anwendungstyp (Zeichenkette), für den die
Quellen ermittelt werden sollen. Jede Anwendung besitzt einen
eindeutigen Typ. Wird ein Modul für mehrere Anwendungen
verwendet, kann es mit diesem Parameter diese unterscheiden.
platform - Zeichenkette, welche die Plattform der Anwendung enthält. Das Modul hat damit die Möglichkeit, für jede Plattform andere Quellen zu definieren.
iterator - Zeiger auf eine Variable vom Typ HEnum_t. Das Modul kann diese Variable als 'Merker' für die Iterationsdaten verwendet, indem es z.B. einen Zeiger auf bestimmte, iterationsspezifische Daten in diese Variable schreibt. ACHTUNG: HEnum_t ist ein 32-Bit-Wert und kann daher entweder als 32-Bit Zahl oder als Zeiger verwendet werden. Auf keinen Fall dürfen längere Daten in diese Variable geschrieben werden.
sourceName - Puffer, der eine Zeichenkette von maximal STRING_NAME_LENGTH Zeichen aufnehmen kann. In diesen Puffer muß das Modul einen für den Benutzer lesbaren Bezeichner für die aktuelle Quelle kopieren.
subAddress - Puffer, der eine Zeichenkette von maximal STRING_NAME_LENGTH-Zeichen aufnehmen kann. In diesen Puffer muß das Modul eine interne Adresse für die aktuelle Quelle kopieren. Falls die Anwendung eine Nachricht weiterleitet, wird diese interne Adresse verwendet, um die Quelle zu bezeichnen.
Rückgabewert:
Wenn eine Quelle eingetragen wurde, muß RC_SUCCESS
zurückgegeben werden. Wenn keine Quellen vorhanden sind (z.B.
bei Modulen mit einer dynamischen Anzahl von Quellen), muß
RC_NO_DATA zurückgegeben werden. Ansonsten wird einer der
definierten Fehlercodes erwartet.
Anmerkungen:
Keine