CORE Module

The CORE module provides WMDF's basic functionality. With the CORE module, it becomes possible to open files, determine the supported DOS version, deal with devices in an abstract manner, and perform basic error handling.

Rationale

Certain operations are useful for all applications; however, some DOS C compilers do not support C89 or have pecularities that limit their portability. The CORE module acts as a central glue layer to portably provide this functionality regardless of the platform.

Concepts

Devices

A device is a data structure that provides low level access to a stream such as a file, socket, I/O port, or filter. Because the interfaces for these entities may be disjoint, devices unify access to them under a common interface. All devices may be opened or close; they usually are also able to be read from or written to depending on how they are opened. Certain devices support an optional seek operation that allows for their position in the stream to be set; additional, device-specific operations can be accessed using their ioctl method. Some devices are terminal and represent a communication endpoint, while others (so-called filters) transform their underlying stream.

Devices are objects and exhibit both polymorphism and device-specific state. A device's constructor is responsible for allocating its memory and initializing it; all devices are destroyed through the wdmf_device_close() function. When the device is created, a field within it as flags is populated with one or more of the following flags:

• WDMF_DEVICE_READABLE - The device can be read.
• WDMF_DEVICE_WRITABLE - The device can be written.
• WDMF_DEVICE_SEEKABLE - The device can be seek()'d.
• WDMF_DEVICE_OPEN - The device is presently open.
• WDMF_DEVICE_EOF - The device has presently reached the end of stream.

Below is an example of interacting with devices. The parameter src is a readable device, while dest is a writable device. This function reads what remains of src and write its contents to dest. It is also assumed that the devices are both open.

#include <wdmf/device.h>
#include <stddef.h>

size_t dump(wdmf_device_t* src, wdmf_device_t* dest) {
    size_t count = 0;
    char buf[256];

      /* While we have data to read. */
      while(!(src->flags & WDMF_DEVICE_EOF)) {
          size_t len = wdmf_device_read(src, buf, sizeof(buf));
          if (buf == WDMF_EOF) {
                break;
          }

           /* Now write back */
           while(len > 0) {
                    size_t wrote = wdmf_device_write(dest, buf, len);
                    len -= wrote;
                     count += wrote;
           }
      }

      return count;
}

Constituents

The following header files make up the CORE module:

• bit.h - Functions for bitwise testing.
• device.h - Device definition and interface.
• errno.h - Error handling
• file.h - Interface for opening and manipulationg the filesystem.
• host.h - Platform detection macros.
• int.h - Platform-independent integer typedefs.
• sys.h - WDMF system management functions

Additionally, the DOS submodule built into the CORE module consists of the following module:

• dos/file.h - low-level file manipulation.
• dos/sys.h - manipulation of DOS system calls.

Usage

To use the CORE module, include the appropriate headers (wdmf/*.h and wdmf/dos/*.h) during compilation and link against wdmf. For example, the following command will link an executable with the GFX module using DJGPP:

> gcc -o foo.exe foo.o -Lpath\to\wdmf\lib -lwdmf

Every API symbol exported by the CORE module is prefixed with wdmf_. Generally, any symbol prefixed with wdmf_ belongs to this module unless it has been claimed by another.

See Also

• [GFX Module] for graphics functons.
• [INPUT Module] for input management.
• [SOUND Module] for sound and music management.