i_opencbm.h File Reference

Internal API for opencbm installation. More...

#include "configuration.h"
#include "opencbm.h"

Go to the source code of this file.

Macros
#define	CBMCTRL(_x_)   CBMCTRL_##_x_, "CBMCTRL_" #_x_
#define	REGKEY_EVENTLOG   "System\\CurrentControlSet\\Services\\Eventlog\\System\\opencbm"

Functions
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_stop (VOID)
	Stop a device driver. More...
BOOL	cbm_driver_start (VOID)
	Start a device driver. More...
BOOL	cbm_driver_install (OUT PULONG Buffer, IN ULONG BufferLen)
	Complete driver installation, "direct version". More...
LONG	RegGetDWORD (IN HKEY RegKey, IN char *SubKey, OUT LPDWORD Value)
	Get a DWORD value from the registry. More...
BOOL	IsDriverStartedAutomatically (VOID)
	Is the driver started automatically? More...
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...
PCHAR	FormatErrorMessage (DWORD Error)
BOOL	CbmInstall (IN LPCTSTR DriverName, IN LPCTSTR ServiceExe, IN BOOL AutomaticStart)
	Install the driver. More...
BOOL	CbmRemove (IN LPCTSTR DriverName)
	Remove the driver. More...
BOOL	CbmCheckPresence (IN LPCTSTR DriverName)
	Check for the presence of the driver. More...
int	CbmCheckDriver (void)
	Check for the correct installation. More...
VOID	CbmParportRestart (VOID)
	Restart the parallel port. More...
BOOL	CbmUpdateParameter (IN ULONG DefaultLpt, IN ULONG IecCableType, IN ULONG PermanentlyLock, IN BOOL DebugFlagsDriverPresent, IN ULONG DebugFlagsDriver, IN BOOL DebugFlagsDllPresent, IN ULONG DebugFlagsDll)
	Update the parameter of the driver. More...
VOID	CbmOutputDebuggingBuffer (VOID)

Detailed Description

Internal API for opencbm installation.

---

Author

Spiro Trikaliotis

Definition in file i_opencbm.h.

Macro Definition Documentation

#define CBMCTRL

(

_x_

)

CBMCTRL_##_x_, "CBMCTRL_" #_x_

A macro for the call to cbm_ioctl() Remember, I'm lazy...

Definition at line 37 of file i_opencbm.h.

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().

#define REGKEY_EVENTLOG   "System\\CurrentControlSet\\Services\\Eventlog\\System\\opencbm"

Registry key where the opencbm driver is located (under HKLM)

Definition at line 57 of file i_opencbm.h.

Referenced by CbmRemove().

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().

int CbmCheckDriver

(

void

)

Check for the correct installation.

This function checks if the driver was correctly installed.

Returns

Return value which will be given on return from main(). That is, 0 on success, everything else indicates an error.

Todo:

NeededAccessRights()

Todo:

Suggested output from WoMo: Checking configuration for OpenCBM: No problems found in current configuration:

Driver configuration: Port: automatic (0), currently using LPT 1 IRQ mode: enabled Driver start mode: manually (3)

Definition at line 465 of file startstop.c.

References DBG_PREFIX, DBG_PRINT, FUNC_ENTER, and FUNC_LEAVE_INT.

Referenced by opencbm_plugin_install_do_install().

BOOL CbmCheckPresence

(

IN LPCTSTR

DriverName

)

Check for the presence of the driver.

This function checks if the driver is present.

Parameters

DriverName

The name under which the driver is installed.

Returns

TRUE if the driver is present, FALSE is not, or if there was an error.

Definition at line 510 of file service.c.

References FUNC_ENTER, and FUNC_LEAVE_BOOL.

Referenced by opencbm_plugin_install_do_uninstall().

BOOL CbmInstall	(	IN LPCTSTR	DriverName,
		IN LPCTSTR	ServiceExe,
		IN BOOL	AutomaticStart
	)

Install the driver.

This function installs the opencbm driver on the machine.

Parameters

DriverName	The name under which the driver should be installed.
ServiceExe	The path to the executable which contains the logging texts
AutomaticStart	If set to TRUE, then the driver start type should be set to "AUTOMATIC", that is, the driver is started on every boot. If FALSE, it is put to "MANUAL".

Returns

TRUE if an error occurred, else FALSE.

Definition at line 294 of file service.c.

References cbm_driver_start(), cbmlibmisc_format_error_message(), DBG_ERROR, DBG_PREFIX, DBG_SUCCESS, DBG_WARN, FUNC_ENTER, and FUNC_LEAVE_BOOL.

Referenced by opencbm_plugin_install_do_install().

VOID CbmParportRestart

(

VOID

)

Restart the parallel port.

This function tries to restart the parallel port, so that registry changes can take effect.

Definition at line 143 of file parport.c.

References SETUPAPI::CM_Get_Device_ID_ExA_p, DBG_ASSERT, DBG_ERROR, DBG_PREFIX, DBG_SUCCESS, DBGDO, FUNC_ENTER, FUNC_LEAVE, SETUPAPI::HandleSetupApiDll, and SETUPAPI::SetupDiGetDeviceInfoListDetailA_p.

BOOL CbmRemove

(

IN LPCTSTR

DriverName

)

Remove the driver.

This function removes the opencbm driver from the machine.

Parameters

DriverName

The name under which the driver is installed.

Returns

TRUE on success, else FALSE.

Definition at line 437 of file service.c.

References cbm_driver_stop(), cbmlibmisc_format_error_message(), DBG_ERROR, DBG_PREFIX, DBG_SUCCESS, FUNC_ENTER, FUNC_LEAVE_BOOL, and REGKEY_EVENTLOG.

Referenced by opencbm_plugin_install_do_uninstall().

BOOL CbmUpdateParameter	(	IN ULONG	DefaultLpt,
		IN ULONG	IecCableType,
		IN ULONG	PermanentlyLock,
		IN BOOL	DebugFlagsDriverPresent,
		IN ULONG	DebugFlagsDriver,
		IN BOOL	DebugFlagsDllPresent,
		IN ULONG	DebugFlagsDll
	)

Update the parameter of the driver.

This function updates the parameters of the driver.

Parameters

DefaultLpt	The default LPT to be set
IecCableType	The IEC cable type
PermanentlyLock	Zero if driver should not permanently lock the parallel port, not zero otherwise.
DebugFlagsDriverPresent	Specifies if the following DebugFlagsDriver field should be used or not
DebugFlagsDriver	The DebugFlags to be set for the driver
DebugFlagsDllPresent	Specifies if the following DebugFlagsDll field should be used or not
DebugFlagsDll	The DebugFlags to be set for the DLL

Returns

TRUE on success, else FALSE.

Definition at line 404 of file service.c.

References FUNC_ENTER, and FUNC_LEAVE_BOOL.

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().

LONG RegGetDWORD	(	IN HKEY	RegKey,
		IN char *	SubKey,
		OUT LPDWORD	Value
	)

Get a DWORD value from the registry.

This function gets a DWORD value in the registry. It is a simple wrapper for convenience.

Parameters

RegKey	A handle to an already opened registry key.
SubKey	Pointer to a null-terminiated string which holds the name of the value to be created or changed.
Value	Pointer to a variable which will contain the value from the registry

Returns

ERROR_SUCCESS on success, -1 otherwise

If this function returns -1, the given Value will not be changed at all!

Definition at line 54 of file registry.c.

References DBG_ASSERT, DBG_ERROR, DBG_PREFIX, DBG_SUCCESS, FUNC_ENTER, FUNC_LEAVE_INT, and FUNC_PARAM.

Referenced by cbm_get_debugging_flags(), and IsDriverStartedAutomatically().

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.

Remarks

Make sure there are no outstanding I/O requests when this function is called!

Definition at line 158 of file i_opencbm.c.

References FUNC_ENTER, and FUNC_LEAVE.

Referenced by DllMain().

VOID WaitForIoCompletionInit

(

VOID

)

Initialize WaitForIoCompletion()

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

Definition at line 129 of file i_opencbm.c.

References DBG_ASSERT, FUNC_ENTER, and FUNC_LEAVE.

Referenced by DllMain().