The New SSLeay IO mechanism.

The aim of this stuff is to allow my library to be independant of the
underlying IO mechanims.  This means the same function can read (or
write) to a socket, FILE *, file descriptor or a memory buffer.  The
function will not know or care.

In most places in SSLeay, where it made sense, functions that operate
on FILE * are still present and they just map to a BIO object and call
the relevent BIO function.  These 'helper' functions are not available
for the Windows 3.1 build because FILE pointers do not work from
inside DLL's.  This was probably the main readon why this
functionality was added.

The Base Functions
int BIO_write(BIO *bio, char *wbuf, int wnum);
int BIO_read(BIO *bio, char *rbuf, int rnum)
int BIO_puts(BIO *bio, char *wbuf);
int BIO_gets(BIO *bio, char *rbuf, int rnum)
long BIO_ctrl(BIO *bio, int cmd, int argi, char *argp);
BIO *BIO_new(void );
BIO_free(BIO *bio);

For BIO_read(). if ret <= 0, call BIO_should_retry() to determin
if we should retry.  We could have to retry if non-blocking semantics
are being used or if say, call completeion is being used under Windows NT.
BIO_eof() can be used to determin if the end of input has been reached.
BIO_retry_type() can be used to determin what kind of operation caused
the 'error'.  This is mostly used by BIO implementations of protocols.
If you are using non-blocking objects like FILE pointers or memory
buffers, ignore what I just said about 'retrying' :-).

Control modes
These are implemted via macros - this is in a state of change.

#define BIO_CTRL_RESET          1  /* opt - rewind/flush etc */
Resets the BIO structure.  It signals the complete wind back
to the state just after the creation.  All pending data is lost.
True on sucess.

#define BIO_CTRL_EOF            2  /* opt - are we at the eof */
True if we know we are at the eof.  0 if we are not sure or not able to
find out or we are not actually there.

#define BIO_CTRL_INFO           3  /* opt */
This is used to return interesting data, which is returned via the
argp and/or return value.  The argi parameter is used to specify
what data to return.

#define BIO_CTRL_SET            4  /* man - set the 'object' type */
Used to set the 'mode/state' for filter BIO's and the source/sink state
for IO BIO's.

#define BIO_CTRL_GET            5  /* man - get the 'object' type */
Return the 'mode/state'  for filter BIO's and the souce/sink state for
IO BIO's

#define BIO_CTRL_PUSH		6  /* man - for filter IO's */
For a filter BIO, 'push' the BIO in argp to be the source/sink for this BIO.

#define BIO_CTRL_POP		7  /* man - for filter IO's */
For a filter BIO, 'pop' the BIO source/since and return it in argp (which
is a BIO **.

#define BIO_CTRL_SET_CLOSE      8  /* man - set the 'close' on free */
Set the 'shutdown' the IO primative on 'free' for IO BIO's.

#define BIO_CTRL_GET_CLOSE      9  /* man - set the 'close' on free */
Return the close status.

#define BIO_CTRL_PENDING        10  /* opt - is their more data buffered */
Return the number of bytes that are waiting in the first BIO down the
chain to have pending data.  If the top one has non, pass the request
down the line.

#define BIO_CTRL_FLUSH          11  /* opt - 'flush' buffered output */
Write pending data and return the number of bytes written.
A return of 0 indicates their is nothing to flush, a -1 could require a retry.

/********** It looks like I may never uses these two, the information
 * is normally being kept in bio->state */
#define BIO_CTRL_SHOULD_RETRY   12 /* opt - should we retry the failed op */
After an IO error, this returns true if the operation should be
retried at a later point.  This is to do with non-blocking semantics.

#define BIO_CTRL_RETRY_TYPE 	13 /* opt - r/w for retry */
Returns the mode that caused the non-blocking IO error.
Codes returned by BIO_CTRL_RETRY_TYPE
#define BIO_FLAGS_READ		0x01
#define BIO_FLAGS_WRITE		0x02
#define BIO_FLAGS_SPECIAL_READ	0x04 /* to be used by SSL */
#define BIO_FLAGS_SPECIAL_WRITE	0x08 /* to be used by SSL */
This is mostly used when doing SSL handshaking because a BIO_write()
could fail on a SSL bio for the reason that it was trying to read()
when doing the opening connection.

#define BIO_NOCLOSE             0
#define BIO_CLOSE               1

/* used by BIO_CTRL_SET_FILENAME option */
#define BIO_FP_READ                2
#define BIO_FP_WRITE               4
#define BIO_FP_APPEND              8


.