IOLib version 4.0c

Using the IOLib library for C++

Contents

- The IOLibStream class
- OutStream
- InStream
- Writing your own filters

The IOLibStream class

The IOLibStream class, which is the base class for both InStream and OutStream, is defined as follows:

class IOLibStream
{

protected:

...

public:

long Size();
long GetPos();
int GetStreamType();
bool SetMode(long);
const char *GetRemoteHostname();
unsigned long GetRemoteIP();
IOLibStream();
~IOLibStream();

};

You must not instanciate this class directly. Use the InStream and OutStream classes instead.

long Size()

This method reports the size of the stream associated with the IOLibStream object. It returns -1 if the stream is not open.

long GetPos()

Returns the current cursor position in the stream.

int GetStreamType()

Returns one of the STREAM_* constants that specify the type of the stream.

bool SetMode(long)

This method works only for sockets. It returns true on success, false on error. The parameter specifies the blocking mode of the socket. It can be one of the following:

MODE_SOCKET_BLOCKING The socket is set to blocking mode (default)
MODE_SOCKET_NONBLOCKING The socket is set to nonblocking mode

const char *GetRemoteHostname()

Returns the hostname of the remote host that the streams socket is connected to.

unsigned long GetRemoteIP()

Returns the IP address of the remote host that the streams socket is connected to. The IP is returned in network byte order.

OutStream

The OutStream class is defined as follows:

class OutStream : public IOLibStream
{

private:

...

public:

bool OutputNumberIntel(long, int);
bool OutputNumberRaw(long, int);
bool OutputNumberVAX(long, int);
bool OutputNumberPBD(long, int);
bool OutputString(const char *);
bool OutputLine(const char *);
bool OutputData(const void *, int);
bool SetPackageSize(int);
bool SetFilter(IOLibFilter *);
bool RemoveFilter();
bool Close();
bool Seek(long);
bool RelSeek(long);
OutStream *WaitForClient();
void Flush();
OutStream(int, const char *, int);
OutStream(int, int, const char *, unsigned short, const char *, unsigned short, ...);
OutStream(int, int);
OutStream(int, FILE *;
OutStream(int, void *, long);
OutStream(int, InStream *);
~OutStream();

};

Constructors - OutStream(int, ...)

The first parameter specifies the type of stream to be created. It can be one of the following:

STREAM_FILE OutStream(STREAM_FILE, const char *filename, int flag);

Parameter 'filename' specifies the name of the file to open and 'flag' is one of the
OS_APPEND or OS_OVERWRITE constants.
STREAM_POSIX OutStream(STREAM_POSIX, int file);

'file' specifies a POSIX file handle (i.e. created with open()) to connect to.
STREAM_ANSI OutStream(STREAM_ANSI, FILE *file);

'file' specifies an ANSI file handle (i.e. created with fopen()) to connect to.
STREAM_WINDOWS OutStream(STREAM_WINDOWS, HFILE file);

'file' specifies a Windows file handle (i.e. created with _lopen()) to connect to.
This is only available on Windows platforms.
STREAM_SOCKET OutStream(STREAM_SOCKET, SOCKET socket);

'socket' specifies an open socket to connect to.
STREAM_SERVER OutStream(STREAM_SERVER, unsigned short port);

'port' specifies a TCP/IP port to listen on.
STREAM_CLIENT OutStream(STREAM_CLIENT, const char *hostname, unsigned short port);

'hostname' specifies the name of the server to connect to and 'port' is the desired TCP/IP port.
STREAM_SOCKS4_CLIENT OutStream(STREAM_SOCKS4_CLIENT, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port);

'flag' must be STREAM_SOCKS4_NOAUTH.
'proxy' and 'proxyport' specify specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
STREAM_SOCKS4_BIND OutStream(STREAM_SOCKS4_BIND, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port, const char *remotehost, unsigned short *remoteport);

'flag' must be STREAM_SOCKS4_NOAUTH.
'proxy' and 'proxyport' specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
'remotehost' points to a buffer which receives the hostname of the listening server, and 'remoteport' is a pointer to an integer which receives the port number.
STREAM_SOCKS5_CLIENT OutStream(STREAM_SOCKS5_CLIENT, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port, [const char *username, const char *password]);

'flag' is either STREAM_SOCKS5_NOAUTH or STREAM_SOCKS5_AUTH.
'proxy' and 'proxyport' specify specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
If 'flag' is STREAM_SOCKS5_AUTH, then additional parameters 'username' and 'password' specify the username and password to be used to connect to the SOCKS5 proxy.
STREAM_SOCKS5_BIND OutStream(STREAM_SOCKS5_BIND, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port, [const char *username, const char *password], const char *remotehost, unsigned short *remoteport);

'flag' is either STREAM_SOCKS5_NOAUTH or STREAM_SOCKS5_AUTH.
'proxy' and 'proxyport' specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
If 'flag' is STREAM_SOCKS5_AUTH, then additional parameters 'username' and 'password' specify the username and password to be used to connect to the SOCKS5 proxy.
'remotehost' points to a buffer which receives the hostname of the listening server, and 'remoteport' is a pointer to an integer which receives the port number.
STREAM_STREAM OutStream(STREAM_STREAM, InStream *instream);

'instream' specifies an InStream to link to.
STREAM_BUFFER OutStream(STREAM_BUFFER, void *buffer, long size);

'buffer' specifies a pointer to a memory buffer and 'size' specifies the size of that buffer.

bool OutputNumber(long , int)

This function writes a value to a stream. There are three versions of this function in IOLib:

bool OutputNumberIntel(long, int) writes values in Intel Byte Order. You can write OutputNumber instead of OutputNumberIntel either.
bool OutputNumberRaw(long, int) writes values in Raw Byte Order.
bool OutputNumberVAX(long, int) writes values in VAX Byte Order.

The first parameter specifies the value to be written to the stream. The second parameter specifies the number of bytes to be used (values from 1-8 bytes are allowed).

bool OutputNumberPBD(long , int)

This function writes a PBD value to a stream. The first parameter specifies the value to be written to the stream and the second parameter specifies the number of bits to be used (values from 1-64 bits are allowed).

bool OutputString(const char *)

This function writes a string to a stream. The parameter specifies the string to be written to the stream.

bool OutputLine(const char *)

This is the same as the OutputString() method, but a LF or CRLF is added automatically.
This function is very useful for writing config files etc., since it automatically cares about LF and CRLF returns.

bool OutputData(const void *, int)

This function writes raw data to the stream. The first parameter specifies the memory buffer containing the data. The second parameter specifies the number of bytes to be written to the stream.

bool SetPackageSize(int)

Specifies the number of bytes to be collected before anything is written to the stream. The default package size is 131072 bytes.

bool SetFilter(IOLibFilter *)

Specifies the filter to be used for writing data to the stream.

bool RemoveFilter()

Removes the currently used filter.

bool Seek(long)

Sets the cursor position in the stream. This function does not work for socket streams.

bool RelSeek(long)

Sets the cursor position in the stream relative to the current position. This function does not work for socket streams.

bool Close()

Closes the stream. This function is automatically invoked by the destructor, but you can close the stream earlier by calling this function from your code.

OutStream *WaitForClient()

This functions works only for streams of type STREAM_SERVER, STREAM_SOCKS4_BIND or STREAM_SOCKS5_BIND. It waits for a client to connect to the server and establishes a connection. The returned OutStream is an interface to the socket connected to client.

void Flush()

Writes all data from the internal buffers to the stream, ignoring the package size setting.

InStream

The InStream class is defined as follows:

class InStream : public IOLibStream
{

private:

...

public:

long InputNumberIntel(int);
long InputNumberRaw(int);
long InputNumberVAX(int);
long InputNumberPBD(int);
char *InputString(int);
char *InputLine();
char *InputSocketString();
void *InputData(void *, int);
bool SetPackageSize(int);
bool SetFilter(IOLibFilter *);
bool RemoveFilter();
bool Close();
bool Seek(long);
bool RelSeek(long);
InStream *WaitForClient();
InStream(int, const char *);
InStream(int, int);
InStream(int, FILE *);
InStream(int, void *, long);
InStream(int, const char *, int);
InStream(int, int, const char *, unsigned short, const char *, unsigned short, ...);
InStream(int, OutStream *);
~InStream();

};

Constructors - InStream(int, ...)

The first parameter specifies the type of stream to be created. It can be one of the following:

STREAM_FILE InStream(STREAM_FILE, const char *filename);

Parameter 'filename' specifies the name of the file to open.
STREAM_POSIX InStream(STREAM_POSIX, int file);

'file' specifies a POSIX file handle (i.e. created with open()) to connect to.
STREAM_ANSI InStream(STREAM_ANSI, FILE *file);

'file' specifies an ANSI file handle (i.e. created with fopen()) to connect to.
STREAM_WINDOWS InStream(STREAM_WINDOWS, HFILE file);

'file' specifies a Windows file handle (i.e. created with _lopen()) to connect to.
This is only available on Windows platforms.
STREAM_SOCKET InStream(STREAM_SOCKET, SOCKET socket);

'socket' specifies an open socket to connect to.
STREAM_SERVER InStream(STREAM_SERVER, unsigned short port);

'port' specifies a TCP/IP port to listen on.
STREAM_CLIENT InStream(STREAM_CLIENT, const char *hostname, unsigned short port);

'hostname' specifies the name of the server to connect to and 'port' is the desired TCP/IP port.
STREAM_SOCKS4_CLIENT InStream(STREAM_SOCKS4_CLIENT, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port);

'flag' must be STREAM_SOCKS4_NOAUTH.
'proxy' and 'proxyport' specify specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
STREAM_SOCKS4_BIND InStream(STREAM_SOCKS4_BIND, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port, const char *remotehost, unsigned short *remoteport);

'flag' must be STREAM_SOCKS4_NOAUTH.
'proxy' and 'proxyport' specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
'remotehost' points to a buffer which receives the hostname of the listening server, and 'remoteport' is a pointer to an integer which receives the port number.
STREAM_SOCKS5_CLIENT InStream(STREAM_SOCKS5_CLIENT, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port, [const char *username, const char *password]);

'flag' is either STREAM_SOCKS5_NOAUTH or STREAM_SOCKS5_AUTH.
'proxy' and 'proxyport' specify specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
If 'flag' is STREAM_SOCKS5_AUTH, then additional parameters 'username' and 'password' specify the username and password to be used to connect to the SOCKS5 proxy.
STREAM_SOCKS5_BIND InStream(STREAM_SOCKS5_BIND, int flag, const char *proxy, unsigned short proxyport, const char *server, unsigned short port, [const char *username, const char *password], const char *remotehost, unsigned short *remoteport);

'flag' is either STREAM_SOCKS5_NOAUTH or STREAM_SOCKS5_AUTH.
'proxy' and 'proxyport' specify the hostname and the TCP/IP port of the SOCKS5 proxy to connect to. 'server' and 'port' specify the hostname and the TCP/IP port of the application server to connect to.
If 'flag' is STREAM_SOCKS5_AUTH, then additional parameters 'username' and 'password' specify the username and password to be used to connect to the SOCKS5 proxy.
'remotehost' points to a buffer which receives the hostname of the listening server, and 'remoteport' is a pointer to an integer which receives the port number.
STREAM_STREAM InStream(STREAM_STREAM, OutStream *outstream);

'outstream' specifies an OutStream to link to.
STREAM_BUFFER InStream(STREAM_BUFFER, void *buffer, long size);

'buffer' specifies a pointer to a memory buffer and 'size' specifies the size of that buffer.

long InputNumber(int)

This function reads a value from a stream. There are three versions of this function in IOLib:

long InputNumberIntel(int) reads values in Intel Byte Order. You can write InputNumber instead of InputNumberIntel either.
long InputNumberRaw(int) reads values in Raw Byte Order.
long InputNumberVAX(int) reads values in VAX Byte Order.

The parameter specifies the number of bytes to be read from the stream (values from 1-8 bytes are allowed). The returned value is the value read from the stream.

long InputNumberPBD(int)

This function reads a PBD value from a stream. The parameter specifies the number of bits to be read from the file (values from 1-64 bits are allowed). The returned value is the value read from the stream.

char *InputString(int)

This function reads a string from a stream. The parameter specifies the number of bytes to be read. The returned string is the string read from the stream.

char *InputLine()

This function reads all characters until the next LF or CRLF. The LF/CRLF is stripped from the returned string.
This function is very useful for reading text files.

void *InputData(void *, int)

This function reads raw data from the stream. The first parameter specifies the memory buffer to receive the data. The second parameter specifies the number of bytes to be read from the stream. The function returns a pointer to the memory buffer specified in parameter one.

char *InputSocketString()

This function reads as many bytes as possible from the stream. It only works for socket streams. It returns a pointer to the string read from the stream.

bool SetPackageSize(int)

Specifies the number of bytes to be read from the stream at one time. The default package size is 131072 bytes.

bool SetFilter(IOLibFilter *)

Specifies the filter to be used for reading data from the stream.

bool RemoveFilter()

Removes the currently used filter.

bool Seek(long)

Sets the cursor position in the stream. This function does not work for socket streams.

bool RelSeek(long)

Sets the cursor position in the stream relative to the current position. This function does not work for socket streams.

bool Close()

Closes the stream. This function is automatically invoked by the destructor, but you can close the stream earlier by calling this function from your code.

InStream *WaitForClient()

This functions works only for streams of type STREAM_SERVER, STREAM_SOCKS4_BIND or STREAM_SOCKS5_BIND. It waits for a client to connect to the server and establishes a connection. The returned InStream is an interface to the socket connected to client.

Writing your own filters

The rules for writing a filter for IOLib are simple: The base class for IOLib filters is class IOLibFilter Your filters must implement the methods void EncodeData(unsigned char **, int, int *) and void DecodeData(unsigned char **, int, int *).

void EncodeData(unsigned char **, int, int *)

This function is invoked by OutStream when writing data to a stream. The first parameter points at a pointer to a buffer that contains the data to be filtered. This is a double-pointer, because this enables filters to enlarge the buffer if necessary.
The second parameter specifies the number of bytes in the buffer. Your filter is expected to write the filtered data back to the buffer and set the value pointed to by the third parameter to the number of bytes written to the buffer.

void DecodeData(unsigned char **, int, int *)

This function is invoked by InStream when reading data from a stream. The first parameter points at a pointer to a buffer that contains the data to be filtered. The second parameter specifies the number of bytes in the buffer. Your filter is expected to write the filtered data back to the buffer and set the value pointed to by the third parameter to the number of bytes written to the buffer.

Your filter can set the int packsize member of class IOLibFilter to specify the number of bytes it wants to have passed to the filtering functions. A value of 0 specifies that a filter can handle any number of bytes. A value of -1 specifies that the filter wants to process all data (i.e. the whole file) in one step. 0 is the default value.