home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / DEV.Z / streams.h < prev    next >
Text File  |  1996-09-08  |  10KB  |  314 lines
  1. /*
  2.  *    File:    streams.h
  3.  *    Author:    Avadis Tevanian, Jr.
  4.  *
  5.  *    Header file definitions.
  6.  */
  7.  
  8. #ifndef STREAMS_H
  9. #define STREAMS_H
  10.  
  11. #ifdef NeXT_PDO
  12. #include <stdarg.h>        // va_start
  13. #include     <mach/mach.h>
  14. #import <objc/objc-api.h>
  15. #else    NeXT_PDO
  16. #import <ansi/stdarg.h>
  17. #import <mach/port.h>
  18. #endif NeXT_PDO
  19. #import <objc/error.h>
  20.  
  21. /* This structure may change size, and should not be included in client
  22.    data structures.  Only use pointers to NXStreams.
  23.  */
  24. typedef struct _NXStream {
  25.     unsigned int    magic_number;    /* to check stream validity */
  26.     unsigned char  *buf_base;    /* data buffer */
  27.     unsigned char  *buf_ptr;    /* current buffer pointer */
  28.     int        buf_size;    /* size of buffer */
  29.     int        buf_left;    /* # left till buffer operation */
  30.     long        offset;     /* position of beginning of buffer */
  31.     int        flags;        /* info about stream */
  32.     int        eof;
  33.     const struct stream_functions
  34.             *functions;    /* functions to implement stream */
  35.     void        *info;        /* stream specific info */
  36. } NXStream;
  37.  
  38.  
  39. struct stream_functions {
  40.     /*
  41.      * Called to read count bytes into buf.  If you arent doing any
  42.      * special buffer management, you can set this proc to be
  43.      * NXDefaultRead.  It should return how many bytes were read.
  44.      */
  45.     int    (*read_bytes)(NXStream *s, void *buf, int count);
  46.  
  47.     /*
  48.      * Called to write count bytes from buf.  If you arent doing any
  49.      * special buffer management, you can set this proc to be
  50.      * NXDefaultWrite.  It should return how many bytes were written.
  51.      */
  52.     int    (*write_bytes)(NXStream *s, const void *buf, int count);
  53.  
  54.     /*
  55.      * Called by the write routine to deal with a full output buffer.
  56.      * This routine should make space for more characters to be
  57.      * written.  NXDefaultWrite assumes this routine empties the
  58.      * buffer.  It should return how many bytes were written.
  59.      * If it returns -1, then a NX_illegalWrite exception will be raised.
  60.      */
  61.     int    (*flush_buffer)(NXStream *s);
  62.  
  63.     /*
  64.      * Called by the read routine to deal with an empty input buffer.
  65.      * This routine should provide more characters to be read.
  66.      * NXDefaultRead assumes this routine adds new characters
  67.      * to the buffer.  It should return how many bytes were read.
  68.      * If it returns -1, then a NX_illegalRead exception will be raised.
  69.      */
  70.     int    (*fill_buffer)(NXStream *s);
  71.  
  72.     /*
  73.      * Called to flip the mode of the stream between reading and writing.
  74.      * The current state can be found by masking the flags field with
  75.      * NX_READFLAG and NX_WRITEFLAG.  The caller will update the flags.
  76.      */
  77.     void    (*change_buffer)(NXStream *s);
  78.  
  79.     /*
  80.      * Called to seek the stream to a certain position.  It must update
  81.      * any affected elements in the NXStream struct.
  82.      */
  83.     void    (*seek)(NXStream *s, long offset);
  84.  
  85.     /*
  86.      * Called to free any resources used by the stream.  This proc
  87.      * should free the buffer if not allocated by NXStreamCreate.
  88.      */
  89.     void    (*destroy)(NXStream *s);
  90. };
  91.  
  92. /*
  93.  *    Modes
  94.  */
  95.  
  96. #define NX_READONLY        1    /* read on stream only */
  97. #define NX_WRITEONLY        2    /* write on stream only */
  98. #define NX_READWRITE        4    /* do read & write */
  99.  
  100. /*
  101.  *    Seeking Modes - determines meaning of offset passed to NXSeek
  102.  */
  103.  
  104. #define NX_FROMSTART        0    /* relative to start of file */
  105. #define NX_FROMCURRENT        1    /* relative to current position */
  106. #define NX_FROMEND        2    /* relative to end of file */
  107.  
  108. /*
  109.  *    Private Flags and Private Routines
  110.  */
  111.  
  112. #define NX_READFLAG    1        /* stream is for reading */
  113. #define NX_WRITEFLAG    (1 << 1)    /* stream is for writing */
  114. #define    NX_USER_OWNS_BUF    (1 << 2)    /* used by memory streams */
  115. #define NX_EOS            (1 << 3)    /* end of stream detected */
  116. #define NX_NOBUF        (1 << 4)    /* whether lib alloc'ed buf */
  117. #define NX_CANWRITE        (1 << 5)
  118. #define NX_CANREAD        (1 << 6)
  119. #define NX_CANSEEK        (1 << 7)
  120.  
  121. /* private functions for NXGetc and NXPutc */
  122. NEXTPDO int _NXStreamFillBuffer(NXStream *s);
  123. NEXTPDO int _NXStreamFlushBuffer(NXStream *s, unsigned char c);
  124. NEXTPDO int _NXStreamChangeBuffer(NXStream *s, unsigned char ch);
  125.  
  126.  
  127. /*
  128.  *        Macro operations.
  129.  */
  130.  
  131. #define NXPutc(s, c) \
  132.     ( ((s)->flags & NX_WRITEFLAG) ? \
  133.     ( --((s)->buf_left) >= 0 ? (*(s)->buf_ptr++ = (unsigned char)(c)) : \
  134.     (_NXStreamFlushBuffer((s), (unsigned char)(c)), (unsigned char)0) ) : \
  135.     _NXStreamChangeBuffer((s), (unsigned char)(c)) ) \
  136.  
  137. #define NXGetc(s)                        \
  138.     ( ((s)->flags & NX_READFLAG) ?                \
  139.     ( --((s)->buf_left) >= 0 ? ((int)(*(s)->buf_ptr++)) :    \
  140.         _NXStreamFillBuffer((s)) ) :            \
  141.     _NXStreamChangeBuffer((s), (unsigned char)(0)) )
  142.  
  143. #define NXAtEOS(s) (s->flags & NX_EOS)
  144.  
  145.  
  146. /*
  147.  *        Procedure declarations (exported).
  148.  */
  149.  
  150. NEXTPDO int NXFlush(NXStream *s);        
  151.  /*
  152.     flush the current contents of stream s.  Returns the number of chars
  153.     written.
  154.   */
  155.   
  156. NEXTPDO void NXSeek(NXStream *s, long offset, int mode);        
  157.  /*
  158.     sets the current position of the stream.  Mode is either NX_FROMSTART,
  159.     NX_FROMCURRENT, or NX_FROMEND.
  160.   */
  161.   
  162. NEXTPDO long NXTell(NXStream *s);        
  163.  /*
  164.     reports the current position of the stream.
  165.   */
  166.   
  167. #define NXRead(s, buf, count)    \
  168.         ((*s->functions->read_bytes)((s), (buf), (count)))
  169.  /*
  170.     int NXRead(NXStream *s, void *buf, int count) 
  171.     
  172.     read count bytes starting at pointer buf from stream s.  Returns the
  173.     number of bytes read.
  174.   */
  175.   
  176. #define NXWrite(s, buf, count)        \
  177.         ((*s->functions->write_bytes)((s), (buf), (count)))
  178.  /*
  179.     int NXWrite(NXStream *s, const void *buf, int count) 
  180.     
  181.     write count bytes starting at pointer buf to stream s.  Returns the
  182.     number of bytes written.
  183.   */
  184.   
  185. NEXTPDO void NXPrintf(NXStream *s, const char *format, ...);
  186. NEXTPDO void NXVPrintf(NXStream *s, const char *format, va_list argList);
  187.  /*
  188.     writes args according to format string to stream s.  The first routine
  189.     takes its variable arguments on the stack, the second takes a va_list
  190.     as defined in <stdarg.h>.
  191.   */
  192.   
  193. NEXTPDO int NXScanf(NXStream *s, const char *format, ...);
  194. NEXTPDO int NXVScanf(NXStream *s, const char *format, va_list argList);
  195.  /*
  196.     reads args from stream s according to format string.  The first routine
  197.     takes its variable arguments on the stack, the second takes a va_list
  198.     as defined in <varargs.h>.
  199.   */
  200.  
  201. NEXTPDO void NXUngetc(NXStream *s);        
  202.  /*
  203.     backs up one character previously read by getc.  Only a single character
  204.     can be backed over between reads.
  205.   */
  206.   
  207. NEXTPDO void NXClose(NXStream *s);        
  208.  /*
  209.     closes stream s.
  210.   */
  211.   
  212. NEXTPDO NXStream *NXOpenFile(int fd, int mode);
  213.  /*
  214.     opens a file stream on file descriptor fd with access mode. mode
  215.     can be NX_READONLY, NX_WRITEONLY or NX_READWRITE.
  216.     The fd should have the same access rights as the mode passed in.
  217.     When NXClose is called on a file stream, the fd is not closed.
  218.   */
  219.  
  220. NEXTPDO NXStream *NXOpenPort(port_t port, int mode);
  221.  /*
  222.     opens a stream on a MACH port with access mode. If mode is NX_READONLY,
  223.     messages will be received on port.  If mode is NX_WRITEONLY,
  224.     messages will be sent to port.  mode can not be NX_READWRITE.
  225.     These streams are not positionable, thus you cannot call NXSeek
  226.     with a port stream.  
  227.   */
  228.  
  229. NEXTPDO NXStream *NXOpenMemory(const char *addr, int size, int mode);
  230.  /*
  231.     Opens a stream on memory with access mode. mode
  232.     can be NX_READONLY, NX_WRITEONLY or NX_READWRITE
  233.     When NXClose is called on a memory stream, the internal buffer is
  234.     not freed.  Use NXGetMemoryBuffer to get the internal buffer and
  235.     use vm_deallocate to free it.
  236.   */
  237.  
  238. NEXTPDO NXStream *NXMapFile(const char *name, int mode);
  239.  /*
  240.     opens a stream on memory with access mode, initializing the
  241.     memory with the contents of a file. mode
  242.     can be NX_READONLY, NX_WRITEONLY or NX_READWRITE
  243.     When NXClose is called on a memory stream, the internal buffer is
  244.     not freed.  Use NXGetMemoryBuffer to get the internal buffer and
  245.     use vm_deallocate to free it. Use NXSaveToFile to write the 
  246.     contents of the memory stream to a file.
  247.   */
  248.  
  249. NEXTPDO NXStream *NXGetStreamOnSection(const char *fileName, const char *segmentName, const char *sectionName);
  250.  /*
  251.     opens a read-only memory stream with the contents of the named section
  252.     within the file.  When NXClose is called on a memory stream, the internal
  253.     buffer is not freed.  Use NXGetMemoryBuffer to get the internal buffer and
  254.     use vm_deallocate to free it.
  255.   */
  256.  
  257. NEXTPDO int NXSaveToFile(NXStream *s, const char *name);
  258.  /*
  259.     Write the contents of a memory stream to a file .
  260.   */
  261.  
  262. NEXTPDO void NXGetMemoryBuffer(NXStream *s, char **addr, int *len, int *maxlen);
  263.  /*
  264.     return the memory buffer, the current length, and the max length
  265.     of the buffer. Use the maxlen value when you vm_deallocate.
  266.   */
  267.  
  268. NEXTPDO void NXCloseMemory(NXStream *s, int option);
  269.  /*
  270.     Closes a memory stream, with options NX_FREEBUFFER which frees the
  271.     internal buffer, NX_TRUNCATEBUFFER which truncates to buffer to
  272.     the size of the data, and NX_SAVEBUFFER which does nothing to the
  273.     buffer. The stream is then closed and freed.
  274.   */
  275.  
  276. #define NX_FREEBUFFER        0    /* constants for NXCloseMemory */
  277. #define NX_TRUNCATEBUFFER    1
  278. #define NX_SAVEBUFFER        2
  279.  
  280.  
  281. typedef void NXPrintfProc(NXStream *stream, void *item, void *procData);
  282.  /*
  283.     A proc that is registered to format and output item on the given stream.
  284.   */
  285.  
  286. NEXTPDO void NXRegisterPrintfProc(char formatChar, NXPrintfProc *proc,
  287.                             void *procData);
  288.  /*
  289.     Registers a NXPrintProc for a format character used in the format
  290.     string for NXPrintf or NXVPrintf.  If formatChar is used in a
  291.     format string, proc will be called with the corresponding argument
  292.     passed to NXPrintf.  The format characters in the string "vVwWyYzZ"
  293.     are available for non-NeXT applications to use; the rest are reserved
  294.     for future use by NeXT.  procData is for client data that will be
  295.     blindly passed along to the proc.
  296.   */
  297.  
  298. #define NX_STREAMERRBASE 2000    /* 1000 error codes for us start here */
  299.  
  300. /* Errors that stream routines raise.  When these exceptions are raised,
  301.    the first data element is always the NXStream * being operated on,
  302.    or zero if thats not applicable.  The second is any error code
  303.    returned from the operating system.
  304.  */
  305. typedef enum _NXStreamErrors {
  306.     NX_illegalWrite = NX_STREAMERRBASE,
  307.     NX_illegalRead,
  308.     NX_illegalSeek,
  309.     NX_illegalStream,
  310.     NX_streamVMError
  311. } NXStreamErrors;
  312.  
  313. #endif
  314.