The IOLibStream class

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

@interface IOLibStream : Object
{

@public

...

}

- init;
- free;
- (long) Size;
- (long) GetPos;
- (int) GetStreamType;
- (bool) SetMode: (long) mode;
- (const char *) GetRemoteHostname;
- (unsigned long) GetRemoteIP;

@end

You must not instantiate 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) mode

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.

The OutStream class is defined as follows:

@interface OutStream : IOLibStream
{

@public

...

}

- free;
...
- (bool) OutputNumberIntel: (long) number: (int) bytes;
- (bool) OutputNumberRaw: (long) number: (int) bytes;
- (bool) OutputNumberVAX: (long) number: (int) bytes;
- (bool) OutputNumberPBD: (long) number: (int) bits;
- (bool) OutputString: (const char *) string;
- (bool) OutputLine: (const char *) string;
- (bool) OutputData: (const void *) pointer: (int) bytes;
- (bool) SetPackageSize: (int) newPackagesize;
- (bool) SetFilter: (IOLibFilter *) newFilter;
- (bool) RemoveFilter;
- (bool) Close;
- (bool) Seek: (long) position;
- (bool) RelSeek: (long) offset;
- (OutStream *) WaitForClient;
- (void) Flush;
- (void) Connect: (int) type, ...;

@end

- (void) Connect: (int) type, ...

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

STREAM_FILE	- (void) Connect: 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	- (void) Connect: STREAM_POSIX, (int) file 'file' specifies a POSIX file handle (i.e. created with open()) to connect to.
STREAM_ANSI	- (void) Connect: STREAM_ANSI, (FILE *) file 'file' specifies an ANSI file handle (i.e. created with fopen()) to connect to.
STREAM_WINDOWS	- (void) Connect: 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	- (void) Connect: STREAM_SOCKET, (SOCKET) socket 'socket' specifies an open socket to connect to.
STREAM_SERVER	- (void) Connect: STREAM_SERVER, (unsigned short) port 'port' specifies a TCP/IP port to listen on.
STREAM_CLIENT	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: STREAM_STREAM, (InStream *) instream 'instream' specifies an InStream to link to.
STREAM_BUFFER	- (void) Connect: 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) number: (int) bytes

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

- (bool) OutputNumberIntel: (long) number: (int) bytes	writes values in Intel Byte Order. You can write OutputNumber instead of OutputNumberIntel either.
- (bool) OutputNumberRaw: (long) number: (int) bytes	writes values in Raw Byte Order.
- (bool) OutputNumberVAX: (long) number: (int) bytes	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) number: (int) bits

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 *) string

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

- (bool) OutputLine: (const char *) string

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 *) pointer: (int) bytes

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) newPackagesize

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 *) newFilter

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

- (bool) RemoveFilter

Removes the currently used filter.

- (bool) Seek: (long) position

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

- (bool) RelSeek: (long) offset

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:

@interface InStream : IOLibStream
{

@public

...

}

- free;
...
- (long) InputNumberIntel: (int) bytes;
- (long) InputNumberRaw: (int) bytes;
- (long) InputNumberVAX: (int) bytes;
- (long) InputNumberPBD: (int) bits;
- (char *) InputString: (int) bytes;
- (char *) InputLine;
- (char *) InputSocketString;
- (void *) InputData: (void *) pointer: (int) bytes;
- (bool) SetPackageSize: (int) newPackagesize;
- (bool) SetFilter: (IOLibFilter *) newFilter;
- (bool) RemoveFilter;
- (bool) Close;
- (bool) Seek: (long) position;
- (bool) RelSeek: (long) offset;
- (InStream *) WaitForClient;
- (void) Connect: (int) type, ...;

@end

- (void) Connect: (int) type, ...

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

STREAM_FILE	- (void) Connect: STREAM_FILE, (const char *) filename Parameter 'filename' specifies the name of the file to open.
STREAM_POSIX	- (void) Connect: STREAM_POSIX, (int) file 'file' specifies a POSIX file handle (i.e. created with open()) to connect to.
STREAM_ANSI	- (void) Connect: STREAM_ANSI, (FILE *) file 'file' specifies an ANSI file handle (i.e. created with fopen()) to connect to.
STREAM_WINDOWS	- (void) Connect: 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	- (void) Connect: STREAM_SOCKET, (SOCKET) socket 'socket' specifies an open socket to connect to.
STREAM_SERVER	- (void) Connect: STREAM_SERVER, (unsigned short) port 'port' specifies a TCP/IP port to listen on.
STREAM_CLIENT	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: 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	- (void) Connect: STREAM_STREAM, (OutStream *) outstream 'outstream' specifies an OutStream to link to.
STREAM_BUFFER	- (void) Connect: 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) bytes

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

- (long) InputNumberIntel: (int) bytes	reads values in Intel Byte Order. You can write InputNumber instead of InputNumberIntel either.
- (long) InputNumberRaw: (int) bytes	reads values in Raw Byte Order.
- (long) InputNumberVAX: (int) bytes	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) bits

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) bytes

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 *) pointer: (int) bytes

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) newPackagesize

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

- (bool) SetFilter: (IOLibFilter *) newFilter

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

- (bool) RemoveFilter

Removes the currently used filter.

- (bool) Seek: (long) position

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

- (bool) RelSeek: (long) offset

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 method 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 **) data: (int) size: (int *) outsize and - (void) DecodeData: (unsigned char **) data: (int) size: (int *) outsize.

- (void) EncodeData: (unsigned char **) data: (int) size: (int *) outsize

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 **) data: (int) size: (int *) outsize

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.