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