CXI-Basis-Programmierreferenz / Noch zu dokumentieren /

Modulversionen (Text)

Modulversionen (Text)

CXI-Basis: Neue Funktionen in der Version 2.10 63 vom 14.12.1998



E r w e i t e r t e   V e r s i o n s a b f r a g e

Die erweiterte Versionsabfrage liefert Versionsinformationen zu
CXI-Dateien (in der Regel EXE- oder DLL-Dateien).

Die Abfrage geschieht, indem ein bestimmter Kennstring in den
Dateien gesucht wird. Dadurch muessen die Dateien nicht geladen
werden, was auch Abfragen betriebssystemfremder DLLs und nicht
konfigurierter Kommunikationstreiber erlaubt.

Die erweiterte Versionsabfrage existiert in drei Varianten:

- Stringvariante (Puffer):
  cxiQueryModuleVersionsStr (fnmask, options, targetbuffer)

- Dateivariante (Dateiname):
  cxiQueryModuleVersionsFile (fnmask, options, targetfname)

- Callbackvariante (Funktion):
  cxiQueryModuleVersions (fnmask, options, cbfunc, cargo)


Die Versionskennung einer Datei hat die Form
  MODULNAME Version (Build)

'MODULNAME' ist der interne Name der Linkeinheit, meistens ist dieser
identisch mit dem Dateinamen ohne Extension (1 bis 8 Zeichen).

'Version' ist die Versionsnummer, die meistens die Form 'x.yy zz' hat,
wobei 'x.yy' die Hauptversionsnummer und 'zz' die Unterversionsnummer
ist. Es ist nicht immer erforderlich, dass alle Dateien die gleiche
Hauptversionsnummer besitzen.

'(Build)' ist eine beim Erstellen der Dateien automatisch vergebene
eindeutige Kennung. Sie besteht aus einer beliebigen Zeichenfolge in
runden Klammern. Bei einer Releaseversion ist die Kennung eine Zahl
(Buildnummer, z.B. '(1186)'), bei Zwischenversionen kann eine
Unterbuildnummer folgen (z.B. '(1176.T45)'). Bei Dateien, die nicht
vom Buildvorgang generiert werden (z.B. Resourcedateien), ist eine
manuell vergebene eindeutige Kennung angegeben (z.B. '(LR-015)').



S t r i n g v a r i a n t e

CxiError cxiQueryModuleVersionsStr (const char *fnmask,
                                    CxiLong options,
                                    char *targetbuffer)

Parameter:

  fnmask:        Zu untersuchende Dateien
                 (Maske mit Jokerzeichen, z.B. "*.*")

  options:       Optionen, zur Zeit definiert sind
                 options == 1:  Deutsche Modulbeschreibungen
                 options == 0:  Englische Modulbeschreibungen

  targetbuffer:  Puffer fuer die Ausgabe der Funktion
                 (ca. 128 Byte pro gefundener Datei)

Return:

  0 = ok, sonst Fehler


Der Zielpuffer enthaelt nach dem Aufruf pro gefundener Versionskennung
einen Eintrag in der Form
  Dateiname,MODULNAME Version (Build),Beschreibung;

Dateien ohne Versionskennung werden nicht beruecksichtigt.



D a t e i v a r i a n t e

CxiError cxiQueryModuleVersionsFile (const char *fnmask,
                                     CxiLong options,
                                     const char *targetfname)

Parameter:

  fnmask:        Zu untersuchende Dateien
                 (Maske mit Jokerzeichen, z.B. "*.*")

  options:       Optionen, zur Zeit definiert sind
                 options == 1:  Deutsche Modulbeschreibungen
                 options == 0:  Englische Modulbeschreibungen

  targetfname:   Name der Zieldatei fuer die Ausgabe der Funktion

Return:

  0 = ok, sonst Fehler


Die Zieldatei wird angelegt und enthaelt nach dem Aufruf pro gefundener
Versionskennung eine Zeile in der Form
  Dateiname     MODULNAME Version (Build)      Beschreibung
  (16 Zeichen)  (32 Zeichen)                   (Rest bis Zeilenende)

Fuer Dateien, die nicht geoeffnet werden koennen oder keine Versionskennung
enthalten, wird eine Zeile in folgender Form generiert:
  Dateiname                                    <<< Fehlertext >>>
  (16 Zeichen)  (32 Leerzeichen)               (Rest bis Zeilenende)



C a l l b a c k v a r i a n t e

CxiError cxiQueryModuleVersions (const char *fnmask,
                                 CxiLong options,
                                 CxiModVersWriteFunc wrtfn,
                                 void *cargo)

Parameter:

  fnmask:        Zu untersuchende Dateien
                 (Maske mit Jokerzeichen, z.B. "*.*")

  options:       Optionen, zur Zeit definiert sind
                 options == 1:  Deutsche Modulbeschreibungen
                 options == 0:  Englische Modulbeschreibungen

  wrtfn:         Adresse der Callbackfunktion

  cargo:         Benutzerdefinierter Parameter
                 (wird der Callback-Funktion uebergeben)

Return:

  0 = ok, sonst Fehler


Die Callbackfunktion hat folgenden Aufbau:

int CXIGLOBALFUNC wrtfn (int what,
                         const char *fname,
                         const char *vstr,
                         const char *dstr,
                         void *cargo);


Der Parameter what gibt den Grund des Aufrufs an:
  what < 0   Fehler
  what > 0   Versionskennung gefunden


Parameter im Fehlerfall (what < 0):

  what:          Art des Fehlers:    -1  Dateizugriffsfehler
                                     -2  Datei ohne Versionskennung

  fname:         Name der Datei ohne Pfad

  vstr:          Leer ("")

  dstr:          Fehlerbeschreibung im Format "<<< Text >>>"

  cargo:         Benutzerdefinierter Parameter


Parameter im Erfolgsfall (what > 0):

  what:          Laufende Nummer pro Datei:  1 erste Kennung in dieser Datei
                                             2 zweite Kennung in dieser D.
                                             3 dritte Kennung  u.s.w.
                 (in der Regel enthalten die Dateien nur je eine Kennung)

  fname:         Name der Datei ohne Pfad

  vstr:          Versionskennung im Format "MODULNAME Version (Build)"

  dstr:          Modulbeschreibung

  cargo:         Benutzerdefinierter Parameter


Return:

  Der Rueckgabewert wird zur Zeit nicht verwendet und muss 0 sein.


Beispiel fuer die allgemeine Variante mit Callback-Funktion:

----------------------------------------------------------------------------

// MODVEXMP.C/CPP - MODVERS Example - Beispiel fuer 'cxiQueryModuleVersions'

#include <stdio.h>
#include <string.h>
#include "cxib.h"

#define TARGETSIZE  16384


// *** Callback-Funktion ***

int CXIGLOBALFUNC myStringWriteFunc
                    (int what, const char *fname, const char *vstr,
                     const char *dstr, void *cargo)
{
  // Parameter bei what < 0 (Fehler):
  //     what    Art des Fehlers:    -1  Dateizugriffsfehler
  //                                 -2  Datei ohne Versionskennung
  //     fname   Name der Datei ohne Pfad
  //     vstr    Leer ("")
  //     dstr    Fehlerbeschreibung im Format "<<< Text >>>"
  //     cargo   Benutzerdefinierter Parameter
  //
  // Parameter bei what > 0 (Kennung gefunden):
  //     what    Laufende Nummer pro Datei:  1 erste Kennung in dieser Datei
  //                                         2 zweite Kennung in dieser D.
  //                                         3 dritte Kennung  u.s.w.
  //               (in der Regel enthalten alle Dateien nur je eine Kennung)
  //     fname   Name der Datei ohne Pfad
  //     vstr    Versionskennung im Format "MODULNAME Version (Build)"
  //     dstr    Modulbeschreibung
  //     cargo   Benutzerdefinierter Parameter
  //
  if (what > 0)
  {
    char *target = (char *) cargo;
    int len = strlen (target);
    if (len < TARGETSIZE - 110)
      sprintf (target + len,
        "%-16.16s%-32.32s%.60s\n", fname, vstr, dstr);
  }
  return 0;
}


// *** Main-Funktion ***

int main (int argc, char **argv)
{
  if (argc != 2)
  {
    printf ("Usage:  MODVEXMP <filespec>\n");
    return 1;
  }
  else
  {
    static char target [TARGETSIZE];
    *target = 0;

    cxiQueryModuleVersions (argv [1], 1, myStringWriteFunc, target);
    // Erster Parameter        Zu untersuchende Dateien (Maske, z.B. "*.*")
    // Zweiter Parameter = 1:  Deutsche Modulbeschreibungen
    //                     0:  Englische Modulbeschreibungen
    // Dritter Parameter       Callback-Funktion
    // Vierter Parameter       Benutzerdefinierter Parameter
    //                         (wird der Callback-Funktion uebergeben)

    printf ("%s", target);
    return 0;
  }
}


// MODVEXMP.C/CPP - Ende

----------------------------------------------------------------------------