-
Getting started
-
-
This document is organized into sections to show various ways of interracting
with our DLL. It is suggested that you make the "Table of Contents" your starting
point. This document lists all DLL entry points with their prototypes in both
C style and VisualBasic style as well as a brief description of each.
The DLL has a wide assortment of function calls. We are continuously updating
the DLL with new entry points to make the developers task of communicating with
our USB devices easier. In doing so, we also strive to keep the DLL backward
compatible for those who have been using our earlier DLL and already have
applications developed with particular DLL entry points and functionality
taken into concideration.
As we add new entry points, we will sometimes prefix them a particular way to
assist the developer in know which are the older and which are the newer entry
points. A good example of this is entry points that begin with the "SP_" prefix.
Such entry points are the easiest means to interface between the DLL and the
application making the calls. However all "SP_" style function calls aren't best
suited for every style of programming language. For example the following calls
are most efficient and should be used when possible by applications using the C or
VisualBasic programming language.
-
-
DLL_StartScan_DIO()
-
DLL_ReadScanData_DIO()
-
DLL_ReadScanDataWithDigin()
To take the explanation of the "SP_" prefixed function usage a little
further, you'll notice that using the "SP_InitAllDevices(...)" entry point will
do everything that a developer once had to do by doing the following calls and/or
tasks:
-
1.) DLL_Init(...)
2.) DLL_ReadWriteDevice(...) - send signon token
3.) handle any errors such as reset of device if write failed
4.) DLL_ReadWriteDevice(...) - read bytes returned from signon
5.) handle any errors such as reset of device if bytes echoed above were incorrect
6.) DLL_ReadWriteDevice(...) - send rate
7.) handle any errors such as reset of device if write failed
8.) DLL_ReadWriteDevice(...) - read bytes returned from sending rate
9.) handle any errors such as reset of device if bytes echoed above were incorrect
10.) DLL_SetRate - let DLL know what the new rate was set to
-
It should also be noted that any device can be reinitialized by calling the function
described above with the single device placed in the Device ID list passed as an
argument in the function call.
back
-
Prototyping
-
This document lists all prototypes for all DLL entry points that currently
exist. You may need to use only a handful of these function calls. We recommend
using function calls prefixed with "SP_" for any new application development.
The explanation in the "getting started" section of this documentation gives
an example of why. As of this time, there aren't "SP_" related functions for
every task that work best for every application. For example, when using a
C or VB language, it's recommended that you continue to use the
following two "old style" function calls rather than their "SP_" counterparts:
-
-
DLL_StartScan_DIO()
-
DLL_ReadScanData_DIO()
-
DLL_ReadScanDataWithDigin()
The functions above are more efficient than their "SP_" counterparts.
The newer "SP_" functions that serve the same purpose were created for
languages that have restrictions concerning passing of structured data between an application
and DLL.
The "Table of Contents" contains links to all function call prototypes for use
by various development environments as well as example code showing their usage.
We have made many improvemnents in our API since it's beginning. We've created new
entry points into our DLL that help make the developer's job easier. However, we
still support the "old style" function calls that we created in the beginning stages
of development. Some of the older calls are still the most efficient. The older style
calls are prefixed with DLL_ while the newer calls are prefixed with
SP_ . It's fine to mix some of the older ones with the newer ones to make
coding of your applications a little easier. For example some very early developers
used "DLL_ReadWriteOneDevice(...)" with a particular token to read one data
point from the device and also had to deal with certain error conditions for example if
the power supply to the hardware, or even the USB cable had been disconnected and then
reconnected. Those developers can still use all of their original old style commands
for initialization, but replace the old way of getting one data point with the new call
to "SP_GetOneConversion(...).
If a developer would prefer to use the old style method to read/write the a device,
but would like to know the condition of the device and have the DLL try to recover
from any errors, then they could replace the call to "DLL_ReadWriteOneDevice(...)"
with a call to "SP_ReadWriteOneDevice(...)" as described elsewhere in
this document. That function call not only attempts to read or write the device (depending
on the argument) but also attempts to recover from any I/O error and then set flags (also
passed as an argument) to indicate the current state of the device.
The prototypes shown in this document default to the "C" language style prototype.
Following each prototype is a link to the VisualBasic style prototype for the
function call.
It's important to note that our DLL uses a BOOLEAN data type in many of the prototypes.
The size of that data type is one BYTE or 8-bits. That issue is also discussed in the
"variable types" section of this document. Also note that the calling conventions
is "_stdcall". The data alignment for structured data is "4 bytes"
which is the default for most simplified programming environments such as
VisualBasic and LabView which don't have the option to set such an alignment. We suggest
that VisualC++ programmers either set that option in their compiler settings or force
the setting in their source files using the appropriate "#pragma pack(push, 4)"
and "#pragma pack(pop)" directives.
back
-
Variable types
-
The following is a chart of the various data types used as either
passed or return arguments in function calls to DLL. For those non-C
programmers, note that an asterix following a variable within a prototype,
such as BYTE*, indicates the argument to be a pointer to either a variable
or an array of that data type. The function call prototypes will indicate
whether the pointer is to a variable or an array.
|
TYPE
|
SIZE
|
PREFIX
|
EXAMPLE
|
|
BOOLEAN
|
8-bit unsigned data type (1=TRUE, 0=FALSE)
|
f
|
fCallRetVal
|
|
BYTE
|
8-bit unsigned data type
|
b
|
bNumChans
|
|
USHORT
|
16-bit unsigned data type
|
us
|
usDeviceID
|
|
SHORT
|
16-bit signed data type
|
s
|
sPlusMinusVal_16
|
|
UINT
|
32-bit unsigned data type
|
ui
|
uiRawCount
|
|
INT
|
32-bit signed data type
|
i
|
iPlusMinusVal_32
|
|
DOUBLE
|
64-bit floating point data type
|
dbl
|
dblVoltage
|
|
STRING
|
zero delimited string
|
sz
|
szMyString
|
Below is an example of a pointer to a unsigned short variable type followed
by an example of a pointer to an array of unsigned short data types. Note
that one example is prefixed with "pus" and the other with "paus".
|
USHORT*
|
pointer to a 16-bit variable
|
pus
|
pusMyDevice
|
|
USHORT*
|
pointer to array of 16-bit data types
|
paus
|
pausMyDevices
|
back
to main page Table of Contents
(use browser "back" button to go back to other locations)
|