home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / DC-POS24.LZX / pOS / pOS_RKRM.lzx / pOS_RKRM / _Docs / pIFFParse.doc < prev    next >
Encoding:
Text File  |  1997-03-18  |  11.7 KB  |  414 lines
  1. TABLE OF CONTENTS
  2.  
  3. piffparse.library/pOS_CloseIFF
  4. piffparse.library/pOS_CurrentChunk
  5. piffparse.library/pOS_FindProp
  6. piffparse.library/pOS_OpenIFF
  7. piffparse.library/pOS_ParseIFF
  8. piffparse.library/pOS_PopChunk
  9. piffparse.library/pOS_PropChunk
  10. piffparse.library/pOS_PushChunk
  11. piffparse.library/pOS_ReadChunkBytes
  12. piffparse.library/pOS_StopChunk
  13. piffparse.library/pOS_WriteChunkBytes
  14.  
  15. piffparse.library/pOS_CloseIFF
  16.  
  17.    NAME
  18.         pOS_CloseIFF -- Schließen eines IFF-Handels.
  19.  
  20.    SYNOPSIS
  21.         pOS_CloseIFF( iff );
  22.                      _R_A0
  23.  
  24.         VOID pOS_CloseIFF(__ARID__ struct pOS_IFFHandle *);
  25.  
  26.    FUNCTION
  27.         Schließt das übergebene IFF-Handle.
  28.  
  29.    INPUTS
  30.         iff - Zeiger auf IFF-Handle
  31.  
  32.    SEE ALSO
  33.         pOS_OpenIFF()
  34.  
  35. piffparse.library/pOS_CurrentChunk
  36.  
  37.    NAME
  38.         pOS_CurrentChunk -- ermittelt Beschreibung des aktuellen
  39.                             IFF-Chunks
  40.  
  41.    SYNOPSIS
  42.         context = pOS_CurrentChunk( iff );
  43.                                    _R_A0
  44.  
  45.         const struct pOS_IFFLocContext*
  46.                   pOS_CurrentChunk(struct pOS_IFFHandle*);
  47.  
  48.    FUNCTION
  49.         Liefert die Chunk-Beschreibung des IFF-Chunks, in welchem sich
  50.         der Parser gerade befindet.
  51.  
  52.    INPUTS
  53.         iff - Zeiger auf IFF-Handle
  54.  
  55.    RESULT
  56.         context - Zeiger auf pOS_IFFLocContext mit der Beschreibung des
  57.                   aktuellen Chunks
  58.  
  59.    SEE ALSO
  60.         pOS_PopChunk(), pOS_PushChunk(), pOS_ParseIFF()
  61.  
  62. piffparse.library/pOS_FindProp
  63.  
  64.    NAME
  65.         pOS_FindProp -- Sucht nach einem zwischengespeicherten Chunk
  66.  
  67.    SYNOPSIS
  68.         sp = pOS_FindProp( iff,   type,  id );
  69.                           _R_A0  _R_D0  _R_D1
  70.  
  71.         const struct pOS_IFFStoredProp*
  72.                   pOS_FindProp(struct pOS_IFFHandle*, ULONG, ULONG);
  73.  
  74.    FUNCTION
  75.         Sucht nach einem zwischengespeicherten Chunk, welcher mit
  76.         pOS_PropChunk() angemeldet und während pOS_ParseIFF()
  77.         gefunden wurde. Die zurückgegebene pOS_IFFStoredProp-Strktur
  78.         beinhaltet einen Zeiger auf die Daten des Chunks.
  79.  
  80.    INPUTS
  81.         iff - Zeiger auf IFF_Handle
  82.         type - Type des zu suchenen Chunks (z.B. "ILBM")
  83.         id - Identifier des Chunks (z.B. "BMHD")
  84.  
  85.    RESULT
  86.         sp - Zeiger auf pOS_IFFStoredProp Struktur, oder NULL, falls
  87.              der geforderte Chunks nicht gefunden wurde
  88.  
  89.    SEE ALSO
  90.         pOS_PropChunk(), pOS_ParseIFF()
  91.  
  92. piffparse.library/pOS_OpenIFF
  93.  
  94.    NAME
  95.         pOS_OpenIFFA -- Erzeugt ein neues IFF-Handle
  96.         pOS_OpenIFF
  97.  
  98.    SYNOPSIS
  99.         iff = pOS_OpenIFFA( tagList );
  100.                             _R_A0
  101.  
  102.         __ARID__ struct pOS_IFFHandle*
  103.                      pOS_OpenIFFA(const struct pOS_TagItem*);
  104.  
  105.         iff = pOS_OpenIFF( firstTag, ...);
  106.  
  107.         __ARID__ struct pOS_IFFHandle *pOS_OpenIFF( ULONG, ...);
  108.  
  109.    FUNCTION
  110.         Erzeugt ein neues IFF-Handle und bereitet es zur Benutzung
  111.         vor.
  112.  
  113.    INPUTS
  114.         tagList - Zeiger auf Tagliste mit den Parametern.
  115.  
  116.    TAGS
  117.         IFFTAG_DosLock (struct pOS_FileLock*)
  118.            - pOS_FileLock auf ein Verzeichnis. Ist dieser ungleich
  119.              NULL, so wird das File relativ zu diesem Lock geöffnet.
  120.  
  121.         IFFTAG_DosName (const CHAR*)
  122.            - Names der zu öffnenen Datei. Wird mit IFFTAG_DosLock ein
  123.              Lock auf ein Verzeichnis übergebenen, so kann der Name
  124.              relativ zu diesem Verzeichnis angegeben werden.
  125.  
  126.         IFFTAG_FH (struct pOS_FileHandle*)
  127.            - Zeiger auf zuvor geöffnetes FileHandle.
  128.  
  129.         IFFTAG_IOStruct (struct pOS_IOStruct*)
  130.            - Zeiger auf vollständig initialisierte pOS_IOStruct.
  131.  
  132.         IFFTAG_AccessMode (enum pOS_IFFAccessMode)
  133.            - Bestimmt den Modus der folgenden Aktionen. Es sind nur
  134.              IFFACCMD_Read oder IFFACCMD_Write möglich. Default ist
  135.              IFFACCMD_Read.
  136.  
  137.         IFFTAG_MainType (ULONG)
  138.            - Bestimmt den Typ des äußersten Chunks. Das IFF-Handle
  139.              wird nur geöffnet, falls der Typ übereinstimmt.
  140.  
  141.    RESULT
  142.         iff - Zeiger auf initialisiertes IFF-Handle oder NULL im
  143.               Fehlerfall
  144.  
  145.    NOTE
  146.         Es ist entweder IFFTAG_DosLock/IFFTAG_DosName oder IFFTAG_FH
  147.         oder IFFTAG_IOStruct zu übergeben.
  148.  
  149.    SEE ALSO
  150.         pOS_CloseIFF()
  151.  
  152. piffparse.library/pOS_ParseIFF
  153.  
  154.    NAME
  155.         pOS_ParseIFF -- Parsen einer IFF-Datei
  156.  
  157.    SYNOPSIS
  158.         error = pOS_ParseIFF( iff,  mode );
  159.                              _R_A0  _R_D0
  160.  
  161.         SLONG pOS_ParseIFF(struct pOS_IFFHandle*, ULONG);
  162.  
  163.    FUNCTION
  164.         Untersucht eine IFF-Datei. Dabei wird entsprechend dem Modus
  165.         unterschiedlich verfahren.
  166.  
  167.         IFFPARSE_Scan:
  168.            Die IFF-Datei wird sequentiell gescannt. Dabei werden alle
  169.            Chunks, die zuvor mit pOS_PropChunk() angemeldet wurden
  170.            geladen und zwischengespeichert. pOS_ParseIFF unterbricht
  171.            seine Arbeit nur, wenn:
  172.               * ein Fehler aufgetreten ist
  173.               * ein Stop-Chunk erreicht wurde
  174.                 (Result == 0 bzw. IFFERR_EOC, bei IFFTAG_StopOnExit)
  175.               * das Ende der Datei erreicht wurde (IFFERR_EOF)
  176.  
  177.            pOS_ParseIFF kann mehrmals nacheinander aufgerufen werden.
  178.            Das Parsen wird dann von der aktuellen Position fortgesetzt.
  179.  
  180.         IFFPARSE_Step:
  181.            Zur Zeit noch nicht implementiert.
  182.  
  183.    INPUTS
  184.         iff - Zeiger auf IFF-Handle
  185.         mode - zu verwendener Parsemodus (zur Zeit nur IFFPARSE_Scan)
  186.  
  187.    RESULT
  188.         error - 0 oder ein entsprechender Error-Code. Als Besonderheit
  189.                 ist IFFERR_EOC zu betrachten, da dieser Rückgabewert
  190.                 auf das Ende eines Chunks hinweist, welcher mit
  191.                 pOS_StopChunk() angemeldet wurde.
  192.  
  193.    SEE ALSO
  194.         pOS_PropChunk(), pOS_StopChunk()
  195.         p:/pOS_RKRM/pIFFParse/iffread.c
  196.  
  197. piffparse.library/pOS_PopChunk
  198.  
  199.    NAME
  200.         pOS_PopChunk -- Abschliessen eines zu schreibenen Chunks
  201.  
  202.    SYNOPSIS
  203.         error = pOS_PopChunk( iff );
  204.                              _R_A0
  205.  
  206.         SLONG pOS_PopChunk(struct pOS_IFFHandle*);
  207.  
  208.    FUNCTION
  209.         Beendet den Schreibvorgang für den zuvor mit pOS_PushChunk
  210.         eröffneten Chunk.
  211.  
  212.    INPUTS
  213.         iff - Zeiger auf IFF-Handle
  214.  
  215.    RESULT
  216.         error - wenn erfolgreich 0, sonst IFFERR_#?
  217.  
  218.    SEE ALSO
  219.         pOS_PushChunk()
  220.         p:/pOS_RKRM/pIFFParse/iffwrite.c
  221.  
  222. piffparse.library/pOS_PropChunk
  223.  
  224.    NAME
  225.         pOS_PropChunk -- Meldet einem Chunk an, der während des
  226.                          Parsens zwischengespeichert werden soll
  227.  
  228.    SYNOPSIS
  229.         error = pOS_PropChunkA( iff,  tagList );
  230.                                _R_A0  _R_A1
  231.  
  232.         SLONG pOS_PropChunkA( struct pOS_IFFHandle*,
  233.                    const struct pOS_TagItem*);
  234.  
  235.         error = pOS_PropChunk( iff,  firstTag, ...);
  236.                               _R_A0
  237.  
  238.         SLONG pOS_PropChunk( struct pOS_IFFHandle*, ULONG, ...);
  239.  
  240.    FUNCTION
  241.         Festlegen der Chunks, die während des Parsen zwischengespeichert
  242.         werden sollen. Die entsprechenden Chunks können nach dem
  243.         Parsen mit pOS_FindProp() ermittelt werden.
  244.  
  245.    INPUTS
  246.         iff - zeiger auf IFF-Handle
  247.         tagList - Zeiger auf Tagliste, welche die Chunks näher beschreibt
  248.  
  249.    TAGS
  250.         IFFTAG_ParseType (ULONG)
  251.            Dieser Tag bestimmt den Chunktyp (z.B. "ILBM"). Alle
  252.            folgenden IDs werden mit diesem Typ verknüpft.
  253.            IFFTAG_ParseType kann mehrmals in der Tagliste vorkommen.
  254.  
  255.  
  256.         IFFTAG_ParseID (ULONG)
  257.            Dieser Tag bestimmt die ChunkID (z.B. "BMHD").
  258.            Es können mehere IDs angegeben werden.
  259.  
  260.    RESULT
  261.         error - 0, falls die Chunks erfolgreich angemeldet werden
  262.                 konnten, sonst IFFERR_#?
  263.  
  264.    EXAMPLE
  265.         pOS_PropChunk( iff, IFFTAG_ParseType, ID_ILBM,
  266.           IFFTAG_ParseID, ID_CMAP, IFFTAG_ParseID, ID_BMHD,
  267.           IFFTAG_ParseID, ID_CAMG, TAG_DONE );
  268.  
  269.         Während des Parsens werden der CMAP-, der BMHD- und der
  270.         CAMG-Chunk eines IFF-ILBM zwischengespeichert.
  271.  
  272.    SEE ALSO
  273.         pOS_ParseIFF(), pOS_StopChunk()
  274.         p:/pOS_RKRM/pIFFParse/iffread.c
  275.  
  276. piffparse.library/pOS_PushChunk
  277.  
  278.    NAME
  279.         pOS_PushChunk -- Eröffnet neuen Chunk zum Schreiben
  280.  
  281.    SYNOPSIS
  282.         error = pOS_PushChunk( iff,  type,   id,   size );
  283.                               _R_A0  _R_D0  _R_D1  _R_D2
  284.  
  285.         SLONG pOS_PushChunk(struct pOS_IFFHandle*,ULONG,ULONG,SLONG);
  286.  
  287.    FUNCTION
  288.         Eröffnet einen neuen Chunk zum Schreiben entsprechend dem
  289.         Typ und der ID. Ist der Chunk ein lokaler Chunk innerhalb
  290.         eines FORM oder PROP, so wird der Typ ignoriert.
  291.         Wird eine Größe angegeben, so darf maximal size Bytes
  292.         mit pOS_WriteChunkBytes() geschrieben werden.
  293.         Bei IFF_SizeUnkown wird die Chunkgröße während des Schreibens
  294.         berechnet.
  295.  
  296.    INPUTS
  297.         iff - Zeiger auf das IFF-Handle
  298.         type - der Chunktype (z.B. "ILBM")
  299.         id - die ChunkID (z.B. "BMHD")
  300.         size - die Anzahl der folgenden Bytes oder IFF_SizeUnkown
  301.  
  302.    RESULT
  303.         error - 0, falls erfolgreich, sonst IFFERR_#?
  304.  
  305.    SEE ALSO
  306.         pOS_PopChunk(), pOS_WriteChunkBytes()
  307.         p:/pOS_RKRM/pIFFParse/iffwrite.c
  308.  
  309. piffparse.library/pOS_ReadChunkyBytes
  310.  
  311.    NAME
  312.         pOS_ReadChunkBytes -- Liest Daten aus dem aktuellen Chunk in
  313.                               einen Buffer
  314.  
  315.    SYNOPSIS
  316.         count = pOS_ReadChunkBytes( iff,   buf,  size );
  317.                                    _R_A0  _R_A2  _R_D0
  318.  
  319.         ULONG pOS_ReadChunkBytes(struct pOS_IFFHandle*,VOID*,ULONG);
  320.  
  321.    FUNCTION
  322.         Es werden size Bytes aus dem aktuellen Chunk in den Buffer
  323.         gelesen.
  324.  
  325.    INPUTS
  326.         iff - Zeiger auf IFF-Handle
  327.         buf - Zeiger auf Buffer
  328.         size - Anzahl der zu lesenden Bytes
  329.  
  330.    RESULT
  331.         count - Anzahl der in den Buffer übertragenden Zeichen
  332.  
  333.    SEE ALSO
  334.         pOS_WriteChunkBytes()
  335.         p:/pOS_RKRM/pIFFParse/iffwrite.c
  336.  
  337. piffparse.library/pOS_StopChunk
  338.  
  339.    NAME
  340.         pOS_StopChunk -- Bestimmt Chunk, bei welchem das Parsen
  341.                          unterbrochen werden soll (IFFPARSE_Scan)
  342.  
  343.    SYNOPSIS
  344.         error = pOS_StopChunk( iff,  tagList );
  345.                               _R_A0  _R_A1
  346.  
  347.         SLONG pOS_StopChunkA(struct pOS_IFFHandle*,
  348.                   const struct pOS_TagItem*);
  349.  
  350.    FUNCTION
  351.         Legt die Chunks fest, bei welchen der Parsevorgang unterbrochen
  352.         werden soll.
  353.  
  354.    INPUTS
  355.         iff - Zeiger auf IFF-Handle
  356.         tagList - Tagliste mit Chunkbeschreibungen
  357.  
  358.    TAGS
  359.         IFFTAG_StopOnExit (BOOL)
  360.            - Es soll am Ende eines der folgenden Chunks gestopt werden.
  361.  
  362.         IFFTAG_StopType (ULONG)
  363.            - Bestimmt den Typ der folgenden Chunks.
  364.  
  365.         IFFTAG_StopID (ULONG)
  366.            - IDs der Stop-Chunks.
  367.  
  368.    RESULT
  369.         error - 0, falls erfolgreich, sonst IFFERR_#?
  370.  
  371.    EXAMPLE
  372.         pOS_StopChunk( iff, IFFTAG_StopOnExit, TRUE,
  373.           IFFTAG_StopType, ID_ILBM, IFFTAG_StopID, ID_FORM, TAG_DONE );
  374.  
  375.         Es wird bis zum Ende des FORM-Chunks eines ILBMs geparst.
  376.  
  377.  
  378.         pOS_StopChunk( iff, IFFTAG_StopType, ID_ILBM,
  379.           IFFTAG_ID, ID_BODY, TAG_DONE );
  380.  
  381.         Es wird bis zum Begin des BODY-Chunks geparst. Der Chunk kann
  382.         dann mit pOS_ReadChunkBytes() ausgelesen werden.
  383.  
  384.    SEE ALSO
  385.         pOS_PropChunk(), pOS_ParseIFF(),
  386.         p:/pOS_RKRM/pIFFParse/iffread.c
  387.         p:/pOS_RKRM/pDtType/Dtilbm.c
  388.  
  389. piffparse.library/pOS_WriteChunkBytes
  390.  
  391.    NAME
  392.         pOS_WriteChunkBytes -- Schreibt Daten in den aktuellen Chunk
  393.  
  394.    SYNOPSIS
  395.         count = pOS_WriteChunkBytes( iff,   buf,  size );
  396.                                     _R_A0  _R_A1  _R_D0
  397.  
  398.         ULONG pOS_WriteChunkBytes(struct pOS_IFFHandle*,VOID*,ULONG);
  399.  
  400.    FUNCTION
  401.         Schreibt size Bytes aus dem Buffer in den aktuellen Chunk.
  402.  
  403.    INPUTS
  404.         iff - Zeiger auf IFF-Handle
  405.         buf - Buffer mit den zu schreibenen Daten
  406.         size - Anzahl der zu schreibenen Bytes
  407.  
  408.    RESULT
  409.         count - Anzahl der wirklich geschriebenen Bytes
  410.  
  411.    SEE ALSO
  412.         pOS_ReadChunkBytes()
  413.         p:/pOS_RKRM/pIFFParse/iffwrite.c