home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / tools / libs / zconnectlib5_0 / developer / autodocs / zconnect.doc < prev   
Encoding:
Text File  |  1998-02-15  |  30.1 KB  |  953 lines
  1. TABLE OF CONTENTS
  2.  
  3. zconnect.library/--announce--
  4. zconnect.library/ZCon_AppendHeaderLine
  5. zconnect.library/ZCon_ASCII2QP
  6. zconnect.library/ZCon_CheckHeader
  7. zconnect.library/ZCon_CheckRoute
  8. zconnect.library/ZCon_CreateDate
  9. zconnect.library/ZCon_CreateHeader
  10. zconnect.library/ZCon_CreateID
  11. zconnect.library/ZCon_FreeHeader
  12. zconnect.library/ZCon_GetDate
  13. zconnect.library/ZCon_GetHeader
  14. zconnect.library/ZCon_GetHeaderLineContents
  15. zconnect.library/ZCon_GetZConStr
  16. zconnect.library/ZCon_HeaderToIBM
  17. zconnect.library/ZCon_HeaderToISO
  18. zconnect.library/ZCon_NewCreateID
  19. zconnect.library/ZCon_QP2ASCII
  20. zconnect.library/ZCon_RemHeaderLines
  21. zconnect.library/ZCon_RenameHeaderLines
  22. zconnect.library/ZCon_StringToIBM
  23. zconnect.library/ZCon_StringToISO
  24. zconnect.library/ZCon_WriteHeader
  25. zconnect.library/--announce--                   zconnect.library/--announce--
  26.  
  27.    TITLE
  28.        zconnect.library
  29.  
  30.    VERSION
  31.        5.0
  32.  
  33.    RELEASE DATE
  34.        15.02.1998
  35.  
  36.    DESCRIPTION
  37.        zconnect.library is a shared library for easy processing of headers
  38.        of so called ZConnect message buffers. It also offers several support
  39.        functions, such as functions for creating date strings or message
  40.        IDs.
  41.  
  42.        For those who don't know what ZConnect is: ZConnect is a format like
  43.        the one specified in RFC 822 ("Standard for the format of ARPA
  44.        internet text messages") - but simply another ;)
  45.  
  46.        Please note that the definitions of ZConnect are currently only
  47.        German, that's why the documentation of zconnect.library is German,
  48.        too.
  49.  
  50.    SPECIAL REQUIREMENTS
  51.        OS 2.04+
  52.  
  53.    AVAILABILITY
  54.        http://home.pages.de/~bZ
  55.        ftp://ftp.wustl.edu/pub/aminet/comm/misc/bZ_ZConnectLib.lha
  56.  
  57.    PRICE
  58.        Freeware
  59.        Please read the additional License.txt document for further details.
  60.  
  61.    AUTHOR
  62.        Maik "BLiZZeR" Schreiber <BLiZZeR@dame.de>
  63.        http://home.pages.de/~bZ
  64.  
  65.    DISTRIBUTION
  66.        Please read the additional License.txt document for further details.
  67. zconnect.library/ZCon_AppendHeaderLine zconnect.library/ZCon_AppendHeaderLine
  68.  
  69.    NAME
  70.        ZCon_AppendHeaderLine -- Fügt eine Headerzeile an.
  71.  
  72.    SYNOPSIS
  73.        line = ZCon_AppendHeaderLine(list, id, contents)
  74.        D0                           A0    A1  A2
  75.  
  76.        struct ZConnectHeaderLine *ZCon_AppendHeaderLine(struct List *,
  77.            STRPTR, STRPTR);
  78.  
  79.    FUNCTION
  80.        Diese Funktion hängt eine Headerzeile an einen ZConnect-Header an.
  81.  
  82.    INPUTS
  83.        list     - Zeiger auf die List-Struktur des Headers
  84.        id       - Kennung der anzuhängenden Headerzeile (z.B. "ABS")
  85.                   *ohne* ":"
  86.        contents - Inhalt der anzuhängenden Headerzeile oder NULL
  87.  
  88.    RESULT
  89.        line     - Zeiger auf die ZConnectHeaderLine-Struktur der ange-
  90.                   hängten Headerzeile oder NULL im Fehlerfall
  91.  
  92.    NOTES
  93.        Die Elemente zhl_ID und zhl_Contents der ZConnectHeaderLine-Struktur
  94.        werden mittels AllocVec() angelegt. Sollen sie programmtechnisch
  95.        verändert werden, ist der Speicherbereich einfach mittels FreeVec()
  96.        freizugeben und ein neuer mittels AllocVec() zu allokieren. Die
  97.        Adresse wird dann wieder in der Struktur abgelegt.
  98.  
  99.        Ein eventueller Doppelpunkt am Ende von id wird abgetrennt.
  100.  
  101.        Eventuelle führende Whitespaces am Anfang von contents werden
  102.        abgetrennt.
  103.  
  104.        Die Headerzeilen werden mittels Enqueue() an die Liste gehängt,
  105.        das Feld zhl_ListNode.ln_Pri der ZConnectHeaderLine-Struktur kann
  106.        also benutzt werden.
  107.  
  108.        Ab V2 kann für contents auch NULL übergeben werden, der Inhalt der
  109.        Headerzeile ist dann leer ("").
  110.  
  111.    BUGS
  112.        Frühere Versionen akzeptierten keinen Leerstring ("") für contents.
  113.        Dies wurde in V2 behoben. Workaround: " " oder "\t" für contents
  114.        übergeben.
  115.  
  116.    SEE ALSO
  117.        ZCon_RemHeaderLines(), exec.library/Enqueue()
  118. zconnect.library/ZCon_ASCII2QP                 zconnect.library/ZCon_ASCII2QP
  119.  
  120.    NAME
  121.        ZCon_ASCII2QP -- Konvertiert ASCII zu Quoted-Printable. (V5)
  122.  
  123.    SYNOPSIS
  124.        count = ZCon_ASCII2QP(source, dest)
  125.        D0                    A1      A2
  126.  
  127.        ULONG ZCon_ASCII2QP(STRPTR, STRPTR);
  128.  
  129.    FUNCTION
  130.        Diese Funktion konvertiert alle Normalzeichen in einem String in
  131.        Quoted-Printable-Zeichen (z.B. "ß" für "=DF").
  132.  
  133.    INPUTS
  134.        source - Zeiger auf einen String mit normalen Zeichen
  135.        dest   - Zeiger auf den Zielpuffer, der den konvertierten String auf-
  136.                 nehmen soll. Der Puffer muß mind. 3x so groß wie source sein
  137.                 (inkl. 0-Byte).
  138.  
  139.    RESULT
  140.        count  - Anzahl der Zeichen, die dest nach der Konvertierung enthält
  141.  
  142.    EXAMPLE
  143.        UBYTE source[100] = "äöüÄÖÜß";
  144.        UBYTE dest[100];
  145.        ULONG len;
  146.  
  147.        len = ZCon_ASCII2QP(source, dest);
  148.  
  149.        /* Ausgabe: "=E4=F6=FC=C4=D6=DC=DF (21)" */
  150.        printf("%s (%lu)\n", dest, len);
  151.  
  152.    NOTES
  153.        Der konvertierte String wird mit einem 0-Byte abgeschlossen.
  154.  
  155.        Es werden alle Zeichen außer ASCII 32-127 konvertiert.
  156.  
  157.    SEE ALSO
  158.        ZCon_QP2ASCII()
  159. zconnect.library/ZCon_CheckHeader           zconnect.library/ZCon_CheckHeader
  160.  
  161.    NAME
  162.        ZCon_CheckHeader -- Checkt einen kompletten ZConnect-Header.
  163.  
  164.    SYNOPSIS
  165.        error = ZCon_CheckHeader(list)
  166.        D0                       A0
  167.  
  168.        ULONG ZCon_CheckHeader(struct List *);
  169.  
  170.    FUNCTION
  171.        Diese Funktion überprüft einen kompletten ZConnect-Header.
  172.        Dabei werden die folgenden Checks durchgeführt:
  173.  
  174.        - Alle Pflicht-Headerzeilen müssen auftreten.
  175.          Befindet sich eine Pflicht-Headerzeile nicht im Header, gibt die
  176.          Funktion ZCCHECK_NO_xxx zurück, wobei xxx der Kennung der im
  177.          Header fehlenden Headerzeile entspricht.
  178.  
  179.        - Alle Headerzeilen, die nur einmal auftreten dürfen, werden
  180.          überprüft.
  181.          Befindet sich eine Headerzeilen-Kennung mehrfach im Header, gibt
  182.          die Funktion ZCCHECK_TOO_MANY_xxx zurück, wobei xxx der Kennung
  183.          der im Header mehrfach auftretenden Headerzeile entspricht.
  184.  
  185.        - Die Inhalte der Headerzeilen EDA, DDA, LDA, O-EDA und SPERRFRIST
  186.          werden überprüft.
  187.          Entsprechen die Inhalte nicht der Definition in der ZConnect-Doku-
  188.          mentation, gibt die Funktion je nach Kennung ZCCHECK_WRONG_EDA,
  189.          ZCCHECK_WRONG_DDA, ZCCHECK_WRONG_LDA, ZCCHECK_WRONG_O_EDA bzw.
  190.          ZCCHECK_WRONG_SPERRFRIST zurück.
  191.  
  192.        - Die Inhalte der Headerzeilen LEN und KOM werden geprüft, wobei
  193.          KOM eine Zahl enthalten muß, die kleiner oder gleich der Zahl
  194.          in LEN ist. Für beide ist der Wert 0 erlaubt.
  195.          Enthält die Headerzeile LEN keine reine Zahl oder ist diese
  196.          Zahl kleiner als die Zahl in der Headerzeile KOM, gibt die
  197.          Funktion ZCCHECK_WRONG_LEN zurück. Enthält die Headerzeile KOM
  198.          keine reine Zahl, gibt die Funktion ZCCHECK_WRONG_KOM zurück.
  199.  
  200.        - Der Inhalt der Headerzeile PRIO wird überprüft.
  201.          Enthält diese nicht "0", "10" oder "20", gibt die Funktion
  202.          ZCCHECK_WRONG_PRIO zurück.
  203.  
  204.    INPUTS
  205.        list  - Zeiger auf die List-Struktur des zu überprüfenden ZConnect-
  206.                Headers
  207.  
  208.    RESULT
  209.        error - ZCCHECK_OK, wenn der Header in Ordnung ist, sonst eine der
  210.                Fehlermeldungen ZCCHECK_xxx
  211.  
  212.    NOTES
  213.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  214.  
  215.        Unbekannte Headerzeilen-Kennungen, die nicht mit dem in der
  216.        ZConnect-Dokumentation definierten Präfix "X-" beginnen, werden
  217.        nicht als unbekannt erkannt, da die Weiterentwicklung von ZConnect
  218.        derzeit nicht geklärt ist. Für weitere Fragen ist die Newsgroup
  219.        de.comm.protocols.zconnect von Interesse.
  220.  
  221.        Folgende Headerzeilen werden erst ab V2 überprüft:
  222.  
  223.          CONTROL: ADD      -----.
  224.          CONTROL: CANCEL        |
  225.          CONTROL: DEL           |
  226.          STAT: AUTO             |
  227.          STAT: CTL              |-- dürfen jeweils nur einmal auftreten
  228.          STAT: EB               |
  229.          STAT: NOCIPHER         |
  230.          STAT: NOKOP            |
  231.          STAT: TRACE       -----'
  232.  
  233.        Eventuell werden in Zukunft noch weitere Fehlermeldungen implemen-
  234.        tiert.
  235.  
  236.    SEE ALSO
  237.        <libraries/zconnect.h>,
  238.        ZConnect-Dokumentation (Kapitel "Datumsangaben")
  239. zconnect.library/ZCon_CheckRoute             zconnect.library/ZCon_CheckRoute
  240.  
  241.    NAME
  242.        ZCon_CheckRoute -- Findet ein System in einem Routepfad. (V3)
  243.  
  244.    SYNOPSIS
  245.        count = ZCon_CheckRoute(route, system)
  246.        D0                      A1     A2
  247.  
  248.        ULONG ZCon_CheckRoute(STRPTR, STRPTR);
  249.  
  250.    FUNCTION
  251.        Diese Funktion stellt fest, wie oft ein bestimmter Systemname (inkl.
  252.        Domain) in einem Routepfad auftritt.
  253.  
  254.    INPUTS
  255.        route  - der zu durchsuchende Routepfad
  256.        system - das zu suchende System (evtl. inkl. Domain)
  257.  
  258.    RESULT
  259.        count  - Anzahl der Auftreten des zu suchenden Systemnamen
  260.  
  261.    EXAMPLE
  262.        /* dies liefert "1" */
  263.        printf("%lu\n", ZCon_CheckRoute("a!b!c", "b"));
  264.  
  265.        /* dies liefert auch "1" */
  266.        printf("%lu\n", ZCon_CheckRoute("a!b!c", "B"));
  267.  
  268.        /* dies liefert ebenfalls "1" */
  269.        printf("%lu\n", ZCon_CheckRoute("a!bc!B!cb!b.do.main!c", "b"));
  270.  
  271.    NOTES
  272.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  273.  
  274.        Systeme werden nur gefunden, wenn sie wie im Routepfad angegeben
  275.        werden. Zum Beispiel wird das System "ABC" niemals gefunden, wenn es
  276.        im Routepfad nur als "ABC.de" auftritt.
  277.  
  278.    BUGS
  279.        Bis einschließlich V4 wurde durch einen Fehler in der LVO-Tabelle der
  280.        Library anstatt dieser Funktion die Funktion ZCon_CreateHeader() auf-
  281.        gerufen. Dies ist in V5 behoben. Workaround: Explizit V5 öffnen.
  282.  
  283.    SEE ALSO
  284.        ZConnect-Dokumentation (Kapitel "Rekursionscheck anhand des Route-
  285.        pfads (ROT)")
  286. zconnect.library/ZCon_CreateDate             zconnect.library/ZCon_CreateDate
  287.  
  288.    NAME
  289.        ZCon_CreateDate -- Erzeugt ZConnect-Datumsangabe. (V2)
  290.  
  291.    SYNOPSIS
  292.        ZCon_CreateDate(date, offset, summertime, buffer)
  293.                        A1    D0      D1          A2
  294.  
  295.        void ZCon_CreateDate(struct ClockData *, WORD, UBYTE, STRPTR);
  296.  
  297.    FUNCTION
  298.        Diese Funktion erzeugt eine Datumsangabe im ZConnect-Format. Dabei
  299.        wird das Offset zur GMT addiert.
  300.  
  301.    INPUTS
  302.        date       - Zeiger auf eine ClockData-Struktur, die die aktuelle
  303.                     Systemzeit enthält
  304.        offset     - zu addierendes Offset zur GMT in Minuten
  305.        summertime - ZC_SUMMERTIME, wenn ein "S" für Sommerzeit eingefügt
  306.                     werden soll; ZC_WINTERTIME, wenn ein "W" für Winterzeit
  307.                     eingefügt werden soll; ZC_IGNORE, wenn keine Sommer-/
  308.                     Winterzeit-Angabe eingefügt werden soll
  309.        buffer     - Zeiger auf einen Puffer, in den die Datumsangabe
  310.                     geschrieben werden soll (muß mind. 22 Bytes groß sein!)
  311.  
  312.    EXAMPLE
  313.        UBYTE             buffer[22];
  314.        struct DateStamp  ds;
  315.        struct ClockData  cd;
  316.        struct Locale    *loc;
  317.        WORD              offs = 0;
  318.  
  319.        DateStamp(&ds);
  320.        Amiga2Date((ULONG) ds.ds_Days * 86400 +
  321.                   (ULONG) ds.ds_Minute * 60 +
  322.                   (ULONG) ds.ds_Tick / TICKS_PER_SECOND,
  323.                   &cd);
  324.  
  325.        if (loc = OpenLocale(NULL))
  326.        {
  327.          offs = (WORD) loc->loc_GMTOffset;
  328.          CloseLocale(NULL);
  329.        }
  330.  
  331.        ZCon_CreateDate(&cd, offs, ZC_IGNORE, buffer);
  332.        ZCon_AppendHeaderLine(header, "EDA", buffer);
  333.  
  334.    NOTES
  335.        Das zu übergebende Offset muß immer genau dem negativen Wert aus der
  336.        ZConnect-Dokumentation entsprechen, da es addiert wird! Ist also die
  337.        MET mit +1:00 gegeben, muß -60 (-1:00) übergeben werden!
  338.  
  339.        Das korrekte Offset kann bspw. ohne Änderungen direkt aus einer
  340.        Locale-Struktur übernommen werden (s.o.).
  341.  
  342.    SEE ALSO
  343.        ZCon_GetDate()
  344. zconnect.library/ZCon_CreateHeader         zconnect.library/ZCon_CreateHeader
  345.  
  346.    NAME
  347.        ZCon_CreateHeader -- Erzeugt einen neuen ZConnect-Header. (V3)
  348.  
  349.    SYNOPSIS
  350.        header = ZCon_CreateHeader()
  351.        D0
  352.  
  353.        struct List *ZCon_CreateHeader(void);
  354.  
  355.    FUNCTION
  356.        Diese Funktion erzeugt einen neuen (leeren) ZConnect-Header, der
  357.        mittels ZCon_FreeHeader() wieder freigegeben werden muß.
  358.  
  359.        Diese Funktion hätte eigentlich schon seit V1 existieren müssen...
  360.  
  361.    RESULT
  362.        header - Zeiger auf die List-Struktur des erzeugten ZConnect-Headers
  363.                 oder NULL im Fehlerfall
  364.  
  365.    EXAMPLE
  366.        struct List *header;
  367.  
  368.        if (header = ZCon_CreateHeader())
  369.        {
  370.          ZCon_AppendHeaderLine(header, "ABS", "BLiZZeR@dame.de");
  371.          ZCon_AppendHeaderLine(header, "EMP", "user@host.do.main");
  372.  
  373.          ZCon_WriteHeader(handle, header);
  374.  
  375.          ZCon_FreeHeader(header);
  376.        }
  377.  
  378.    SEE ALSO
  379.        ZCon_FreeHeader()
  380. zconnect.library/ZCon_CreateID                 zconnect.library/ZCon_CreateID
  381.  
  382.    NAME
  383.        ZCon_CreateID -- Erzeugt einzigartige ID. (V2) (OBSOLETE)
  384.  
  385.    SYNOPSIS
  386.        id = ZCon_CreateID(string)
  387.        D0                 A1
  388.  
  389.        ULONG ZCon_CreateID(STRPTR);
  390.  
  391.    FUNCTION
  392.        Diese Funktion erzeugt eine einzigartige ID, die z.B. als Message-ID
  393.        für ZConnect-Nachrichten verwandt werden kann.
  394.  
  395.    INPUTS
  396.        string - Ein beliebiger String, der zur Erzeugung der ID herangezogen
  397.                 wird. Hier kann z.B. die Adresse des Absenders übergeben
  398.                 werden.
  399.  
  400.    RESULT
  401.        id     - die erzeugte ID
  402.  
  403.    EXAMPLE
  404.        UBYTE  buffer[256];
  405.        STRPTR abs,
  406.               emp;
  407.  
  408.        abs = "BLiZZeR@dame.de";
  409.        emp = "user@host.do.main";
  410.  
  411.        ZCon_AppendHeaderLine(header, "ABS", abs);
  412.        ZCon_AppendHeaderLine(header, "EMP", emp);
  413.  
  414.        /* erzeugen einer weltweit einmaligen Message-ID */
  415.        sprintf(buffer, "%lx%lx%s",
  416.                ZCon_CreateID(abs),
  417.                ZCon_CreateID(emp),
  418.                strchr(abs, '@'));
  419.        ZCon_AppendHeaderLine(header, "MID", buffer);
  420.  
  421.    NOTES
  422.        Die ID wird mittels einer Hashfunktion erzeugt, die von der aktuellen
  423.        Systemzeit, dem übergebenen String sowie dem Rückgabewert der Funk-
  424.        tion GetUniqueID() der utility.library abhängig ist.
  425.  
  426.        Die Wahrscheinlichkeit, daß jemals die gleiche ID erzeugt wird, ist
  427.        daher nahezu 0.
  428.  
  429.        Bitte benutzen Sie ZCon_NewCreateID() statt dieser Funktion, da sie
  430.        einen besseren Algorithmus verwendet.
  431.  
  432.    SEE ALSO
  433.        ZCon_NewCreateID()
  434. zconnect.library/ZCon_FreeHeader             zconnect.library/ZCon_FreeHeader
  435.  
  436.    NAME
  437.        ZCon_FreeHeader -- Gibt kompletten ZConnect-Header frei.
  438.  
  439.    SYNOPSIS
  440.        ZCon_FreeHeader(list)
  441.                        A0
  442.  
  443.        void ZCon_FreeHeader(struct List *);
  444.  
  445.    FUNCTION
  446.        Diese Funktion gibt einen kompletten ZConnect-Header frei, der mit
  447.        ZCon_CreateHeader() oder ZCon_GetHeader() angelegt wurde.
  448.  
  449.    INPUTS
  450.        list - Zeiger auf die List-Struktur des freizugebenden ZConnect-
  451.               Headers oder NULL
  452.  
  453.    EXAMPLE
  454.        list = ZCon_GetHeader(handle);
  455.  
  456.        /* ... */
  457.  
  458.        ZCon_FreeHeader(list);
  459. zconnect.library/ZCon_GetDate                   zconnect.library/ZCon_GetDate
  460.  
  461.    NAME
  462.        ZCon_GetDate -- Liest Datum aus ZConnect-Datumsangabe aus. (V2)
  463.  
  464.    SYNOPSIS
  465.        offset = ZCon_GetDate(buffer, date, summertime)
  466.        D0                    A1      A2    A3
  467.  
  468.        WORD ZCon_GetDate(STRPTR, struct ClockData *, UBYTE *);
  469.  
  470.    FUNCTION
  471.        Diese Funktion liest ein Datum aus einer ZConnect-Datumsangabe.
  472.  
  473.    INPUTS
  474.        buffer     - Zeiger auf einen Puffer, der eine gültige ZConnect-
  475.                     Datumsangabe enthält
  476.        date       - Zeiger auf eine ClockData-Struktur, die das ausgelesene
  477.                     Datum aufnehmen soll (es werden *alle* Elemente der
  478.                     Struktur korrekt gesetzt)
  479.        summertime - Zeiger auf ein UBYTE, das die Sommer-/Winterzeit-Angabe
  480.                     aufnehmen soll (ZC_WINTERTIME, wenn ein "W" für Winter-
  481.                     zeit angegeben war; ZC_SUMMERTIME, wenn ein "S" für
  482.                     Sommerzeit angegeben war; ZC_IGNORE, wenn keines der
  483.                     beiden angegeben war)
  484.  
  485.  
  486.    RESULT
  487.        offset     - das in der Datumsangabe angegebene Offset in Minuten
  488.  
  489.    EXAMPLE
  490.        WORD             offset;
  491.        struct ClockData cd;
  492.        UBYTE            summertime;
  493.  
  494.        offset = ZCon_GetDate("19970608212044S+2", &cd, &summertime);
  495.  
  496.        printf("%02u.%02u.%u %02u:%02u:%02u, ",
  497.               cd.mday, cd.month, cd.year, cd.hour, cd.min, cd.sec);
  498.        if (summertime != ZC_IGNORE)
  499.          printf("%szeit, ",
  500.                 (summertime == ZC_WINTERTIME) ? "Winter" : "Sommer");
  501.        printf("Offset: %d min\n", offset);
  502.  
  503.    SEE ALSO
  504.        ZCon_CreateDate()
  505. zconnect.library/ZCon_GetHeader               zconnect.library/ZCon_GetHeader
  506.  
  507.    NAME
  508.        ZCon_GetHeader -- Liest ZConnect-Header aus Datei.
  509.  
  510.    SYNOPSIS
  511.        list = ZCon_GetHeader(filehandle)
  512.        D0                    A1
  513.  
  514.        struct List *ZCon_GetHeader(BPTR);
  515.  
  516.    FUNCTION
  517.        Diese Funktion liest einen kompletten ZConnect-Header aus einer
  518.        Datei in eine List-Struktur. Die Nodes der List-Struktur entsprechen
  519.        nach dem Einlesen der Struktur ZConnectHeaderLine.
  520.  
  521.    INPUTS
  522.        filehandle - Zeiger auf das FileHandle der zu lesenden Datei
  523.  
  524.    RESULT
  525.        list       - Zeiger auf die List-Struktur, die mittels
  526.                     ZCon_FreeHeader() wieder freigegeben werden muß,
  527.                     oder NULL im Fehlerfall
  528.  
  529.    EXAMPLE
  530.        BPTR         handle;
  531.        struct List *list;
  532.  
  533.        handle = Open(filename, MODE_OLDFILE);
  534.        list = ZCon_GetHeader(handle);
  535.  
  536.        if (list)
  537.        {
  538.          /* Ausgeben aller Headerzeilen */
  539.          if (!IsListEmpty(list))
  540.          {
  541.            struct ZConnectHeaderLine *l =
  542.                (struct ZConnectHeaderLine *) list->lh_Head;
  543.  
  544.            do
  545.            {
  546.              printf("%s: %s\n", l->zhl_ID, l->zhl_Contents);
  547.              l = (struct ZConnectHeaderLine *) l->zhl_ListNode.ln_Succ;
  548.            }
  549.            while ((APTR) l != (APTR) &list->lh_Tail);
  550.          }
  551.        }
  552.  
  553.    NOTES
  554.        Die Elemente zhl_ID und zhl_Contents der ZConnectHeaderLine-Struktur
  555.        werden mittels AllocVec() angelegt. Sollen sie programmtechnisch
  556.        verändert werden, ist der Speicherbereich einfach mittels FreeVec()
  557.        freizugeben und ein neuer mittels AllocVec() zu allokieren. Die
  558.        Adresse wird dann wieder in der Struktur abgelegt.
  559.  
  560.        Das Einlesen der Headerzeilen geschieht mit FGets(). Es ist daher
  561.        darauf zu achten, nur gepufferte Ein-/Ausgabe (FRead()) zu benutzen.
  562.  
  563.        Das Element zhl_ID der ZConnectHeaderLine-Struktur enthält nur die
  564.        reine Headerzeilen-Kennung, also ohne den Doppelpunkt.
  565.  
  566.        Eventuell führende Whitespaces werden vom Element zhl_Contents der
  567.        ZConnectHeaderLine-Struktur abgetrennt.
  568.  
  569.        Die Elemente zhl_ID und zhl_Contents der ZConnectHeaderLine-Struktur
  570.        werden (bis auf die o.g. Änderungen) unverändert eingelesen.
  571.  
  572.        Der eingelesene Header wird nicht gecheckt.
  573.  
  574.    SEE ALSO
  575.        ZCon_HeaderToISO(), ZCon_CheckHeader(), dos.library/FRead(),
  576.        IsListEmpty()
  577. zconnect.library/ZCon_GetHeaderLineContentslibrary/ZCon_GetHeaderLineContents
  578.  
  579.    NAME
  580.        ZCon_GetHeaderLineContents -- Holt Inhalt einer Headerzeile.
  581.  
  582.    SYNOPSIS
  583.        contents = ZCon_GetHeaderLineContents(list, id, storage)
  584.  
  585.        STRPTR ZCon_GetHeaderLineContents(struct List *, STRPTR,
  586.            struct ZConnectHeaderLine **);
  587.  
  588.    FUNCTION
  589.        Diese Funktion holt den Inhalt einer Headerzeile aus einem ZConnect-
  590.        Header.
  591.  
  592.    INPUTS
  593.        list     - Zeiger auf die List-Struktur des zu untersuchenden
  594.                   ZConnect-Headers
  595.        id       - Kennung der zu suchenden Headerzeile *ohne* ":"
  596.        storage  - Zeiger auf einen Zeiger auf eine ZConnectHeaderLine-
  597.                   Struktur, der einen Zeiger auf eine ZConnectHeaderLine-
  598.                   Struktur zu weiteren Abarbeitung des Header aufnimmt
  599.                   (muß vor dem ersten Aufruf mit NULL initialisiert
  600.                   werden). Ist keine weitere Abarbeitung gewünscht, ist
  601.                   NULL zu übergeben.
  602.  
  603.    RESULT
  604.        contents - Zeiger auf das Element zhl_Contents der ZConnectHeader-
  605.                   Line-Struktur, in der die Kennung auftrat
  606.  
  607.    EXAMPLE
  608.        /* Ausgeben des Inhalts der ABS:-Headerzeile */
  609.        STRPTR c;
  610.  
  611.        c = ZCon_GetHeaderLineContents(list, "ABS", NULL);
  612.        if (c)
  613.          printf("Absender: %s\n", l);
  614.  
  615.  
  616.        /* Ausgeben aller EMP:-Headerzeilen */
  617.        STRPTR c;
  618.        struct ZConnectHeaderLine *store = NULL;
  619.  
  620.        while (c = ZCon_GetHeaderLineContents(list, "EMP", &store))
  621.          printf("Empfänger: %s\n", c);
  622.  
  623.    NOTES
  624.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  625. zconnect.library/ZCon_GetZConStr             zconnect.library/ZCon_GetZConStr
  626.  
  627.    NAME
  628.        ZCon_GetZConStr -- Holt String aus Locale-Catalog. (V3)
  629.  
  630.    SYNOPSIS
  631.        string = ZCon_GetZConStr(id)
  632.        D0                       D0
  633.  
  634.        STRPTR ZCon_GetZConStr(ULONG);
  635.  
  636.    FUNCTION
  637.        Diese Funktion holt einen String aus dem Locale-Catalog der
  638.        zconnect.library, der beim ersten Öffnen der Library automatisch
  639.        geladen wird.
  640.  
  641.    INPUTS
  642.        id     - die Nummer des gewünschten Strings im Catalog; die Rückgabe-
  643.                 werte von ZCon_CheckHeader() können hierbei direkt benutzt
  644.                 werden
  645.  
  646.    RESULT
  647.        string - Zeiger auf den String im Catalog (read-only!) oder NULL im
  648.                 Fehlerfall (kein Catalog vorhanden, locale.library konnte
  649.                 nicht geöffnet werden, gewünschter String nicht vorhanden
  650.                 usw.)
  651.  
  652.    EXAMPLE
  653.        ULONG error;
  654.  
  655.        if (error = ZCon_CheckHeader(header))
  656.        {
  657.          STRPTR text;
  658.  
  659.          if (text = ZCon_GetZConStr(error))
  660.            printf("%s.\n", text);
  661.          else
  662.            puts("Kein Fehlertext verfügbar.");
  663.        }
  664.        else
  665.          puts("Keine Fehler.");
  666.  
  667.    SEE ALSO
  668.        MailDemon.cd
  669. zconnect.library/ZCon_HeaderToIBM           zconnect.library/ZCon_HeaderToIBM
  670.  
  671.    NAME
  672.        ZCon_HeaderToIBM -- Wandelt Header in IBM-Umlaute.
  673.  
  674.    SYNOPSIS
  675.        ZCon_HeaderToIBM(list)
  676.                         A0
  677.  
  678.        void ZCon_HeaderToIBM(struct List *);
  679.  
  680.    FUNCTION
  681.        Diese Funktion wandelt alle ISO-8859-1-Umlaute eines ZConnect-
  682.        Headers in IBM-Umlaute um.
  683.  
  684.    INPUTS
  685.        list - Zeiger auf die List-Struktur des umzuwandelnden ZConnect-
  686.        Headers
  687.  
  688.    SEE ALSO
  689.        ZCon_HeaderToISO(), ZCon_StringToIBM()
  690. zconnect.library/ZCon_HeaderToISO           zconnect.library/ZCon_HeaderToISO
  691.  
  692.    NAME
  693.        ZCon_HeaderToISO -- Wandelt Header in ISO-8859-1-Umlaute.
  694.  
  695.    SYNOPSIS
  696.        ZCon_HeaderToISO(list)
  697.                         A0
  698.  
  699.        void ZCon_HeaderToISO(struct List *);
  700.  
  701.    FUNCTION
  702.        Diese Funktion wandelt alle IBM-Umlaute eines ZConnect-Headers in
  703.        ISO-8859-1-Umlaute um.
  704.  
  705.    INPUTS
  706.        list - Zeiger auf die List-Struktur des umzuwandelnden ZConnect-
  707.               Headers
  708.  
  709.    SEE ALSO
  710.        ZCon_HeaderToIBM(), ZCon_StringToISO()
  711. zconnect.library/ZCon_NewCreateID           zconnect.library/ZCon_NewCreateID
  712.  
  713.    NAME
  714.        ZCon_NewCreateID -- Erzeugt einzigartige ID. (V3)
  715.  
  716.    SYNOPSIS
  717.        success = ZCon_NewCreateID(string, buffer)
  718.        D0                         A1      A2
  719.  
  720.        BOOL ZCon_NewCreateID(STRPTR, STRPTR);
  721.  
  722.    IMPORTANT NOTE
  723.        Ab V4 muß der Puffer mindestens 33 Byte groß sein (s. BUGS)!
  724.  
  725.    FUNCTION
  726.        Diese Funktion erzeugt eine einzigartige ID, die z.B. als Message-ID
  727.        für ZConnect-Nachrichten verwandt werden kann.
  728.  
  729.    INPUTS
  730.        string  - Ein beliebiger String, der zur Erzeugung der ID herange-
  731.                  zogen wird. Hier kann z.B. die Adresse des Absenders über-
  732.                  geben werden.
  733.        buffer  - Zeiger auf einen Puffer, der die erzeugte ID aufnehmen soll
  734.                  (muß mind. 33 Byte groß sein!). Die ID wird mit einem 0-
  735.                  Byte abgeschlossen.
  736.  
  737.    RESULT
  738.        success - TRUE, wenn die ID erfolgreich erzeugt werden konnte, sonst
  739.                  FALSE (kein temporärer Speicher verfügbar)
  740.  
  741.    EXAMPLE
  742.        UBYTE  id[33];
  743.        STRPTR abs;
  744.  
  745.        abs = "BLiZZeR@dame.de";
  746.        ZCon_AppendHeaderLine("ABS", abs);
  747.  
  748.        if (ZCon_NewCreateID(abs, id))
  749.          ZCon_AppendHeaderLine("MID", id);
  750.  
  751.    NOTES
  752.        Die ID wird mittels des RSA Data Security, Inc., MD5 Message-Digest
  753.        Algorithm erzeugt, dessen Ergebnis von der aktuellen Systemzeit, dem
  754.        übergebenen String sowie dem Rückgabewert der Funktion GetUniqueID()
  755.        der utility.library abhängig ist.
  756.  
  757.        Die Wahrscheinlichkeit, daß jemals die gleiche ID erzeugt wird, ist
  758.        daher nahezu 0.
  759.  
  760.    BUGS
  761.        V3 erzeugte einen defekten Pufferinhalt. Dies ist in V4 behoben.
  762.        Workaround: Explizit V4 öffnen.
  763.  
  764.    SEE ALSO
  765.        ZCon_CreateID()
  766. zconnect.library/ZCon_QP2ASCII                 zconnect.library/ZCon_QP2ASCII
  767.  
  768.    NAME
  769.        ZCon_QP2ASCII -- Konvertiert Quoted-Printable zu ASCII. (V5)
  770.  
  771.    SYNOPSIS
  772.        count = ZCon_QP2ASCII(source, dest)
  773.        D0                    A1      A2
  774.  
  775.        ULONG ZCon_QP2ASCII(STRPTR, STRPTR);
  776.  
  777.    FUNCTION
  778.        Diese Funktion konvertiert alle Quoted-Printable-Zeichen (z.B. "=DF"
  779.        für "ß" usw.) in einem String in Normalzeichen.
  780.  
  781.    INPUTS
  782.        source - Zeiger auf einen String, der evtl. Quoted-Printable-Zeichen
  783.                 enthält
  784.        dest   - Zeiger auf den Zielpuffer, der den konvertierten String auf-
  785.                 nehmen soll. Die Größe muß mind. der von source entsprechen
  786.                 (inkl. 0-Byte)!
  787.  
  788.    RESULT
  789.        count  - Anzahl der Zeichen, die dest nach der Konvertierung tatsäch-
  790.                 lich enthält (nützlich bei "=00", was ja einem 0-Byte ent-
  791.                 spricht. strlen() wäre dann nämlich nutzlos.)
  792.  
  793.    EXAMPLE
  794.        UBYTE source[100] = "=E4=F6=FC=C4=D6=DC=DF";
  795.        UBYTE dest[100];
  796.        ULONG len;
  797.  
  798.        len = ZCon_QP2ASCII(source, dest);
  799.  
  800.        /* Ausgabe: "äöüÄÖÜß (7)" */
  801.        printf("%s (%lu)\n", dest, len);
  802.  
  803.    NOTES
  804.        Der konvertierte String wird mit einem 0-Byte abgeschlossen.
  805.  
  806.        Es werden nur die Quoted-Printable-Zeichen von "=00" bis "=FF"
  807.        konvertiert.
  808.  
  809.        Die Zeichen müssen als Großbuchstaben vorliegen! Zum Beispiel wird
  810.        "=DF" zu "ß" konvertiert, "=df" bleibt aber "=df".
  811.  
  812.    SEE ALSO
  813.        ZCon_ASCII2QP()
  814. zconnect.library/ZCon_RemHeaderLines     zconnect.library/ZCon_RemHeaderLines
  815.  
  816.    NAME
  817.        ZCon_RemHeaderLines -- Entfernt Headerzeilen aus einem Header. (V2)
  818.  
  819.    SYNOPSIS
  820.        ZCon_RemHeaderLines(list, id, all)
  821.                            A0    A1  D0
  822.  
  823.        void ZCon_RemHeaderLines(struct List *, STRPTR, BOOL);
  824.  
  825.    FUNCTION
  826.        Diese Funktion entfernt alle Headerzeilen eines ZConnect-Headers,
  827.        deren Kennung gleich der übergebenen Kennung ist.
  828.  
  829.    INPUTS
  830.        list - Zeiger auf die List-Struktur des zu bearbeitenden ZConnect-
  831.               Headers
  832.        id   - Kennung der Headerzeilen *ohne* ":", die entfernt werden
  833.               sollen (z.B. "O-ROT")
  834.        all  - TRUE, wenn alle Headerzeilen mit der richtigen Kennung ent-
  835.               fernt werden sollen, sonst FALSE (hier wird nach Entfernen der
  836.               ersten richtigen Headerzeile abgebrochen)
  837.  
  838.    EXAMPLE
  839.        /* alle Headerzeilen, deren Kennung "EB" ist, entfernen */
  840.        ZCon_RemHeaderLines(header, "EB", TRUE);
  841.  
  842.    NOTES
  843.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  844.  
  845.    SEE ALSO
  846.        ZCon_AppendHeaderLine()
  847. zconnect.library/ZCon_RenameHeaderLinesconnect.library/ZCon_RenameHeaderLines
  848.  
  849.    NAME
  850.        ZCon_RenameHeaderLines -- Benennt Headerzeilenkennungen um. (V2)
  851.  
  852.    SYNOPSIS
  853.        ZCon_RenameHeaderLines(list, id, newid, all)
  854.                               A0    A1  A2     D0
  855.  
  856.        void ZCon_RenameHeaderLines(struct List *, STRPTR, STRPTR, BOOL);
  857.  
  858.    FUNCTION
  859.        Diese Funktion benennt alle Headerzeilenkennungen eines ZConnect-
  860.        Headers in eine andere Kennung um.
  861.  
  862.    INPUTS
  863.        list  - Zeiger auf die List-Struktur des zu bearbeitenden ZConnect-
  864.                Headers
  865.        id    - Kennung der zu suchenden Headerzeilen *ohne* ":" (z.B. "ROT")
  866.        newid - neue Kennung *ohne* ":" (z.B. "O-ROT")
  867.        all   - TRUE, wenn alle Headerzeilen mit der richtigen Kennung umbe-
  868.                nannt werden sollen, sonst FALSE (hier wird nach Umbenennen
  869.                der ersten richtigen Headerzeile abgebrochen)
  870.  
  871.    EXAMPLE
  872.        ZCon_RenameHeaderLines(header, "EMP", "OEM", FALSE);
  873.  
  874.    NOTES
  875.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  876. zconnect.library/ZCon_StringToIBM           zconnect.library/ZCon_StringToIBM
  877.  
  878.    NAME
  879.        ZCon_StringToIBM -- Wandelt String in IBM-Umlaute.
  880.  
  881.    SYNOPSIS
  882.        ZCon_StringToIBM(string)
  883.                         A1
  884.  
  885.        void ZCon_StringToIBM(STRPTR);
  886.  
  887.    FUNCTION
  888.        Diese Funktion wandelt alle ISO-8859-1-Umlaute eines String IBM-
  889.        Umlaute um.
  890.  
  891.    INPUTS
  892.        string - Zeiger auf den umzuwandelnden String
  893.  
  894.    SEE ALSO
  895.        ZCon_StringToISO(), ZCon_HeaderToIBM()
  896. zconnect.library/ZCon_StringToISO           zconnect.library/ZCon_StringToISO
  897.  
  898.    NAME
  899.        ZCon_StringToISO -- Wandelt String in ISO-8859-1-Umlaute.
  900.  
  901.    SYNOPSIS
  902.        ZCon_StringToISO(string)
  903.                         A1
  904.  
  905.        void ZCon_StringToISO(STRPTR);
  906.  
  907.    FUNCTION
  908.        Diese Funktion wandelt alle IBM-Umlaute eines Strings in ISO-8859-1-
  909.        Umlaute um.
  910.  
  911.    INPUTS
  912.        string - Zeiger auf den umzuwandelnden String
  913.  
  914.    SEE ALSO
  915.        ZCon_StringToIBM(), ZCon_HeaderToISO()
  916. zconnect.library/ZCon_WriteHeader           zconnect.library/ZCon_WriteHeader
  917.  
  918.    NAME
  919.        ZCon_WriteHeader -- Schreibt ZConnect-Header in Datei.
  920.  
  921.    SYNOPSIS
  922.        ZCon_WriteHeader(list, filehandle)
  923.                         A0    A1
  924.  
  925.        void ZCon_WriteHeader(struct List *, BPTR);
  926.  
  927.    FUNCTION
  928.        Diese Funktion schreibt einen kompletten ZConnect-Header in eine
  929.        Datei.
  930.  
  931.    INPUTS
  932.        list       - Zeiger auf die List-Struktur des zu schreibenden
  933.                     ZConnect-Headers
  934.        filehandle - Zeiger auf das FileHandler der Datei
  935.  
  936.    NOTES
  937.        Die Headerzeilen werden in folgendem Format in die Datei
  938.        geschrieben:
  939.  
  940.          <Kennung>:<TAB><Inhalt><CR><LF>
  941.  
  942.        Die Elemente zhl_ID und zhl_Contents werden unverändert in die Datei
  943.        geschrieben.
  944.  
  945.        Hinter dem Header wird keine Leerzeile (CR/LF) ausgegeben, die den
  946.        Header vom Body/Kommentar trennt.
  947.  
  948.        Die Ausgabe in die Datei geschieht mittels FWrite(), es ist also
  949.        darauf zu achten, nur gepufferte Ein-/Ausgabe zu benutzen.
  950.  
  951.    SEE ALSO
  952.        ZCon_HeaderToIBM(), ZCon_HeaderToISO(), dos.library/FWrite()
  953.