stream.h

libbt-1.01 BT应用软件 是BT客户端的源代码

#ifndef __KSTREAM__H
#define __KSTREAM__H
#include "strbuf.h"

/*-------------------------------------------------------------------
 * kStream
 *
 *    The structure kStream adds stream semantics to a socket
 */
typedef struct kStream {
    int fd;
    int inputready;
    int error;
    int error_count;
    int read_count;
    int write_count;
    kStringBuffer ibuf;
    kStringBuffer obuf;
} kStream;


/*-------------------------------------------------------------------
 * kStream_create
 *
 *    The method constructs a Stream
 *
 *  PARAMETERS:
 *    str   Stream to intialize, or NULL to calloc the stream
 *    sd    Socket to connect the stream to
 *
 *  RETURNS:
 *    The initialized stream
 *
 *  SIDE EFFECTS:
 */
kStream* 
kStream_create( kStream *str, int sd);

/*-------------------------------------------------------------------
 * kStream_finit
 *
 *    The method destroys a stream
 *
 *  PARAMETERS:
 *    str   Stream to intialize, or NULL to calloc the stream
 *
 *  SIDE EFFECTS:
 */
void
kStream_finit( kStream *str);

/*-------------------------------------------------------------------
 * kStream_read
 *
 *    Unbuffered reader
 *
 *    The method reads at at most 'max' characters from the stream.  
 *    The number of characters read is returned, or -1 is returned on
 *    error.
 *
 *  PARAMETERS:
 *    str    Stream
 *    buf    Buffer to write to
 *    max    Try to fill the buffer this full
 *
 *  RETURNS:
 *    Number of characters read, or -1 on error.  
 *
 *  SIDE EFFECTS:
 *    Sets ios->error to the error code if there is an error.
 */

int kStream_read( kStream *str, char *buf, int max);

/*-------------------------------------------------------------------
 * kStream_write
 *
 *    The method writes 'len' characters to the stream.
 * 
 *    This method is unbuffered.  It may not write all of the 
 *    characters requested depending on how much room is 
 *    available in the output stream.  Use buffered output if
 *    you need to write data and don't want to loop until
 *    the whole buffer has been sent.
 *
 *  PARAMETERS:
 *    str    Stream
 *    buf    Buffer to write to
 *    len    Length of the buffer
 *
 *  RETURNS:
 *    Number of characters written.  Can return less than 'len' if
 *    there is an error on the stream.
 *
 *  SIDE EFFECTS:
 */

int kStream_write( kStream *str, char *buf, int len);

/*-------------------------------------------------------------------
 * kStream_flush( str);
 * kStream_clear( str);
 *
 * Flush() writes any remaining data in the output buffer to the socket
 * and returns.  If the stream can't hold all of the currently buffered
 * data it will write as much as possible, and return.
 *
 * Clear() removes all data from the output-buffer without writing it
 * to the socket.
 *
 *  PARAMETERS:
 *    str    Stream
 *
 *  RETURNS:
 *    Number of characters remaining to be written, or -1 on 
 *    error.
 *
 *  SIDE EFFECTS:
 *    Removes characters from the output buffer.
 */
int kStream_flush( kStream* str);
int kStream_clear( kStream* str);

/*-------------------------------------------------------------------
 * kStream_fwrite
 *
 *    The method writes 'len' characters to the stream.
 * 
 *    This method is buffered.  If the stream can't write
 *    all of the data in one request the remaining data
 *    is saved in the output buffer and the request should 
 *    be completed by calling kStream_flush() until it
 *    returns 0.
 *
 *  PARAMETERS:
 *    str    Stream
 *    buf    Buffer to write to
 *    len    Length of the buffer
 *
 *  RETURNS:
 *    Number of characters remaining in output buffer.  Returns -1 on error.
 *
 *  SIDE EFFECTS:
 *    Adds characters to the output buffer.
 */

int kStream_fwrite( kStream *str, char *buf, int len);

/*-------------------------------------------------------------------
 * kStream_fread
 * kStream_fpeek
 *
 *    The method read 'len' characters to the stream.
 * 
 *    This method is buffered.  Data from the socket is 
 *    read and buffered until there is enough to satisfy 
 *    the request.  Any extra data will be left in the 
 *    input buffer.  If the socket runs out of data then
 *    this function will return 0, and ios->error will be set
 *    to EAGAIN.
 *
 *    Fpeek is the same as fread, but the characters read
 *    are left on the input buffer.
 *
 *  PARAMETERS:
 *    str    Stream
 *    buf    Buffer to write to
 *    len    Length of the buffer
 *
 *  RETURNS:
 *    Number of characters read.  Returns -1 on error.
 *
 *  SIDE EFFECTS:
 *    Adds characters to the input buffer.
 */
int kStream_fread( kStream *str, char *buf, int size) ;
int kStream_fpeek( kStream *str, char *buf, int size) ;

/*-------------------------------------------------------------------
 * kStream_gets
 * kStream_fgets
 *
 *    The method reads a newline terminated string from the socket.
 *    Characters are read into a buffer and returned one line at a 
 *    time.  There is no absolute limit on line length as the buffer
 *    grows dynamically, but gets() will never return more than size
 *    characters.
 *
 *  PARAMETERS:
 *    str   Stream
 *    buf   Where to put the line that is read
 *    size  Maximum line length to read
 *
 *  RETURNS:
 *    Number of characters placed into the buffer.  On a stream error
 *    the return value is zero unless there is at least one newline
 *    marker in the input buffer.  Once the buffered lines have been
 *    consumed gets() will return 0.  
 *    
 *    Any characters left after the last newline will never be 
 *    returned, but can be examined by looking directly at the buffer
 *    if needed.
 * 
 *    A stream read or write error is saved in the str->error variable
 *    when it occurs, and can be seen immediately or can be examined
 *    only after gets() has returned 0.
 *
 *  SIDE EFFECTS:
 *    The data read from the socket is written to the buf array.
 *
 *    kStream_gets() trims any trailing [CR-LF].  
 *
 *    kStream_fgets() will always return a string with a trailing 
 *    linefeed unless there was a read error from the socket.
 */

int kStream_fgets( kStream *str, char *buf, int size);
int kStream_gets( kStream *str, char *buf, int size);

/*-------------------------------------------------------------------
 * kStream_getdoc( str, buf)
 *
 *    The method reads lines until it gets an EOF marker.  The EOF
 *    marker it uses is defined as SEPARATOR in the protocol.h
 *    header.
 *
 *  PARAMETERS:
 *    str   Stream
 *    buf   Where to put the document that is read
 *
 *  RETURNS:
 *    The number of characters read.  
 *
 *  SIDE EFFECTS:
 *    The data read from the socket is written to the buf array.
 *
 *  BUGS:
 *    No error handling.
 */
int kStream_getdoc( kStream *str, kStringBuffer *buf);

/*-------------------------------------------------------------------
 * kStream_printf
 *
 *    The method writes a formatted print buffer to the stream.
 *
 *    This method buffers output.  If the entire buffer cannot
 *    be written without blocking then the remainder will be 
 *    saved in the buffer and output when kStream_run is 
 *    called.
 *
 *  PARAMETERS:
 *    str    Stream
 *    fmt    Format descriptor in printf format
 *
 *  RETURNS:
 *    Number of characters written.  Unwritten characters are
 *    queued for later output.  Returns -1 if there is an error.
 *
 *  SIDE EFFECTS:
 */

int kStream_printf( kStream *str, char *fmt, ...);

/*-------------------------------------------------------------------
 * kStream_iqlen( kStream *str);
 * kStream_oqlen( kStream *str);
 *
 *    The method returns the number of characters available in the
 *    input queue, and output queue respectively.
 *
 *  PARAMETERS:
 *    str    Stream
 *
 *  RETURNS:
 *    Number of characters available, or waiting to be written.
 *
 *  SIDE EFFECTS:
 */
int kStream_iqlen( kStream *str);
int kStream_oqlen( kStream *str);
int kStream_in_addr( kStream *str);
int kStream_out_addr( kStream *str);

#endif /* __DR1STREAM__H */