Dynamic Link Library "ParaPort.dll"
Overview
ParaPort offers to its client applications written in C or C++ an
Application Programming Interface ( API ) for the exported functions
of ParaPort.dll.
The C interface of ParaPort is implemented in the header file "ParaPort.h"
and presents all C type definitions and function prototypes needed
to access the dll.
The C++ interface of ParaPort contains C++ classes which wraps the
C functions and C structures:
The usage of ParaPort can be viewed in source code of the sample
program.
Software
Architecture
API
"open a port"
Description:
Before writing data to or reading data from the parallel port using
"ParaPortCycle", the client application must
get a handle from ParaPort to a port by specifying its name ( e.g.:
"LPT1" ). This handle will be used to call the other methods.
HANDLE openPort( const char* PortName );
Parameter:
| Type |
Parameter |
Description |
const char* |
PortName |
Not case sensitive character array with
name of port "LPT1" to "LPT3". Some computers
support "LPT4". Valid values are e.g.: "LPT1",
"Lpt2", "lpt3", "lpT4" etc. |
Return value:
| Type |
Possible Values |
Description |
HANDLE |
INVALID_HANDLE_VALUE |
Error occurred, call ::GetLastError()
from Windows API to get information about the error |
| |
all other values |
a valid handle ( in the sense of Windows API ),
which can be used as parameter of the other methods |
API
"get information about a port"
Description:
The following information can be extracted from a port:
API
"execute cycle"
Description:
This is the central functionality to write data to or read data from
the parallel port.
Types:
typedef struct {
UCHAR Reserved;
UCHAR Data;
UCHAR Status;
UCHAR Control;
UCHAR MaskData;
UCHAR MaskStatus;
UCHAR MaskControl;
UCHAR RepeatFactor;
} PARAPORT_CYCLE;
Method:
BOOL executeCycle( HANDLE Handle, PARAPORT_CYCLE* ParaPortCycle,
int Count );
Parameter:
| Type |
Parameter |
Description |
HANDLE |
Handle |
handle of the port ( returned by "openPort(
)" ) |
PARAPORT_CYCLE* |
ParaPortCycle |
array of cycles |
int |
Count |
number of cycles in the array |
Return value:
| Type |
Possible Values |
Description |
BOOL |
TRUE |
Method was executed successful |
| |
FALSE |
Error occurred, call ::GetLastError()
from Windows API to get information about the error |
API
"direct register access"
Description:
This functionality gives direct access to the parallel port registers.
These functions have the "__stdcall" declarators,
so they can be called from Visual Basic applications.
Types:
PARAPORT_ADDRESS
Methods:
PARAPORT_ADDRESS getPortAddress( const char* PortName
);
UCHAR input( PARAPORT_ADDRESS Address );
UCHAR output( PARAPORT_ADDRESS Address, UCHAR Byte );
Parameter:
| Type |
Parameter |
Description |
const char* |
PortName |
Not case sensitive character array with name of
port "LPT1" to "LPT3". Some computers support
"LPT4". Valid values are e.g.: "LPT1", "Lpt2",
"lpt3", "lpT4" etc. |
PARAPORT_ADDRESS |
Address |
address of the port ( returned by "getPortAddress(
)" ) |
UCHAR |
Byte |
byte to be written |
Return value:
| Type |
Possible Values |
Description |
PARAPORT_ADDRESS |
Address |
address of the port |
UCHAR |
byte to be read |
Method was executed successful |
| |
PARAPORT_BYTE_ON_ERROR |
Error occurred, call ::GetLastError()
from Windows API to get information about the error |
API
"close a port"
Description:
If a port is no more accessed, the client application must close
the handle of the port.
Method:
BOOL closePort( HANDLE Handle );
Parameter:
| Type |
Parameter |
Description |
HANDLE |
Handle |
handle of the port ( returned by "openPort(
)" ) |
Return value:
| Type |
Possible Values |
Description |
BOOL |
TRUE |
Method was executed successful |
| |
FALSE |
Error occurred, call ::GetLastError()
from Windows API to get information about the error |
API
"error handling"
Description:
All methods of ParaPort uses the error handling mechanism of Windows
using the functions "::SetLastError( )" and "::GetLastError(
)" from Windows API. ParaPort specific errors are C defines in
the custom range beyond 0x20000000. There are also some common Windows
errors returned by the functions.
#define PARAPORT_ERROR |
|
start of the ParaPort error range |
#define PARAPORT_ERROR_INTERNAL_1
|
all functions |
internal error, please contact ParaPort.net |
#define PARAPORT_ERROR_INTERNAL_2 |
all functions |
internal error, please contact ParaPort.net |
#define PARAPORT_ERROR_INTERNAL_3 |
all functions |
internal error, please contact ParaPort.net |
#define PARAPORT_ERROR_INVALID_HANDLE |
all functions |
the handle given as parameter is invalid |
#define PARAPORT_ERROR_INVALID_PORTNAME |
openPort( ) |
the name of the port is invalid |
#define PARAPORT_ERROR_LIBRARY_NOT_IMPLEMENTED |
all functions |
this functionality is not ( yet ) implemented |
#define PARAPORT_ERROR_LIBRARY_NOT_LOADED |
all functions |
|
#define PARAPORT_BYTE_ON_ERROR |
input( ) or output(
) |
the address of the port |
#define PARAPORT_ERROR_INVALID_CYCLE |
executeCycle( ) |
ParaPortCycle == NULL
|
#define PARAPORT_ERROR_INVALID_CYCLE |
executeCycle( ) |
ParaPortCycle == NULL
|
Windows errors:
ERROR_NOT_ENOUGH_MEMORY |
executeCycle( ) |
returned, if memory allocation fails
in case of limited memory resources on the computer |
API
"dll singleton"
Description:
The C++ interface implements the singleton design
pattern for the class "ParaPortDll". The
client application normally uses only on instance of the class, which
is created by the first call of the static method "getSingleton(
)". Following calls of this method do not create new objects,
but return the address of the single instance. If the object is no
longer needed, it can be deleted by calling the method "deleteSingleton(
)".
Method:
static ParaPortDll* getSingleton( );
static void deleteSingleton( );
Copyright (c) 2002, 2003, 2004 by Paul R. ADAM,
v2.0, read the Terms of Use
