HALFRED  0.4.0
IOVirtual device

Detailed Description


The IOVirtual is an IODevice used mainly for unit testing.

It allows to emulate the behavior of connected IODevices. Each IOVirtual device has a number of gates, that allow it to be connected to other IOVirtual devices. When two or more IOVirtual devices are connected, writing to one of them will cause the data to be received by all the others.

Creating and destroying IOVirtual devices.

All IOVirtual device objects are created at runtime, by a call to IOVIRTUAL_Create function. This call allocates memory for a new IOVIRTUAL device descriptor (plus additional memory for data buffer). Such IOVirtual device is then ready to operate as a regular IODevice object. When done using, all IOVirtual devices should be destroyed to free allocated memory, by a call to IOVIRTUAL_Destroy function.

Using IOVirtual devices.

Once created, the IOVirtual devices are usually being connected to each other. This is done by a call to IOVIRTUAL_Connect. A complementary IOVIRTUAL_Disconnect function is also provided, allowing to disconnect the devices.

A typical usage scenario is presented below:

// declare IOVirtual devices just as any other IODevices
IODevice vio1, vio2;
char buf[5];
// crete IOVirtual devices with 64 bytes long buffers and one gate
vio1 = IOVIRTUAL_Create(64, 1);
vio2 = IOVIRTUAL_Create(64, 1);
// connect IOVirtual devices together to allow data to be passed between them
// Initialize IOVirtual devices just like any other IODevices
// Use IOVirtual devices just like any other IODevices
IODEV_Write(vio1, "hello", 5, 0);
IODEV_Read(vio2, buf, 5, 0);
// buf should now contain the "hello" string
// Deinitialze IOVirtual devices just like any other IODevice
// When done using IOVirtual devices - destroy them


IODevice IOVIRTUAL_Create (size_t buf_size, int number_of_gates)
void IOVIRTUAL_Destroy (IODevice iodevice)
HALRESULT IOVIRTUAL_Connect (IODevice iodev1, IODevice iodev2)
HALRESULT IOVIRTUAL_Disconnect (IODevice iodev1, IODevice iodev2)

Function Documentation

IODevice IOVIRTUAL_Create ( size_t  buf_size,
int  number_of_gates 

Creates a new virtual IODevice.

buf_sizesize of the data buffer (in bytes)
number_of_gatesnumber of gates to connect other IOVirtual devices
new virtual IODevice or NULL if creation failed
void IOVIRTUAL_Destroy ( IODevice  iodevice)

Destroys a virtual IODevice and frees all memory allocated for it. Note, that this function should NOT be used to free other types of IODevices.

iodevicevirtual IODevice
HALRESULT IOVIRTUAL_Connect ( IODevice  iodev1,
IODevice  iodev2 

Connects IOVirtual devices together.

iodev1first IOVirtual device
iodev2second IOVirtual device
Return values
HALRESULT_OKif the devices were connected
HALRESULT_NOT_ENOUGH_GATESif one (or both) of the devices has no more free gates for connecting
HALRESULT IOVIRTUAL_Disconnect ( IODevice  iodev1,
IODevice  iodev2 

Disconnects IOVirtual devices.