Helper functions for the DLL for accessing the driver, and the install functions. More...

#include <windows.h>
#include <windowsx.h>
#include "debug.h"
#include <winioctl.h>
#include "cbmioctl.h"
#include <stdlib.h>
#include <stddef.h>
#include "i_opencbm.h"
#include "version.h"
#include "archlib.h"

Macros
#define	DBG_USERMODE

#define	DBG_PROGNAME "OPENCBM-XA1541.DLL"

#define	OPENCBM_PLUGIN
	mark: we are exporting plugin functions

Functions
VOID	WaitForIoCompletionInit (VOID)
	Initialize WaitForIoCompletion() More...

VOID	WaitForIoCompletionDeinit (VOID)
	Uninitialize WaitForIoCompletion() More...

VOID	WaitForIoCompletionCancelAll (VOID)
	Cancel any running WaitForIoCompletion() More...

VOID	WaitForIoCompletionConstruct (LPOVERLAPPED Overlapped)
	Boilerplate code for asynchronous I/O requests. More...

BOOL	WaitForIoCompletion (BOOL Result, CBM_FILE HandleDevice, LPOVERLAPPED Overlapped, DWORD *BytesTransferred)
	Wait for the completion of an I/O operation. More...

const char *CBMAPIDECL	opencbm_plugin_get_driver_name (const char *const Port)
	Get the name of the driver for a specific parallel port. More...

int CBMAPIDECL	opencbm_plugin_driver_open (CBM_FILE HandleDevice, const char const Port)
	Opens the driver. More...

void CBMAPIDECL	opencbm_plugin_driver_close (CBM_FILE HandleDevice)
	Closes the driver. More...

BOOL	cbm_ioctl (IN CBM_FILE HandleDevice, IN DWORD ControlCode, IN char *TextControlCode, IN PVOID InBuffer, IN ULONG InBufferSize, OUT PVOID OutBuffer, IN ULONG OutBufferSize)
	Perform an ioctl on the driver. More...

BOOL	cbm_driver_start (VOID)
	Start a device driver. More...

BOOL	cbm_driver_stop (VOID)
	Stop a device driver. More...

BOOL	cbm_driver_install (OUT PULONG Buffer, IN ULONG BufferLen)
	Complete driver installation, "direct version". More...

BOOL	IsDriverStartedAutomatically (VOID)
	Is the driver started automatically? More...

Detailed Description

Helper functions for the DLL for accessing the driver, and the install functions.

Author: Spiro Trikaliotis

Authors: Based on code from Michael Klein <michael(dot)klein(at)puffin(dot)lb(dot)shuttle(dot)de>

Definition in file i_opencbm.c.

Macro Definition Documentation

#define DBG_PROGNAME "OPENCBM-XA1541.DLL"

The name of the executable

Definition at line 34 of file i_opencbm.c.

#define DBG_USERMODE

Mark: We are in user-space (for debug.h)

Definition at line 30 of file i_opencbm.c.

Function Documentation

BOOL cbm_driver_install	(	OUT PULONG	Buffer,
		IN ULONG	BufferLen
	)

Complete driver installation, "direct version".

This function performs anything that is needed to successfully complete the driver installation.

Parameters

Buffer	Pointer to a buffer which will return the install information
BufferLen	The length of the buffer Buffer points to (in bytes).

Returns: FALSE on success, TRUE on error

This function is for use of the installation routines only!

This version is for usage in the DLL or the install package.

Definition at line 704 of file i_opencbm.c.

References CBM_FILE, CBM_I_DRIVER_INSTALL_0_FAILED, CBM_I_DRIVER_INSTALL_0_IOCTL_FAILED, cbm_ioctl(), CBMCTRL, CBMT_I_INSTALL_OUT_MAKE_VERSION, CBMT_I_INSTALL_OUT_MAKE_VERSION_EX, DBG_ASSERT, DBG_ERROR, DBG_PREFIX, CBMT_I_INSTALL_OUT::DllVersion, CBMT_I_INSTALL_OUT::DllVersionEx, CBMT_I_INSTALL_OUT::ErrorFlags, FUNC_ENTER, FUNC_LEAVE_INT, opencbm_plugin_driver_close(), and opencbm_plugin_driver_open().

BOOL cbm_driver_start ( VOID )

Start a device driver.

This function start a device driver. It is the programmatically equivalent for "net start <driver>"

Returns: Returns TRUE on success, else FALSE.

This function is for use of the installation routines only!

Definition at line 564 of file i_opencbm.c.

References DBG_ERROR, DBG_PREFIX, DBG_SUCCESS, DBG_WARN, FUNC_ENTER, FUNC_LEAVE_BOOL, and OPENCBM_DRIVERNAME.

Referenced by CbmInstall(), and DllMain().

BOOL cbm_driver_stop ( VOID )

Stop a device driver.

This function stops a device driver. It is the programmatically equivalent for "net stop <driver>"

Returns: Returns TRUE on success, else FALSE.

This function is for use of the installation routines only!

Definition at line 639 of file i_opencbm.c.

References DBG_ERROR, DBG_PREFIX, DBG_SUCCESS, FUNC_ENTER, FUNC_LEAVE_BOOL, and OPENCBM_DRIVERNAME.

Referenced by CbmRemove(), and DllMain().

BOOL cbm_ioctl	(	IN CBM_FILE	HandleDevice,
		IN DWORD	ControlCode,
		IN char *	TextControlCode,
		IN PVOID	InBuffer,
		IN ULONG	InBufferSize,
		OUT PVOID	OutBuffer,
		IN ULONG	OutBufferSize
	)

Perform an ioctl on the driver.

This function performs an ioctl on the driver. It is used internally only.

Parameters

HandleDevice	A CBM_FILE which contains the file handle of the driver.
ControlCode	The ControlCode of the IOCTL to be performed.
TextControlCode	A string representation of the IOCTL to be performed. This is used for debugging purposes, only, and not available in free builds.
InBuffer	Pointer to a buffer which holds the input parameters for the IOCTL. Can be NULL if no input buffer is needed.
InBufferSize	Size of the buffer pointed to by InBuffer. If InBuffer is NULL, this has to be zero,
OutBuffer	Pointer to a buffer which holds the output parameters of the IOCTL. Can be NULL if no output buffer is needed.
OutBufferSize	Size of the buffer pointed to by OutBuffer. If OutBuffer is NULL, this has to be zero,

Returns: TRUE: IOCTL succeeded, else FALSE an error occurred processing the IOCTL

If cbm_driver_open() did not succeed, it is illegal to call this function.

Definition at line 506 of file i_opencbm.c.

References DBG_ERROR, DBG_PREFIX, DBG_WARN, FUNC_ENTER, FUNC_LEAVE_BOOL, WaitForIoCompletion(), and WaitForIoCompletionConstruct().

Referenced by cbm_driver_install(), cbm_get_debugging_buffer(), opencbm_plugin_clear_eoi(), opencbm_plugin_close(), opencbm_plugin_get_eoi(), opencbm_plugin_iec_dbg_read(), opencbm_plugin_iec_dbg_write(), opencbm_plugin_iec_poll(), opencbm_plugin_iec_release(), opencbm_plugin_iec_set(), opencbm_plugin_iec_setrelease(), opencbm_plugin_iec_wait(), opencbm_plugin_listen(), opencbm_plugin_lock(), opencbm_plugin_open(), opencbm_plugin_parallel_burst_read(), opencbm_plugin_parallel_burst_read_track(), opencbm_plugin_parallel_burst_read_track_var(), opencbm_plugin_parallel_burst_write(), opencbm_plugin_parallel_burst_write_track(), opencbm_plugin_pp_read(), opencbm_plugin_pp_write(), opencbm_plugin_reset(), opencbm_plugin_talk(), opencbm_plugin_unlisten(), opencbm_plugin_unlock(), and opencbm_plugin_untalk().

BOOL IsDriverStartedAutomatically ( VOID )

Is the driver started automatically?

This function finds out if the driver is started automatically or manually.

Returns: Returns TRUE if driver is started automatically, FALSE if not.

Definition at line 763 of file i_opencbm.c.

References CBM_REGKEY_SERVICE, DBG_ERROR, DBG_PREFIX, DBG_WARN, FUNC_ENTER, FUNC_LEAVE_BOOL, and RegGetDWORD().

Referenced by DllMain().

void CBMAPIDECL opencbm_plugin_driver_close ( CBM_FILE HandleDevice )

Closes the driver.

Closes the driver, which has be opened with cbm_driver_open() before.

Parameters

HandleDevice A CBM_FILE which contains the file handle of the driver.

cbm_driver_close() should be called to balance a previous call to cbm_driver_open().

If cbm_driver_open() did not succeed, it is illegal to call cbm_driver_close().

Definition at line 454 of file i_opencbm.c.

References DBG_ASSERT, FUNC_ENTER, and FUNC_LEAVE.

Referenced by cbm_driver_install(), and main().

int CBMAPIDECL opencbm_plugin_driver_open	(	CBM_FILE *	HandleDevice,
		const char *const	Port
	)

Opens the driver.

This function Opens the driver.

Parameters

HandleDevice	Pointer to a CBM_FILE which will contain the file handle of the driver.
Port	The port specification for the driver to open. If not set (== NULL), the "default" driver is used. The exact meaning depends upon the plugin.

Returns: ==0: This function completed successfully !=0: otherwise

Port is not allowed to exceed 10.

cbm_driver_open() should be balanced with cbm_driver_close().

Definition at line 405 of file i_opencbm.c.

References DBG_ASSERT, FUNC_ENTER, FUNC_LEAVE_INT, and opencbm_plugin_get_driver_name().

Referenced by cbm_driver_install(), and main().

const char* CBMAPIDECL opencbm_plugin_get_driver_name ( const char *const Port )

Get the name of the driver for a specific parallel port.

Parameters

Port	The port specification for the driver to open. If not set (== NULL), the "default" driver is used. The exact meaning depends upon the plugin.

Returns: Returns a pointer to a null-terminated string containing the driver name, or NULL if an error occurred.

Bug:: Port is not allowed to exceed 10.

Todo:: do not hard-code the driver name

Bug:: the logic does not allow more than 10 entries, thus, fail this call if we want to use a port > 10!

Definition at line 347 of file i_opencbm.c.

References FUNC_ENTER, and FUNC_LEAVE_STRING.

Referenced by opencbm_plugin_driver_open().

BOOL WaitForIoCompletion	(	BOOL	Result,
		CBM_FILE	HandleDevice,
		LPOVERLAPPED	Overlapped,
		DWORD *	BytesTransferred
	)

Wait for the completion of an I/O operation.

This function waits until an I/O operation is completed, or cancelled.

Parameters

Result	The result of the previous I/O operation (ReadFile(), WriteFile(), DeviceIoControl())
HandleDevice	A CBM_FILE which contains the file handle of the driver.
Overlapped	Pointer to an OVERLAPPED structure that was specified when the overlapped operation was started.
BytesTransferred	Pointer to a DWORD which will contain the number of bytes transferred in this asynchronous I/O operation.

Returns: FALSE if a failure occurred, TRUE if success.

Remarks: A cancelled request is considered as a failure, thus, FALSE is returned in this case.

Definition at line 258 of file i_opencbm.c.

References DBG_ASSERT, FUNC_ENTER, and FUNC_LEAVE_BOOL.

Referenced by cbm_ioctl(), opencbm_plugin_raw_read(), and opencbm_plugin_raw_write().

VOID WaitForIoCompletionCancelAll ( VOID )

Cancel any running WaitForIoCompletion()

This function cancels the running WaitForIoCompletion() function.

Definition at line 179 of file i_opencbm.c.

References FUNC_ENTER, and FUNC_LEAVE.

Referenced by opencbm_plugin_reset().

VOID WaitForIoCompletionConstruct ( LPOVERLAPPED Overlapped )

Boilerplate code for asynchronous I/O requests.

This function initializes

Parameters

Overlapped Pointer to an OVERLAPPED structure that will be initialized.

Remarks: This function completely initializes an OVERLAPPED structure to be used with ReadFile(), WriteFile, DeviceIoControl() later, and waited for with WaitForIoCompletion().

Definition at line 217 of file i_opencbm.c.

References DBG_ASSERT, FUNC_ENTER, and FUNC_LEAVE.

Referenced by cbm_ioctl(), opencbm_plugin_raw_read(), and opencbm_plugin_raw_write().

VOID WaitForIoCompletionDeinit ( VOID )

Uninitialize WaitForIoCompletion()

This function uninitializes everything needed for the WaitForIoCompletion...() functions. It has to be called exactly once for each program stop.