home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1999 March B / SCO_CASTOR4RRT.iso / nsfast / root.9 / usr / ns-home / nsapi / include / base / buffer.h / buffer
Text File  |  1998-08-19  |  8KB  |  271 lines
  1. /*
  2.  * Copyright (c) 1994, 1995.  Netscape Communications Corporation.  All
  3.  * rights reserved.
  4.  * 
  5.  * Use of this software is governed by the terms of the license agreement for
  6.  * the Netscape FastTrack or Netscape Enterprise Server between the
  7.  * parties.
  8.  */
  9.  
  10.  
  11. /* ------------------------------------------------------------------------ */
  12.  
  13.  
  14. /*
  15.  * buffer.h: For performing buffered I/O on a file or socket descriptor.
  16.  * 
  17.  * This is an abstraction to allow I/O to be performed regardless of the
  18.  * current system. That way, an integer file descriptor can be used under 
  19.  * UNIX but a stdio FILE structure could be used on systems which don't
  20.  * support that or don't support it as efficiently.
  21.  * 
  22.  * Two abstractions are defined: A file buffer, and a network buffer. A
  23.  * distinction is made so that mmap() can be used on files (but is not
  24.  * required). Also, the file buffer takes a file name as the object to 
  25.  * open instead of a file descriptor. A lot of the network buffering
  26.  * is almost an exact duplicate of the non-mmap file buffering.
  27.  * 
  28.  * If an error occurs, system-independent means to obtain an error string
  29.  * are also provided. However, if the underlying system is UNIX the error
  30.  * may not be accurate in a threaded environment.
  31.  * 
  32.  * Rob McCool
  33.  * 
  34.  */
  35.  
  36.  
  37. #ifndef BUFFER_H
  38. #define BUFFER_H
  39.  
  40.  
  41. /*
  42.  * We need certain system specific functions and symbols.
  43.  */
  44.  
  45. #include "file.h"
  46. #include "net.h"
  47.  
  48. /*
  49.  * Requires that the macro MALLOC be set to a "safe" malloc that will 
  50.  * exit if no memory is available. If not under MCC httpd, define MALLOC
  51.  * to be the real malloc and play with fire, or make your own function.
  52.  */
  53.  
  54. #include "../netsite.h"
  55.  
  56. #ifdef FILE_UNIX_MMAP
  57. #include <sys/types.h>          /* caddr_t */
  58. #endif
  59.  
  60.  
  61. /* ------------------------------ Structures ------------------------------ */
  62.  
  63. #ifdef FILE_MMAP
  64. typedef struct {
  65.     SYS_FILE fd;
  66. #ifdef FILE_UNIX_MMAP
  67.     caddr_t fp;
  68. #else /* FILE_WIN32_MMAP */
  69.     HANDLE fdmap;
  70.     char *fp;
  71. #endif /* FILE_UNIX_MMAP */
  72.     int len;
  73.  
  74.     unsigned char *inbuf;   /* for buffer_grab */
  75.     int cursize;
  76.  
  77.     int pos;
  78.     char *errmsg;
  79. } filebuffer;
  80.  
  81. #else
  82.  
  83. typedef struct {
  84.     SYS_FILE fd;
  85.  
  86.     int pos, cursize, maxsize;
  87.     unsigned char *inbuf;
  88.     char *errmsg;
  89. } filebuffer;
  90.  
  91. #endif
  92.  
  93. /* C++ streamio defines a filebuf class. */
  94. /* XXXrobm Temporarily allow this typedef for NT compiles. */
  95. #if !defined(__cplusplus) || !defined(XP_UNIX)
  96. typedef filebuffer filebuf;
  97. #endif
  98.  
  99. typedef struct {
  100.     SYS_NETFD sd;
  101.  
  102.     int pos, cursize, maxsize, rdtimeout;
  103. #ifdef XP_WIN32
  104.     CHAR address[64];
  105. #endif /* XP_WIN32 */
  106.     unsigned char *inbuf;
  107.     char *errmsg;
  108. } netbuf;
  109.  
  110.  
  111. /* -------------------------------- Macros -------------------------------- */
  112.  
  113.  
  114. /*
  115.  * netbuf_getc gets a character from the given network buffer and returns 
  116.  * it. (as an integer).
  117.  * 
  118.  * It will return (int) IO_ERROR for an error and (int) IO_EOF for
  119.  * an error condition or EOF respectively.
  120.  */
  121.  
  122. #define netbuf_getc(b) \
  123.  ((b)->pos != (b)->cursize ? (int)((b)->inbuf[(b)->pos++]) : netbuf_next(b,1))
  124.  
  125. #ifdef FILE_MMAP
  126. #define filebuf_getc(b) ((b)->pos == (b)->len ? IO_EOF : (b)->fp[(b)->pos++])
  127. #else
  128. #define filebuf_getc(b) \
  129.  ((b)->pos != (b)->cursize ? (int)((b)->inbuf[(b)->pos++]) : filebuf_next(b,1))
  130. #endif
  131.  
  132. #ifdef XP_WIN32
  133. #define pipebuf_getc(b) \
  134.  ((b)->pos != (b)->cursize ? (int)((b)->inbuf[(b)->pos++]) : pipebuf_next(b,1))
  135. #endif /* XP_WIN32 */
  136.  
  137. /*
  138.  * buffer_error returns the last error that occurred with buffer. Don't use
  139.  * this unless you know an error occurred. Independent of network/file type.
  140.  */
  141.  
  142. #define buffer_error(b) ((b)->errmsg)
  143.  
  144.  
  145. /* ------------------------------ Prototypes ------------------------------ */
  146.  
  147.  
  148. /*
  149.  * buffer_open opens a new buffer reading the specified file, with an I/O
  150.  * buffer of size sz, and returns a new buffer structure which will hold
  151.  * the data.
  152.  *
  153.  * If FILE_UNIX_MMAP is defined, this may return NULL. If it does, check 
  154.  * system_errmsg to get a message about the error.
  155.  */
  156.  
  157. NSAPI_PUBLIC filebuffer *filebuf_open(SYS_FILE fd, int sz);
  158. NSAPI_PUBLIC netbuf *netbuf_open(SYS_NETFD sd, int sz);
  159.  
  160. /*
  161.  * filebuf_open_nostat is a convenience function for mmap() buffer opens,
  162.  * if you happen to have the stat structure already.
  163.  */
  164.  
  165. /*
  166.  * filebuf_create is a convenience function if the file is already open
  167.  * or mmap'd.  It creates a new filebuf for use with the mmap'd file.
  168.  * If mmap_ptr is NULL, or MMAP is not supported on this system, it 
  169.  * creates a buffer with buffer size bufsz.
  170.  */
  171. filebuffer *filebuf_create(SYS_FILE fd, caddr_t mmap_ptr, int mmap_len, 
  172.                            int bufsz);
  173.  
  174. /* 
  175.  * filebuf_close_buffer is provided to cleanup a filebuf without closing
  176.  * the underlying file.  If clean_mmap is 1, and the file is memory mapped,
  177.  * the file will be unmapped.  If clean_mmap is 0, the file will not
  178.  * be unmapped.
  179.  */
  180. void filebuf_close_buffer(filebuffer *buf, int clean_mmap);
  181.  
  182. #ifdef FILE_MMAP
  183. #include <sys/stat.h>
  184. NSAPI_PUBLIC 
  185. filebuffer *filebuf_open_nostat(SYS_FILE fd, int sz, struct stat *finfo);
  186.  
  187. #else  /* !MMAP */
  188. #define filebuf_open_nostat(fd,sz,finfo) filebuf_open(fd,sz)
  189. #endif
  190.  
  191. #ifdef XP_WIN32
  192. NSAPI_PUBLIC 
  193. filebuffer *pipebuf_open(SYS_FILE fd, int sz, struct stat *finfo);
  194. #endif /* XP_WIN32 */
  195.  
  196. /*
  197.  * buffer_next loads size more bytes into the given buffer and returns the
  198.  * first one, or BUFFER_EOF on EOF and BUFFER_ERROR on error.
  199.  */
  200.  
  201. NSAPI_PUBLIC int filebuf_next(filebuffer *buf, int advance);
  202. NSAPI_PUBLIC int netbuf_next(netbuf *buf, int advance);
  203. #ifdef XP_WIN32 
  204. NSAPI_PUBLIC int pipebuf_next(filebuffer *buf, int advance);
  205. #endif /* XP_WIN32 */
  206.  
  207. /*
  208.  * buffer_close deallocates a buffer and closes its associated files
  209.  * (does not close a network socket).
  210.  */
  211.  
  212. NSAPI_PUBLIC void filebuf_close(filebuffer *buf);
  213. NSAPI_PUBLIC void netbuf_close(netbuf *buf);
  214. #ifdef XP_WIN32
  215. NSAPI_PUBLIC void    pipebuf_close(filebuffer *buf);
  216. #endif /* XP_WIN32 */
  217.  
  218. /*
  219.  * buffer_grab will set the buffer's inbuf array to an array of sz bytes 
  220.  * from the buffer's associated object. It returns the number of bytes 
  221.  * actually read (between 1 and sz). It returns IO_EOF upon EOF or IO_ERROR
  222.  * upon error. The cursize entry of the structure will reflect the size
  223.  * of the iobuf array.
  224.  * 
  225.  * The buffer will take care of allocation and deallocation of this array.
  226.  */
  227.  
  228. NSAPI_PUBLIC int filebuf_grab(filebuffer *buf, int sz);
  229. NSAPI_PUBLIC int netbuf_grab(netbuf *buf, int sz);
  230. #ifdef XP_WIN32
  231. NSAPI_PUBLIC int pipebuf_grab(filebuffer *buf, int sz);
  232. #endif /* XP_WIN32 */
  233.  
  234.  
  235. /*
  236.  * netbuf_buf2sd will send n bytes from the (probably previously read)
  237.  * buffer and send them to sd. If sd is -1, they are discarded. If n is
  238.  * -1, it will continue until EOF is recieved. Returns IO_ERROR on error
  239.  * and the number of bytes sent any other time.
  240.  */
  241.  
  242. NSAPI_PUBLIC int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);
  243.  
  244. /*
  245.  * filebuf_buf2sd assumes that nothing has been read from the filebuf, 
  246.  * and just sends the file out to the given socket. Returns IO_ERROR on error
  247.  * and the number of bytes sent otherwise.
  248.  *
  249.  * Does not currently support you having read from the buffer previously. This
  250.  * can be changed transparently.
  251.  */
  252.  
  253. NSAPI_PUBLIC int filebuf_buf2sd(filebuffer *buf, SYS_NETFD sd);
  254.  
  255. #ifdef XP_WIN32
  256.  
  257. /*
  258.  * NT pipe version of filebuf_buf2sd.
  259.  */
  260.  
  261. NSAPI_PUBLIC int pipebuf_buf2sd(filebuffer *buf, SYS_NETFD sd, int len);
  262.  
  263. /*
  264.  * NT pipe version of netbuf_buf2sd.
  265.  */
  266.  
  267. NSAPI_PUBLIC int pipebuf_netbuf2sd(netbuf *buf, SYS_FILE sd, int len);
  268. #endif /* XP_WIN32 */
  269.  
  270. #endif
  271.