home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIIOBuf.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-10-22  |  14.2 KB  |  500 lines
  1. /*____________________________________________________________________________*\
  2.  *
  3.  
  4.  Copyright (c) 1997 John Roy. All rights reserved.
  5.  
  6.  These sources, libraries and applications are
  7.  FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
  8.  as long as the following conditions are adhered to.
  9.  
  10.  Redistribution and use in source and binary forms, with or without
  11.  modification, are permitted provided that the following conditions
  12.  are met:
  13.  
  14.  1. Redistributions of source code must retain the above copyright
  15.     notice, this list of conditions and the following disclaimer. 
  16.  
  17.  2. Redistributions in binary form must reproduce the above copyright
  18.     notice, this list of conditions and the following disclaimer in
  19.     the documentation and/or other materials provided with the
  20.     distribution.
  21.  
  22.  3. Redistributions of any form whatsoever and all advertising materials 
  23.     mentioning features must contain the following
  24.     acknowledgment:
  25.     "This product includes software developed by John Roy
  26.     (http://www.johnroy.com/pi3/)."
  27.  
  28.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  29.  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30.  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  31.  IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  32.  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33.  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34.  GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35.  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36.  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37.  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  38.  OF THE POSSIBILITY OF SUCH DAMAGE.
  39.  
  40.  *____________________________________________________________________________*|
  41.  *
  42.  * $Source: PIIOBuf.h$
  43.  * $Date: Sun Aug 10 06:36:33 1997$
  44.  *
  45.  Description:
  46. \*____________________________________________________________________________*/
  47. /* $SourceTop:$ */
  48.  
  49. #ifndef PIIOBUF_H_
  50. #define PIIOBUF_H_
  51.  
  52. #include "Pi2API.h"
  53.  
  54. /*____________________________________________________________________________*\
  55.  *
  56.  Description:
  57.     Flags which effect behaviour
  58. \*____________________________________________________________________________*/
  59. #define PIIOBUF_NONE        (0)
  60. #define PIIOBUF_NOBUFFER    (1)
  61.  
  62.     /* -------------- +++++++++++++++++++++++++++++++ ------------------ *\
  63.     
  64.                         C++ Interface
  65.  
  66.     \* -------------- +++++++++++++++++++++++++++++++ ------------------ */
  67. #if defined(__cplusplus) && defined(PI3_INTERNAL)
  68.  
  69. #include <assert.h>
  70.  
  71. /*____________________________________________________________________________*\
  72.  *
  73.  Description:
  74. \*____________________________________________________________________________*/
  75. class PIIOBuffer
  76. {
  77. private:
  78.     PIObject *pIOObject;
  79.     enum { IN_BUF_SIZE=2047, OUT_BUFFER_SIZE=8192 };
  80.     char szInBuf[ IN_BUF_SIZE ];
  81.     char *pOutBuffer;
  82.     int iBufferLen;
  83.     int iBytesSent;
  84.     int iOutBufferSize;
  85.     int iOutIOError;
  86.  
  87.     /* --- internal methods --- */
  88.     int GrowData();
  89.     int FlushOutput();
  90.     int Internal_Write( const char *pData, int iLen, int iFlags );
  91.  
  92. public:
  93.     PIIOBuffer( PIObject *pTheIOObject )
  94.     :    pIOObject( pTheIOObject ),
  95.         pOutBuffer( new char[OUT_BUFFER_SIZE] ),
  96.         iBufferLen( 0 ),
  97.         iBytesSent( 0 ),
  98.         iOutBufferSize( 0 ),
  99.         iOutIOError( 0 )
  100.         {
  101.         assert( pOutBuffer );
  102.         };
  103.  
  104.     ~PIIOBuffer()
  105.         {
  106.         FlushOutput();
  107.         delete [] pOutBuffer;
  108.         };
  109.  
  110.     inline PIObject *GetIOObject()        { return pIOObject; };
  111.     int GetLine( char *pszBuf, int iBufLen );
  112.     int PollBeforeRead();
  113.     const char *Read( int *piRead );
  114.     inline int Flush()                    { return FlushOutput(); };
  115.     int Read( char *pszBuffer, int iMaxLen );
  116.     int Write( const char *pData, int iItsLength, int iFlags=PIIOBUF_NONE );
  117.     int WriteLn( const char *pData, int iItsLength, int iFlags=PIIOBUF_NONE );
  118.     inline int GetOutputBuffer( char **ppBuffer )
  119.         {
  120.         assert( pOutBuffer );
  121.         assert( ppBuffer );
  122.         *ppBuffer = &( pOutBuffer[iOutBufferSize] );
  123.         return OUT_BUFFER_SIZE-iOutBufferSize;
  124.         };
  125.     inline int AdvanceBufferPointer( int iCount )
  126.         {
  127.         assert( iCount<=(OUT_BUFFER_SIZE-iOutBufferSize) );
  128.         iOutBufferSize += iCount;
  129.         return 1;
  130.         };
  131.     inline int GetBytesSent() const    { return iBytesSent; };
  132.     inline void ResetBytesSent()    { iBytesSent = 0; };
  133. };
  134.  
  135. #else
  136.     /* -------------- +++++++++++++++++++++++++++++++ ------------------ *\
  137.     
  138.                         External C Interface
  139.  
  140.     \* -------------- +++++++++++++++++++++++++++++++ ------------------ */
  141. /*____________________________________________________________________________*\
  142.  *
  143.  Description:
  144.     Structure is opaque in C
  145. \*____________________________________________________________________________*/
  146. typedef int PIIOBuffer;
  147.  
  148.  
  149.     /* -------------- +++++++++++++++++++++++++++++++ ------------------ *\
  150.     
  151.                         C Functions
  152.  
  153.     \* -------------- +++++++++++++++++++++++++++++++ ------------------ */
  154. #endif
  155.  
  156. /*____________________________________________________________________________*\
  157.  *
  158.  Name:
  159.     PIIOBuffer_new
  160.  
  161.  Synopsis:
  162.     PIIOBuffer *PIIOBuffer_new( PIObject *pIOObject )
  163.  
  164.  Description:
  165.     Create a new IO buffer object which uses IO channel object pIOObject for
  166.     input and output.
  167.  
  168.  Notes:
  169.  Return Values:
  170.  Errors:
  171.  See Also:
  172.     PIIOBuffer_delete().
  173. \*____________________________________________________________________________*/
  174. PUBLIC_PIAPI PIIOBuffer *PIIOBuffer_new( PIObject *pIOObject );
  175.  
  176. /*____________________________________________________________________________*\
  177.  *
  178.  Name:
  179.     PIIOBuffer_delete
  180.  
  181.  Synopsis:
  182.     int PIIOBuffer_delete( PIIOBuffer *pPIIOBuffer )
  183.  
  184.  Description:
  185.     Deallocate memory associated with IO buffer object pIOBuffer after 
  186.     flushing output.
  187.  
  188.  Notes:
  189.     Destroying the buffer object does not destroy the IO channel it
  190.     encapsulates.
  191.  
  192.  Return Values:
  193.  Errors:
  194.  
  195.  See Also:
  196.     PIIOBuffer_new().
  197. \*____________________________________________________________________________*/
  198. PUBLIC_PIAPI int PIIOBuffer_delete( PIIOBuffer *pPIIOBuffer );
  199.  
  200. /*____________________________________________________________________________*\
  201.  *
  202.  Name:
  203.     PIIOBuffer_getLine
  204.  
  205.  Synopsis:
  206.     int PIIOBuffer_getLine( PIIOBuffer *pIOBuf, char *pszBuf, int iBufLen )
  207.  
  208.  Description:
  209.     Read a line from the IO buffer into buffer pszBuf. Up to iBufLen
  210.     characters are written.
  211.  
  212.  Notes:
  213.  Return Values:
  214.     Returns number of characters read or -1 on error.
  215.     
  216.  Errors:
  217.     Returns -1 on error.
  218.  
  219.  See Also:
  220.     PIIOBuffer_read().
  221. \*____________________________________________________________________________*/
  222. PUBLIC_PIAPI int PIIOBuffer_getLine( PIIOBuffer *pIOBuf, char *pszBuf,
  223.     int iBufLen );
  224.  
  225. /*____________________________________________________________________________*\
  226.  *
  227.  Name:
  228.     PIIOBuffer_pollBeforeRead
  229.  
  230.  Synopsis:
  231.     int PIIOBuffer_pollBeforeRead( PIIOBuffer *pIOBuf )
  232.  
  233.  Description:
  234.     Causes the current thread to yield until data has been read from the
  235.     IO channel into the internal buffer.
  236.  
  237.  Notes:
  238.  Return Values:
  239.     Returns -1 on IO error, 0 for channel closed and >0 for success.
  240.     
  241.  Errors:
  242.     Returns -1 on error.
  243.  
  244.  See Also:
  245.     PIIOBuffer_read().
  246. \*____________________________________________________________________________*/
  247. PUBLIC_PIAPI int PIIOBuffer_pollBeforeRead( PIIOBuffer *pIOBuf );
  248.  
  249. /*____________________________________________________________________________*\
  250.  *
  251.  Name:
  252.     PIIOBuffer_read
  253.  
  254.  Synopsis:
  255.     const char *PIIOBuffer_read( PIIOBuffer *pIOBuf, int *piRead )
  256.  
  257.  Description:
  258.     Reads data from the IO channel into the internal buffer and returns
  259.     a pointer to the data read. The pointer piRead should point at 
  260.     an integer which will be set to the number of bytes read on success.
  261.  
  262.  Notes:
  263.  Return Values:
  264.     Return a non-NULL pointer on success.
  265.     
  266.  Errors:
  267.     Returns NULL on channel closed or error.
  268.  
  269.  See Also:
  270.     PIIOBuffer_readToBuffer().
  271. \*____________________________________________________________________________*/
  272. PUBLIC_PIAPI const char *PIIOBuffer_read( PIIOBuffer *pIOBuf, int *piRead );
  273.  
  274. /*____________________________________________________________________________*\
  275.  *
  276.  Name:
  277.     PIIOBuffer_readToBuffer
  278.  
  279.  Synopsis:
  280.     int PIIOBuffer_readToBuffer( PIIOBuffer *pIOBuf, char *pszBuf,
  281.         int iMaxLen )
  282.  
  283.  Description:
  284.     Reads data from the IO channel into the buffer pIOBuf. Up to iMaxLen
  285.     bytes will be read. A positive return value gives the number of bytes
  286.     written into the buffer.
  287.  
  288.  Notes:
  289.  Return Values:
  290.     Returns values are: 0 on channel closed, -1 on error and >0 on success.
  291.     
  292.  Errors:
  293.     Returns -1 on error, 0 on channel closed.
  294.  
  295.  See Also:
  296.     PIIOBuffer_read().
  297. \*____________________________________________________________________________*/
  298. PUBLIC_PIAPI int PIIOBuffer_readToBuffer( PIIOBuffer *pIOBuf, char *pszBuf,
  299.     int iMaxLen );
  300.  
  301. /*____________________________________________________________________________*\
  302.  *
  303.  Name:
  304.     PIIOBuffer_write
  305.  
  306.  Synopsis:
  307.     int PIIOBuffer_write( PIIOBuffer *pIOBuf, const char *pszBuf, int iLen,
  308.         int iFlags )
  309.  
  310.  Description:
  311.     Write the contents of the buffer pszBuf of length iLen into the
  312.     the internal output buffer optionally flushing the output buffer.
  313.  
  314.     The value iFlags is formed by OR'ing the following flags
  315.  
  316.         PIIOBUF_NONE        No flags (0).
  317.         PIIOBUF_NOBUFFER    Don't buffer, output data with directly after
  318.                                 flushing existing output buffer.
  319.  Notes:
  320.     If iLen is -1, PIIOBuffer_write() uses strlen() to determine the 
  321.     length of the string pszBuf.
  322.  
  323.  Return Values:
  324.     Returns number of bytes written or -1 on error.
  325.     
  326.  Errors:
  327.     Returns -1 on error.
  328.  
  329.  See Also:
  330.     PIIOBuffer_writeLn().
  331. \*____________________________________________________________________________*/
  332. PUBLIC_PIAPI int PIIOBuffer_write( PIIOBuffer *pIOBuf, const char *pszBuf,
  333.     int iLen, int iFlags );
  334.  
  335. /*____________________________________________________________________________*\
  336.  *
  337.  Name:
  338.     PIIOBuffer_writeLn
  339.  
  340.  Synopsis:
  341.     int PIIOBuffer_writeLn( PIIOBuffer *pIOBuf, const char *pszBuf, int iLen,
  342.         int iFlags )
  343.  
  344.  Description:
  345.     Write the contents of the buffer pszBuf of length iLen into the
  346.     the internal output buffer followed by CRLF to terminate the line.
  347.  
  348.     See PIIOBuffer_write() for a description of flags.
  349.  
  350.  Notes:
  351.     If iLen is -1, PIIOBuffer_write() uses strlen() to determine the 
  352.     length of the string pszBuf.
  353.  
  354.  Return Values:
  355.     Returns number of bytes written or -1 on error.
  356.     
  357.  Errors:
  358.     Returns -1 on error.
  359.  
  360.  See Also:
  361.     PIIOBuffer_write().
  362. \*____________________________________________________________________________*/
  363. PUBLIC_PIAPI int PIIOBuffer_writeLn( PIIOBuffer *pIOBuf, const char *pszBuf,
  364.     int iLen, int iFlags );
  365.  
  366. /*____________________________________________________________________________*\
  367.  *
  368.  Name:
  369.     PIIOBuffer_flush
  370.  
  371.  Synopsis:
  372.     int PIIOBuffer_flush( PIIOBuffer *pIOBuf )
  373.  
  374.  Description:
  375.     Flush contents of output buffer to the IO channel.
  376.  
  377.  Notes:
  378.  Return Values:
  379.     Returns an integer which should be interpreted as a boolean.
  380.     
  381.  Errors:
  382.     Returns non-zero on success, zero on failure.
  383.  
  384.  See Also:
  385. \*____________________________________________________________________________*/
  386. PUBLIC_PIAPI int PIIOBuffer_flush( PIIOBuffer *pIOBuf );
  387.  
  388. /*____________________________________________________________________________*\
  389.  *
  390.  Name:
  391.     PIIOBuffer_getOutputBuffer
  392.  
  393.  Synopsis:
  394.     int PIIOBuffer_getOutputBuffer( PIIOBuffer *pIOBuf, char **ppBuffer )
  395.  
  396.  Description:
  397.     Returns the output buffer and its length so data can be written into
  398.     it directly rather than using intermediate buffering. If the buffer 
  399.     length is not sufficient PIIOBuffer_flush() may be invoked followed by
  400.     PIIOBuffer_getOutputBuffer() to get the flushed buffer.
  401.  
  402.     The pointer ppBuffer will be set to point at the internal buffer.
  403.  
  404.     After data has been written to the buffer and before any other output
  405.     buffer functions are invoked the function PIIOBuffer_advanceBufferPointer()
  406.     should be called to set the internal length of the output buffer.
  407.     
  408.  Notes:
  409.  Return Values:
  410.     Returns the length of the output buffer.
  411.     
  412.  Errors:
  413.  See Also:
  414.     PIIOBuffer_advanceBufferPointer().
  415.  
  416. \*____________________________________________________________________________*/
  417. PUBLIC_PIAPI int PIIOBuffer_getOutputBuffer( PIIOBuffer *pIOBuf,
  418.     char **ppBuffer );
  419.  
  420. /*____________________________________________________________________________*\
  421.  *
  422.  Name:
  423.     PIIOBuffer_advanceBufferPointer
  424.  
  425.  Synopsis:
  426.     int PIIOBuffer_advanceBufferPointer( PIIOBuffer *pIOBuf, int iCount )
  427.  
  428.  Description:
  429.     Advances the internal buffer pointer by iCount bytes. See 
  430.     PIIOBuffer_getBufferPointer() for more information.
  431.  
  432.  Notes:
  433.  Return Values:
  434.     Returns a positive integer on success.
  435.     
  436.  Errors:
  437.     Returns a negative or zero value on failure.
  438.  
  439.  See Also:
  440.     PIIOBuffer_getBufferPointer().
  441.  
  442. \*____________________________________________________________________________*/
  443. PUBLIC_PIAPI int PIIOBuffer_advanceBufferPointer( PIIOBuffer *pIOBuf,
  444.     int iCount );
  445.  
  446. /*____________________________________________________________________________*\
  447.  *
  448.  Name:
  449.     PIIOBuffer_getBytesSent
  450.  
  451.  Synopsis:
  452.     int PIIOBuffer_getBytesSent( PIIOBuffer *pIOBuf )
  453.  
  454.  Description:
  455.     Returns the number of byes which have been place into this buffer
  456.     object since it was created or PIIOBuffer_resetBytesSent() was
  457.     last invoked. This value is the sum of the data sent down the IO channel
  458.     and data currently in the output buffer.
  459.     
  460.  Notes:
  461.  Return Values:
  462.     Returns number of bytes sent.
  463.     
  464.  Errors:
  465.     This function does not raise an error.
  466.  
  467.  See Also:
  468.     PIIOBuffer_resetBytesSent().
  469.  
  470. \*____________________________________________________________________________*/
  471. PUBLIC_PIAPI int PIIOBuffer_getBytesSent( PIIOBuffer *pIOBuf );
  472.  
  473. /*____________________________________________________________________________*\
  474.  *
  475.  Name:
  476.     PIIOBuffer_resetBytesSent
  477.  
  478.  Synopsis:
  479.     int PIIOBuffer_resetBytesSent( PIIOBuffer *pIOBuf )
  480.  
  481.  Description:
  482.     Resets the count of bytes sent through this buffer object to 0.
  483.     Refer to PIIOBuffer_getBytesSent() for more information.
  484.     
  485.  Notes:
  486.  Return Values:
  487.     This function does not return a value.
  488.     Returns number of bytes sent.
  489.     
  490.  Errors:
  491.     This function does not raise an error.
  492.  
  493.  See Also:
  494.     PIIOBuffer_getBytesSent().
  495. \*____________________________________________________________________________*/
  496. PUBLIC_PIAPI void PIIOBuffer_resetBytesSent( PIIOBuffer *pIOBuf );
  497.  
  498. #endif /* PIIOBUF_H_ */
  499.  
  500.