IO.pbi

 Top Next

IO.pbi is a small library that implements a interface for all important native IO interfaces in PureBasic.

All methods in the interface have the same behavior, no matter what IO interface is actually involved.

Currently supported IO interfaces:

·File

·Memory

·Network

·SerialPort

For future versions, it is planed to implement "virtual" IO subinterfaces. This virtual interfaces are just holding another IO interface, and all the actions will be passed to this interface, so they are only another layer of abstraction. In this layer functions like bandwidth - limiting, thread - syncronization, usw. will be implemented.

Current Version: # 0.3

Download

If you like my include you can tell my by buying me a beer (or two):


Interface

 Top Previous Next

The interface as it is implemented in PureBasic, just click a method to get a detailed Description.

The Interface is splitted in obligtory-to-implement and optional-to-implement methods.

Interface IO

; Obligatory:

Write(*Mem, MemSize.i)

Read(*Mem, MemSize.i)

IsAvailable()

Truncate()

Close()

IOHandle()

IOName$()

IOOptionalFunctions()

; Optional:

GetLength()

GetPosition()

SetPosition(Position.i)

ImportFromIO(*IO.IO)

ExportToIO(*IO.IO)

EndInterface


Write(*Mem, MemSize.i)

IO\Write(*Mem, MemSize.i)

 Top Previous Next

Implementation:

Obligatory

Parameters:

*Mem: Address of memory area

MemSize: Size of memory area

Description:

Writes MemSize - bytes from *Mem to the IO interface output-buffer at the current data-pointer position.

The data-pointer will be set to data-pointer + MemSize*.

* Only for interfaces that have the same input-output buffer (file/memory), but there will hardly a situation where

this matters.

Return value:

Number of bytes actually written. If return value isn't equal with MemSize some kind of error happened.

See also:

IO\Read()


Read(*Mem, MemSize.i)

IO\Read(*Mem, MemSize.i)

 Top Previous Next

Implementation:

Obligatory

Parameters:

*Mem: Address of memory area

MemSize: Size of memory area

Description:

Reads MemSize - bytes from the IO interface input-buffer at the current data pointer position to *Mem.

To be sure there is something to read, IO\IsAvailable() MUST be called before the use of IO\Read().

The data-pointer will be set to data-pointer + MemSize*.

* (IO interfaces that doesn't support navigation in the data won't be able to access this data again. This

data will be removed automatically from the buffer so you havn't to worry about memory-leaks.)

Return value:

Number of bytes actually read.

See also:

IO\Write(), IO\IsAvailable()


IsAvailable()

IO\IsAvailable()

 Top Previous Next

Implementation:

Obligatory

Parameters:

Description:

Return the amount of data available in bytes in the input-buffer between the data-pointer* and the end of the buffer.

* (IO interfaces that doesn't support navigation in the data, the data-pointer is always at the position after the last

IO\Read()/IO\Write()** call, so it returns the amount of new data in the buffer)

** IO\Write() only for interfaces that have the same input-output buffer (file/memory), but there will be hardly a situation where this matters.

This Method MUST be called before IO\Read() because it does the internal buffering.

Return value:

Number of bytes in the input-buffer.

See also:

IO\Write(), IO\Read(), IO\SetPosition(), IO\GetPosition()


Truncate()

IO\Truncate()

 Top Previous Next

Implementation:

Obligatory

Parameters:

Description:

Truncates the input/output-buffer at the data-pointer, all data after this pointer will be removed.

* (IO interfaces that doesn't support navigation in the data, the data-pointer is always at the position after the last

IO\Read()/IO\Write() call, so always the hole buffer is flushed)

Return value:

See also:

IO\Write(), IO\Read(), IO\SetPosition(), IO\GetPosition()


Close()

IO\Close()

 Top Previous Next

Implementation:

Obligatory

Parameters:

Description:

Closes and frees the IO interface and also closes the native IO interface inside.

Return value:

See also:


IOHandle()

IO\IOHandle()

 Top Previous Next

Implementation:

Obligatory

Parameters:

Description:

Returns the native handle of the containing IO port (Address of memory area, file handle, ...)

Return value:

Native IO handle

See also:

IO\IOName$()


IOName$()

IO\IOName$()

 Top Previous Next

Implementation:

Obligatory

Parameters:

Description:

Returns the name of the IO - Implementation ("FILE", "MEMORY", ...)

Return value:

IO Name

See also:

IO\IOHandle()


IOOptionalFunctions()

IO\IOOptionalFunctions()

 Top Previous Next

Implementation:

Obligatory

Parameters:

Description:

Returns supported optional-to-implement methods of the IO interface. The Values are binary-or chained,

so you can check for the existence of a method with the binary-and operator. (e.g. IO\IOOptionalFunctions() & #IO_GetLength)

Available values:

·#IO_GetLength

·#IO_GetPosition

·#IO_SetPosition

·#IO_ImportFromIO

·#IO_ExportToIO

Return value:

Optional functions

See also:

IO\GetLength(), IO\GetPosition(), IO\SetPosition(), IO\ImportFromIO(), IO\ExportToIO()


GetLength()

IO\GetLength()

 Top Previous Next

Implementation:

Optional.

Before you use this method check with IO\IOOptionalFunctions() & #IO_GetLength if the IO interface

supports this method, otherwise you could run into an IMA.

Parameters:

Description:

Returns the total length of data in the input/output-buffer.

Return value:

Total bytes in buffer.

See also:

IO\IsAvailable()


GetPosition()

IO\GetPosition()

 Top Previous Next

Implementation:

Optional.

Before you use this method check with IO\IOOptionalFunctions() & #IO_GetPosition if the IO interface

supports this method, otherwise you could run into an IMA.

Parameters:

Description:

Returns the current position of the data-pointer in the input/output buffer.

Return value:

Current data-pointer position in bytes.

See also:

IO\SetPosition()


SetPosition(Position.i)

IO\SetPosition(Position.i)

 Top Previous Next

Implementation:

Optional.

Before you use this method check with IO\IOOptionalFunctions() & #IO_SetPosition if the IO interface

supports this method, otherwise you could run into an IMA.

Parameters:

Position New Position of the data-pointer in bytes.

Description:

Returns the current position of the data-pointer in the input/output buffer.

Return value:

See also:

IO\GetPosition()


ImportFromIO(*IO.IO)

IO\ImportFromIO(*IO.IO)

 Top Previous Next

Implementation:

Optional.

Before you use this method check with IO\IOOptionalFunctions() & #IO_ImportFromIO if the IO interface

supports this method, otherwise you could run into an IMA.

Parameters:

*IO IO interface to import data

Description:

All data from the *IO interface will be imported into the input/output-buffer* of the IO interface. For example, a File IO interface will replace all the data in the file with the data from the *IO interface.

* Only for interfaces that have the same input-output buffer (file/memory), otherwise the imported data

will be sent to the output buffer (Network/SerialPort), but there will be hardly a situation where this matters.

Return value:

Non-zero if success, zero otherwise

See also:

IO\ExportToIO()


ExportToIO(*IO.IO)

IO\ExportToIO(*IO.IO)

 Top Previous Next

Implementation:

Optional.

Before you use this method check with IO\IOOptionalFunctions() & #IO_ExportToIO if the IO interface

supports this method, otherwise you could run into an IMA.

Parameters:

*IO IO interface to import data

Description:

All data from the IO interface will be sent to the the IO\Write() method of the *IO interface.

The current data-pointer, input/output buffer won't be touched, exporting doesn't change anything

at the current IO interface. (Also for interfaces that doesn't support navigation)

Return value:

See also:

IO\ImportFromIO()


Implementations

Native PB IO interfaces currently supported by IO.pbi:

·File

·Memory

·Network

·SerialPort


File

The File IO interface wraps the PB - File Commands. As this commands cover the functionality of the IO.pbi interface pretty good

there are just very few adjustments.

Syntax:

*File.IO = IO_File(FileName$, Type = #PB_File_Open, Flags = #Null)

Pretty simple, FileName$ is the name of the file you want to open/read/create, Type chooses the type of operation

(#PB_File_Open, #PB_File_Read, #PB_File_Write) like the similiar PB - Commands and Flags are the same Flags like

in the similiar PB commands (Link).

IO Name:

"FILE"

IO Handle:

File handle

Supported optional methods:

IO\GetLength(), IO\GetPosition(), IO\SetPosition(), IO\ImportFromIO(), IO\ExportToIO()


Memory

The Memory IO interface uses an internal growing memory that acts exactly like a file, but just in the memory.

Syntax:

*Memory.IO = IO_Memory(BlockSize = 512)

You havn't to worry about anything, the Memory IO interface will do automatic reallocating, automatic shrinking (after IO\Truncate()), ... .

The optional BlockSize parameter only specifies the internal size of blocks that will be used for automatic resizing, increase it if you operate with large

amounts of data, but it won't change anything at the functionality.

IO Name:

"MEMORY"

IO Handle:

Address of memory area

Supported optional methods:

IO\GetLength(), IO\GetPosition(), IO\SetPosition(), IO\ImportFromIO(), IO\ExportToIO()


Network

The Network IO interface adds automatic receiving and buffering of the PB Network functions. You won't have to mess around with receive loops,

checking for more data available at the Connection/Client, this Interface will do that for you.

Syntax:

*Network.IO = IO_Network_Connection(ServerName$, Port, Mode = #PB_Network_TCP|#PB_Network_IPv4, TimeOut = 5000, LocalIP$ = "", LocalPort = #Null)

*Network.IO = IO_Network_Client(ClientID, Mode = #PB_Network_TCP)

The Network IO interfaces can be created by two ways:

·The first one is the same as you'd use the OpenNetworkConnection() command.

·The second one is to create a Interface from an ClientID you received from EventClient(). The optional Mode parameter is just to adjust the internal receive buffer, but for a better performance, you should set it correct.

IO Name:

"NETWORK:CONNECTION"

"NETWORK:CLIENT"

IO Handle:

ConnectionID/ClientID

Supported optional methods:

IO\ImportFromIO(), IO\ExportToIO()


SerialPort

 Top Previous

The SerialPort IO interface adds automatic receiving and buffering of the PB SerialPort functions. You won't have to mess around with receive loops,

checking for more data available at the port, this Interface will do that for you.

Syntax:

*SerialPort.IO = IO_SerialPort(SerialPortName$, Bauds, Parity, _Data.i, Stop.f, HandshakeMode, InputBufferSize, OutputBufferSize)

This interface will be created the same way as the OpenSerialPort() command.

IO Name:

"SerialPort"

IO Handle:

SerialPortID

Supported optional methods:

IO\ImportFromIO(), IO\ExportToIO()