IOLib version 4.0c

Using the IOLib library for C

Contents

- OutStream
- InStream
- Writing your own filters

OutStream

The following functions are available for processing OutStreams:

OutStream_New(OutStream *);
OutStream_Free(OutStream *);
bool OutStream_OutputNumberIntel(OutStream *, long , int);
bool OutStream_OutputNumberRaw(OutStream *, long, int);
bool OutStream_OutputNumberVAX(OutStream *, long , int);
bool OutStream_OutputNumberPBD(OutStream *, long, int);
bool OutStream_OutputString(OutStream *, const char *);
bool OutStream_OutputLine(OutStream *, const char *);
bool OutStream_OutputData(OutStream *, const void *, int);
bool OutStream_SetPackageSize(OutStream *, int);
bool OutStream_SetFilter(OutStream *, IOLibFilter *);
bool OutStream_RemoveFilter(OutStream *);
bool OutStream_Close(OutStream *);
bool OutStream_Seek(OutStream *, long);
bool OutStream_RelSeek(OutStream *, long);
OutStream *OutStream_WaitForClient(OutStream *);
void OutStream_Flush(OutStream *);
long OutStream_Size(OutStream *);
long OutStream_GetPos(OutStream *);
int OutStream_GetStreamType(OutStream *);
bool OutStream_SetMode(OutStream *, long);
const char *OutStream_GetRemoteHostname(OutStream *);
unsigned long OutStream_GetRemoteIP(OutStream *);
void OutStream_Connect(OutStream *, int, ...);

OutStream_New(OutStream *)

This macro allocates memory for an OutStream and initializes it correctly.

OutStream_Free(OutStream *)

This macro closes the OutStream and frees the allocated memory.

void OutStream_Connect(OutStream *, int, ...)

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

STREAM_FILE OutStream_Connect(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_Connect(OutStream *, STREAM_POSIX, int file);

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

'file' specifies an ANSI file handle (i.e. created with fopen()) to connect to.
STREAM_WINDOWS OutStream_Connect(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_Connect(OutStream *, STREAM_SOCKET, SOCKET socket);

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

'port' specifies a TCP/IP port to listen on.
STREAM_CLIENT OutStream_Connect(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_Connect(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_Connect(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_Connect(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_Connect(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_Connect(OutStream *, STREAM_STREAM, InStream *instream);

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

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

bool OutStream_OutputNumber(OutStream *, long , int)

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

bool OutStream_OutputNumberIntel(OutStream *, long, int) writes values in Intel Byte Order. You can write OutputNumber instead of OutputNumberIntel either.
bool OutStream_OutputNumberRaw(OutStream *, long, int) writes values in Raw Byte Order.
bool OutStream_OutputNumberVAX(OutStream *, 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 OutStream_OutputNumberPBD(OutStream *, 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 OutStream_OutputString(OutStream *, const char *)

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

bool OutStream_OutputLine(OutStream *, 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 OutStream_OutputData(OutStream *, 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 OutStream_SetPackageSize(OutStream *, int)

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

bool OutStream_SetFilter(OutStream *, IOLibFilter *)

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

bool OutStream_RemoveFilter(OutStream *)

Removes the currently used filter.

bool OutStream_Seek(OutStream *, long)

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

bool OutStream_RelSeek(OutStream *, long)

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

bool OutStream_Close(OutStream *)

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 *OutStream_WaitForClient(OutStream *)

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 OutStream_Flush(OutStream *)

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

long OutStream_Size(OutStream *)

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

long OutStream_GetPos(OutStream *)

Returns the current cursor position in the stream.

int OutStream_GetStreamType(OutStream *)

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

bool OutStream_SetMode(OutStream *, 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 *OutStream_GetRemoteHostname(OutStream *)

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

unsigned long OutStream_GetRemoteIP(OutStream *)

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

InStream

The following functions are available for processing InStreams:

InStream_New(InStream *);
InStream_Free(InStream *);
long InStream_InputNumberIntel(InStream *, int);
long InStream_InputNumberRaw(InStream *, int);
long InStream_InputNumberVAX(InStream *, int);
long InStream_InputNumberPBD(InStream *, int);
char *InStream_InputString(InStream *, int);
char *InStream_InputLine(InStream *);
char *InStream_InputSocketString(InStream *);
void *InStream_InputData(InStream *, void *, int);
bool InStream_SetPackageSize(InStream *, int);
bool InStream_SetFilter(InStream *, IOLibFilter *);
bool InStream_RemoveFilter(InStream *);
bool InStream_Close(InStream *);
bool InStream_Seek(InStream *, long);
bool InStream_RelSeek(InStream *, long );
InStream *InStream_WaitForClient(InStream *);
long InStream_Size(InStream *);
long InStream_GetPos(InStream *);
int InStream_GetStreamType(InStream *);
bool InStream_SetMode(InStream *, long);
const char *InStream_GetRemoteHostname(InStream *);
unsigned long InStream_GetRemoteIP(InStream *);
void InStream_Connect(InStream *, int, ...);

InStream_New(InStream *)

This macro allocates memory for an InStream and initializes it correctly.

InStream_Free(OutStream *)

This macro closes the InStream and frees the allocated memory.

void InStream_Connect(InStream *, int, ...)

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

STREAM_FILE InStream_Connect(InStream *, STREAM_FILE, const char *filename);

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

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

'file' specifies an ANSI file handle (i.e. created with fopen()) to connect to.
STREAM_WINDOWS InStream_Connect(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_Connect(InStream *, STREAM_SOCKET, SOCKET socket);

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

'port' specifies a TCP/IP port to listen on.
STREAM_CLIENT InStream_Connect(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_Connect(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_Connect(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_Connect(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_Connect(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_Connect(InStream *, STREAM_STREAM, OutStream *outstream);

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

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

long InStream_InputNumber(InStream *, int)

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

long InStream_InputNumberIntel(InStream *, int) reads values in Intel Byte Order. You can write InputNumber instead of InputNumberIntel either.
long InStream_InputNumberRaw(InStream *, int) reads values in Raw Byte Order.
long InStream_InputNumberVAX(InStream *, 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 InStream_InputNumberPBD(InStream *, 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 *InStream_InputString(InStream *, 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 *InStream_InputLine(InStream *)

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 *InStream_InputData(InStream *, 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 *InStream_InputSocketString(InStream *)

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 InStream_SetPackageSize(InStream *, int)

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

bool InStream_SetFilter(InStream *, IOLibFilter *)

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

bool InStream_RemoveFilter(InStream *)

Removes the currently used filter.

bool InStream_Seek(InStream *, long)

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

bool InStream_RelSeek(InStream *, long)

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

bool InStream_Close(InStream *)

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 *InStream_WaitForClient(InStream *)

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.

long InStream_Size(InStream *)

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

long InStream_GetPos(InStream *)

Returns the current cursor position in the stream.

int InStream_GetStreamType(InStream *)

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

bool InStream_SetMode(InStream *, 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 *InStream_GetRemoteHostname(InStream *)

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

unsigned long InStream_GetRemoteIP(InStream *)

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

Writing your own filters

Writing filters for IOLib-C is a bit complicated. I suggest that you have a look at the XOR-Filter in the 'iolib-c/test' directory and at the filters that come with the IOLib-Filters distribution.