PROGRAMMING API DEFINITIONS FOR AEC_NTTC.DLL
May 25, 2000
Copyright (C)2000 Adrienne Electronics Corporation
The AEC_NTTC.DLL file has been developed to allow Windows NT programmers
to easily interface to any of the time code boards made by Adrienne
Electronics Corporation. This Dynamic Link Library (DLL) file seamlessly
integrates the reading and/or writing of data to all Adrienne Electronics
time code boards through the use of only a few API functions.
The ability to set up Win32 interrupt service routines has been
included in this time code board API. Some important notes and issues
related to installing and using this DLL file will now be addressed,
followed by a description of each of the API functions in the DLL.
This DLL is 32-bit and is written explicitly for personal computers having
Intel 32-bit microprocessors and running the Windows NT/9x operating system.
This code was developed using the Microsoft SDK and Visual C++ 6.0.
NOTES:
1) Be sure that the AEC_NTTC.DLL file is copied into a directory that is
in the "path" of the executing file, so that the API functions can be
accessed when they are needed.
2) Put the AEC_NTTC.lib file into the link line of the executable file
to obtain dynamic linking of the DLL at load-time. See the Visual C++
Books Online 4.0 -- Win32 SDK:Win32, Overviews, System Services,
"Using Load-Time Dynamic Linking". For example, the following lines
could be included in your application's make file:
# Link YourApp.obj and AEC_NTTC.lib to create YourApp.exe:
YourAp.exe: YourAp.obj AEC_NTTC.lib
$(link) $(conflags) \
-out:YourAp.exe YourAp.obj AEC_NTTC.lib $(conlibs) )
3) For run-time loading you can use the "LoadLibrary("AEC_NTTC")"
function which gives better error handling. See the Visual C++ Books
Online 4.0 -- Win32 SDK:Win32, Overviews, System Services,
"Using Run-Time Dynamic Linking". However, the DLL file does NOT use
a large amount of data and it easier to work with when it is statically
linked.
4) Effective with AEC_NTTC.DLL revision "B1", all DLL functions use the
"WINAPI" calling convention, which is the same convention used for
all other Windows NT API functions. Revision "A1" of our DLL used
the "__cdecl" calling convention, and did not work with Visual Basic.
As a result, we recommend that you not use revision "A1" of our DLL.
5)
** New with revision 'C1' of the DLL, support for the AEC PCI-TC
products is now included in the DLL.
## For all AEC PC-TC (ISA) device models under Windows NT/2000:
a) Copy the WinRT.sys file into the 'C:\WINDOWS\System32\drivers\'
directory with the other '.sys' files. Change the path as needed
if your "windows" directory is not "WINDOWS".
b) Run the Adrienne Electronics program, "AECSETUP.EXE", to automatically
register the "WinRT.sys" device driver devices in the Windows NT
registry. You can verify the results of running this setup program by
running the "regedt32.exe" program found in the Windows NT directory
tree. After the regedt32.exe program is started, go to:
HKEY_LOCAL_MACHINE -> SYSTEM -> CurrentControlSet -> Services ->
WinRT -> WinRTdev0 (or WinRTdev1...) -> Parameters -> Section0.
You should now see the information you entered when running the
"AECSETUP.EXE" program.
## For all AEC PC-TC (ISA) device models under Windows 9x:
a) Copy the WRTdev0.vxd file into the 'C:\WINDOWS\System\VMM32\'
directory with the other '.vxd' files. Change the path as needed
if your "windows" directory is not "WINDOWS".
b) Run the Adrienne Electronics program, "AECSET95.EXE", to automatically
register the device driver devices in the Windows 9x registry.
## For all AEC PCI-TC (PCI) device models under Windows NT/2000:
1) Run "instdrv.exe" in the 'INSTALNT' directory.
This should set up the registry AND copy the 'aecpcitc.sys' file to
the ...\system32\drivers\ dirctory.
## For all AEC PCI-TC (PCI) device models under Windows 9x:
a)Install the time code board and turn on the PC. The machines
"PLUG-n-PLAY" system should detect the board and ask where the needed
files (driver (.vxd) and .inf) are located. These files are located in
the 'INSTAL9x' directory (here).
6) Copy the AEC_NTTC.DLL (C1) file to the following directory:
if (Windows NT/2000) ...\windows\system32\
if (Windows 9x) ...\windows\system\
With the file in this location, it can be access from anywhere in the
machine.
SPECIAL NOTE 1:
NONE OF THE FUNCTION CALLS THAT FOLLOW IN THE DLL API WILL WORK WITH A
TIME CODE BOARD IF THE DEVICE HAS NOT BEEN PLACED IN THE DEVICE REGISTRY
BY THE Setup/install PROGRAM !!! (see 5) above).
SPECIAL NOTE 2: COMPILER PROBLEM
This library is C code. When programming in C++, there may be a problem with
decorated names of the library, C++ can't recognize the C names in a library. So,
you will have to import the library and include the header file using the
"extern "C" { include file}.
If you include the aec_nttc.h file, you may not be able to compile without problems.
but if you include aecinttc.h using "extern "C"{#include "aecinttc.h} you should compile
without errors and warnings.
SPECIAL NOTE 3:
Since the AEC PCI-TC boards are NOT placed at the "same" address each
time the computer comfigures the PCI device (upon bootup), the DLL supports
an defined set of values that are to be used for the BASE ADDRESS parameter
in each of the DLL functions when calling. The set of values is 0x1000
(first board in PC), 0x1100 (for second board in PC), 0x1200 (for the
third board in the PC), ... and so on. Up to 18 boards can be placed in
a PC (if you have that many slots). At the time of this document, only
ONE device at a time is supported by the Windows9x driver (AecPciTC.vxd).
It is planned to support more devices in the future. See the sample
programs function "FindBoards" for an example.
-------------------------------------------------------------------------
AEC_NTTC.DLL FUNCTION Group
(DLL API)
DLL Function Listing
AEC_PCTC_CHECK_BOARD (LPWORD)
AEC_PCTC_READ_TB (LPDWORD, LPWORD)
AEC_PCTC_READ_TBE (LPDWORD, LPWORD)
AEC_PCTC_READ_UB (LPDWORD, LPWORD)
AEC_PCTC_READ_ASC_TB (LPSTR, LPWORD)
AEC_PCTC_READ_ASC_UB (LPSTR, LPWORD)
AEC_PCTC_READ_1BYTE (LPBYTE, LPWORD, LPWORD)
AEC_PCTC_READ_4BYTES (LPDWORD, LPWORD, LPWORD)
AEC_PCTC_WRITE_1BYTE (LPBYTE, LPWORD, LPWORD)
AEC_PCTC_WRITE_4BYTES (LPDWORD, LPWORD, LPWORD)
AEC_PCTC_SEND_COMMAND (LPBYTE, LPBYTE, LPWORD)
AEC_PCTC_GET_INTCODE (LPBYTE, LPBYTE, LPWORD)
AEC_PCTC_GET_DLL_INFO (LPSTR)
AEC_PCTC_GET_SELECTOR (LPWORD, LPWORD)
AEC_PCTC_UNINSTALL_BOARD (LPWORD)
AEC_PCTC_ECHO_ADDR (LPWORD)
AEC_PCTC_GET_NUMBER_OF_DEVICES (VOID)
AEC_PCTC_DWORD_TO_STR (LPBYTE, LPDWORD, LPSTR)
AEC_PCTC_GET_BOARD_POINTER (LPWORD)
AEC_PCTC_GET_BOARD_INT_POINTER (LPWORD)
AEC_PCTC_INIT_BRD_INT (LPHANDLE, LPINT, LPWORD)
AEC_PCTC_ISR_1 (LPWORD)
AEC_PCTC_ISR_2 (LPWORD)
AEC_PCTC_ISR_3 (LPWORD)
--------------------------------------------------------------------------
AEC_PCTC_CHECK_BOARD QuickInfo Overview Group
The AEC_PCTC_CHECK_BOARD function looks for a time code board
at the "address" that is passed as a parameter. The board MUST
have been previously registered in the Windows NT registry.
Use the AECSETUP.EXE program to register the board if needed.
int AEC_PCTC_CHECK_BOARD(
LPWORD lpBrdAddr
);
PARAMETERS:
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a number (TYPE int) that tells
the calling program what board (if any) was found
at that address.
Returns a completion code:
00h => No board found.
01h => An IOR board was found. (PC-LTC/IOR)
02h => An MMR board was found. (PC-LTC/MMR)
03h => A "SMART" PC-LTC, PC-VITC, or
PC-VLTC board was found (RDR, GEN, RG1, etc.).
REMARKS:
This function leaves the device in the same (open or
closed) state that it found the device in upon entry.
This function is very useful for detecting the presence
of time code boards programmatically, and for determining
if the time code board is functional prior to reading
and/or writing data, etc..
------------------------------------------------------------------------
AEC_PCTC_READ_TB QuickInfo Overview Group
The AEC_PCTC_READ_TB function returns the 'time bits' portion
of the currently selected time code reader data (for the board
whose address is passed as a parameter), placing this data
(after stripping out the embedded bits) into the double word
whose address is also passed as a parameter.
BOOL AEC_PCTC_READ_TB(
LPDWORD lpTime,
LPWORD lpBrdAddr
);
PARAMETERS:
lpTime
Identifies the address of a four byte (32bit)
double word that will get the 'time' data written
into it. The 'time' data will be in a packed BCD
format (ie: 0xHHMMSSFF ). The time data will be
written with the embedded bits removed (stripped
out) from the data, thus giving only the time.
The data placed here will always come from the
time code board's offset addresses 00h-03h (the
first four bytes on the board).
(ie: lpTime = &dwTime ( DWORD dwTime;)
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Reads the current selected time bits (with no embedded
bits) into a far doubleword variable. Reads the time
bits on-the-fly, without waiting for any interrupt codes.
For IOR and MMR boards, this function always reads the
byte at offset 09h (to select reading of time data)
prior to reading the time data.
-----------------------------------------------------------------------
AEC_PCTC_READ_TBE QuickInfo Overview Group
The AEC_PCTC_READ_TBE function returns the 'time and embedded
bits' portion of the currently selected time code reader data
(for the board whose address is passed as a parameter),
placing this data (WITH embedded bits) into the double word
whose address is also passed as a parameter.
BOOL AEC_PCTC_READ_TBE(
LPDWORD lpTimeE,
LPWORD lpBrdAddr
);
PARAMETERS:
lpTimeE
Identifies the address of a four byte (32bit)
double word that will get the 'time+' data written
into it. The 'time+' data will be in a packed BCD
format (ie: 0xHHMMSSFF ). The time data will be
written WITH the embedded bits left in.
The data placed here will always come from the
time code board's offset addresses 00h-03h (the
first four bytes on the board).
(ie: lpTimeE = &dwTimeE ( DWORD dwTimeE;)
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Reads the current selected time bits (WITH embedded
bits) into a far doubleword variable. Reads the time
bits on-the-fly, without waiting for any interrupt codes.
For IOR and MMR boards, this function always reads the
byte at offset 09h (to select reading of time data)
prior to reading the time data.
------------------------------------------------------------------------
AEC_PCTC_READ_UB QuickInfo Overview Group
The AEC_PCTC_READ_UB function returns the 'user bits' portion
of the currently selected time code reader data (for the board
whose address is passed as a parameter), placing this data
into the double word whose address is also passed as a parameter.
BOOL AEC_PCTC_READ_UB(
LPDWORD lpUser,
LPWORD lpBrdAddr
);
PARAMETERS:
lpUser
Identifies the address of a four byte (32bit)
double word that will get the 'user' data written
into it. The 'user' data will be in a packed BCD
format (ie: 0xHHMMSSFF ).
(ie: lpUser = &dwUser ( DWORD dwUser;)
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Reads the current selected user bits into a far
doubleword variable. Reads the user bits on-the-fly,
without waiting for any interrupt codes. For IOR and
MMR boards, this function always reads the byte at
offset 08h (to select reading of user data) prior to
reading the user data bytes. For PC-VLTC boards,
reads the user bits data at offset addresses 004h-007h.
For PC-VITC and all other PC-LTC boards, reads the user
bits data at offset addresses 010h - 013h.
------------------------------------------------------------------------
AEC_PCTC_READ_ASC_TB QuickInfo Overview Group
The AEC_PCTC_READ_ASC_TB function returns an ASCII string
representation of the 'time bits' (with no embedded bits)
portion of the currently selected time code reader data
(for the board whose address is passed as a parameter),
placing this ASCII string data into the string whose address
is also passed as a parameter.
int AEC_PCTC_READ_ASC_TB(
LPSTR lpStrT,
LPWORD lpBrdAddr
);
PARAMETERS:
lpStrT
Identifies the address of the string that will get
the 'time string' data written into it. The 'time
string' will be in ASCII string format ('HH:MM:SS:FF').
The time data will be written with the embedded
bits removed (stripped out) from the data, thus
giving only the time. The data placed here will
always come from the time code board's offset
addresses 00h-03h (the first four bytes on board),
which are then unpacked/converted to an ASCII string.
You should always pass a string that is at least
12 characters long (ie: char str[12]).
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns an int value of '11' (0Bh).
The string will have 11 data bytes followed by a NULL
(00h) character. You should always pass a string that
is at least 12 characters long (ie: char str[12]).
REMARKS:
Reads the current selected time bits (with no embedded
bits) into a far string variable. Reads the time
bits on-the-fly, without waiting for any interrupt codes.
For IOR and MMR boards, this function always reads the
byte at offset 09h (to select reading of time data)
prior to reading the time data. After the data is read,
it is unpacked/converted into the equivalent ASCII string.
This function is an ASCII string equivalent of the
(packed BCD) 'AEC_PCTC_READ_TB' function.
------------------------------------------------------------------------
AEC_PCTC_READ_ASC_UB QuickInfo Overview Group
The AEC_PCTC_READ_ASC_UB function returns an ASCII string
representation of the 'user bits' portion of the currently
selected time code reader data (for the board whose address
is passed as a parameter), placing this ASCII string data into
the string whose address is also passed as a parameter.
int AEC_PCTC_READ_ASC_UB(
LPSTR lpStrU,
LPWORD lpBrdAddr
);
PARAMETERS:
lpStrU
Identifies the address of the string that will get
the 'user string' data written into it. The 'user
string' will be in ASCII string format ('HH:MM:SS:FF').
The data placed here will come from the time code
board's user data area (00h-03h for IOR & MMR boards,
04h-07h for PC-VLTC boards, and 10h-13h for PC-VITC
and all other PC-LTC boards). This data is unpacked
and then converted into the equivalent ASCII string.
You should always pass a string that is at least
12 characters long (ie: char str[12]).
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns an int value of '11' (0Bh).
The string will have 11 data bytes followed by a NULL
(00h) character. You should always pass a string that
is at least 12 characters long (ie: char str[12]).
REMARKS:
Reads the current selected user bits data into a far
string variable. Reads the user bits data on-the-fly,
without waiting for any interrupt codes. For IOR and MMR
boards, this function always reads the byte at offset 08h
(to select reading of user data) prior to reading the
user data. After the data is read, it is unpacked
and converted into the equivalent ASCII string.
This function is an ASCII string equivalent of the
(packed BCD) 'AEC_PCTC_READ_UB' function.
------------------------------------------------------------------------
AEC_PCTC_READ_1BYTE QuickInfo Overview Group
The AEC_PCTC_READ_1BYTE function reads one data byte at the
offset address specified (for the board whose address is
also passed as a parameter), and places the data into the
byte variable whose address is passed as a parameter.
BOOL AEC_PCTC_READ_1BYTE(
LPBYTE lpReadB,
LPWORD lpAddrOff,
LPWORD lpBrdAddr
);
PARAMETERS:
lpReadB
This parameter points to the byte variable which will
receive the single data byte read from the board.
lpAddrOff
This parameter points to a 16-bit word which contains
an OFFSET address (relative to the base address of the
board) for the byte to be read from the board.
Note that the offset address must be limited to 00h-1Fh
for IOR & MMR boards, and must be limited to 000h-3FFh
for all other PC-LTC, PC-VITC, and PC-VLTC boards.
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Reads the byte at the desired offset address
(with respect to the board's base address).
------------------------------------------------------------------------
AEC_PCTC_READ_4BYTES QuickInfo Overview Group
The AEC_PCTC_READ_4BYTES function reads four data bytes at
the offset address specified (for the board whose address is
also passed as a parameter), and places the data into the
double word variable whose address is passed as a parameter.
BOOL AEC_PCTC_READ_4BYTES(
LPDWORD lpReadL,
LPWORD lpAddrOff,
LPWORD lpBrdAddr
);
PARAMETERS:
lpReadL
This parameter points to the double word variable
which will receive the four bytes read from the board.
lpAddrOff
This parameter points to a 16-bit word which contains
an OFFSET address (relative to the base address of the
board) for the byte to be read from the board.
Note that the offset address must be limited to 00h
for IOR & MMR boards, and must be limited to 000h-3FCh
for all other PC-LTC, PC-VITC, and PC-VLTC boards.
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Reads the four bytes starting at the desired offset
address (with respect to the board's base address).
For IOR and MMR boards, the only allowable offset value
is 00h (any other value will return an error).
------------------------------------------------------------------------
AEC_PCTC_WRITE_1BYTE QuickInfo Overview Group
The AEC_PCTC_WRITE_1BYTE function writes one data byte
(whose address is passed as a parameter) to the offset
address specified (for the board whose address is also
passed as a parameter). Note that this function is not
valid for IOR and MMR boards, which are "read only" devices
(an error code will be returned).
BOOL AEC_PCTC_WRITE_1BYTE(
LPBYTE lpWriteB,
LPWORD lpAddrOff,
LPWORD lpBrdAddr
);
PARAMETERS:
lpWriteB
This parameter points to the data byte which will
be written to the board.
lpAddrOff
This parameter points to a 16-bit word which contains
an OFFSET address (relative to the base address of the
board) indicating where the data byte should be written to.
Note that the offset address must be limited to 000h-3FFh.
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Writes a byte to the desired offset address
(with respect to the board's base address).
------------------------------------------------------------------------
AEC_PCTC_WRITE_4BYTES QuickInfo Overview Group
The AEC_PCTC_WRITE_4BYTES function writes four data bytes
(whose lowest address is passed as a parameter) to the offset
address specified (for the board whose address is also
passed as a parameter). Note that this function is not
valid for IOR and MMR boards, which are "read only" devices
(an error code will be returned).
BOOL AEC_PCTC_WRITE_4BYTES(
LPDWORD lpWriteL,
LPWORD lpAddrOff,
LPWORD lpBrdAddr
);
PARAMETERS:
lpWriteL
This parameter points to the double word which contains
the four bytes to be written to the board.
lpAddrOff
This parameter points to a 16-bit word which contains
an OFFSET address (relative to the base address of the
board) indicating where the data bytes should be written to.
Note that the offset address must be limited to 000h-3FCh.
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Writes four bytes starting at the desired offset address
(with respect to the board's base address).
------------------------------------------------------------------------
AEC_PCTC_SEND_COMMAND QuickInfo Overview Group
The AEC_PCTC_SEND_COMMAND function writes the command byte
(whose address is passed as a parameter) to address offset 3FFh
(on the board whose address is also passed as a parameter).
The board's command acknowledgement byte is then returned in a
separate byte variable (whose address is passed as a parameter).
This process normally completes in under 100us, but in extreme
cases could take up to 50ms (board missing, etc.).
Note that this function is not valid for IOR and MMR boards
(an error code will be returned).
BOOL AEC_PCTC_SEND_COMMAND(
LPBYTE lpCommandB,
LPBYTE lpReturnB,
LPWORD lpBrdAddr
);
PARAMETERS:
lpCommandB
This parameter points to the command code data byte
which will be written to the board at address offset 3FFh.
lpReturnB
This parameter points to the byte variable which will
receive the board's command acknowledgement code.
This return code is the byte read at offset 3FEh,
or the last code found, or 00h if nothing is found.
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a TRUE (1, OK) or FALSE (0, error).
REMARKS:
Writes the desired command byte to board offset 3FFh
after waiting for that address to equal FFh.
The command acknowledgement byte at 3FEh is then read
and returned at the lpReturnB address. This process
normally completes in under 100us, but in extreme
cases could take up to 50ms (board missing, etc.).
IMPORTANT:
This function will always return 00h if an interrupt
service routine is catching and resetting the hardware
interrupts (reading offset 3FEh), because this function
generates an interrupt. This means that the "ISR" steals
the command acknowledgement from this function. Calling
this function will always create a hardware interrupt
if you have enabled the IRQ!
------------------------------------------------------------------------
AEC_PCTC_GET_INTCODE QuickInfo Overview Group
The AEC_PCTC_GET_INTCODE function reads the interrupt ID code
byte at offset 3FEh (on the board whose address is passed as
a parameter), and returns this byte to the byte variable whose
address is also passed as a parameter. A 'delay' data byte
(whose address is passed as a parameter) can be used to determine
how long (up to 50ms) this function will wait for an interrupt
ID code to appear at offset address 3FEh. If no interrupt ID
code is found before the end of the desired delay period,
a 00h byte is returned. Note that this function is not valid
for IOR and MMR boards (an error code will be returned).
BOOL AEC_PCTC_GET_INTCODE(
LPBYTE lpWaitMsB,
LPBYTE lpReturnB,
LPWORD lpBrdAddr
);
PARAMETERS:
lpWaitMsB
This parameter points to the data byte which determines
how long (if at all) this function will wait for an
interrupt code to appear at board offset address 3FEh.
This data byte should have a value of 0d-50d (00h-32h),
which specifies a maximum delay of 0-50ms respectively.
This value will be limited to 50d (50ms) maximum if needed,
so this function will always return within 50ms worst case.
A delay value of 00h causes this function to return
immediately after checking 3FEh, without any further wait.
lpReturnB
This parameter points to the byte variable which will
receive the interrupt ID code read from offset 3FEh.
If an interrupt code is already pending, it is returned
immediately. Otherwise this function waits up to 50ms
(see above) for an interrupt code to appear. Whenever
an interrupt ID code is found, this function reads it,
then prepares the board to send the next interrupt.
If no interrupt is found, 00h is returned.
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a completion code which is
TRUE (1, OK) if found/read an interrupt,
or FALSE (0, error) otherwise.
REMARKS:
This function should not be used if your application
is using hardware interrupts (while they are enabled).
Read the following...
IMPORTANT:
This function will always return 00h if an interrupt
service routine is catching and resetting the hardware
interrupts (reading offset 3FEh), because any change to
the data at 3FEh generates a hardware interrupt. This
means that the "ISR" steals the interrupt ID code from
this function. Once a hardware interrupt service routine
is enabled (by calls to AEC_PCTC_ISR_1, etc.), this
function is of no use as long as the ISR remains active.
------------------------------------------------------------------------
AEC_PCTC_GET_DLL_INFO QuickInfo Overview Group
The AEC_PCTC_GET_DLL_INFO function returns the DLL revision
code (letter/number) in the string that is passed as a parameter.
int AEC_PCTC_GET_DLL_INFO(
LPSTR lpInfoStr,
);
PARAMETERS:
lpInfoStr
This parameter points to a string variable. The
string that is passed should be at least 3 bytes
long (ie: str[3]). The data will be written as two
ASCII characters followed by a NULL (00h) byte.
The characters will be the revision letter followed
by the revision number (for example, "A1").
RETURN VALUE:
The function returns an integer value of 2 (02h).
REMARKS:
This function is very useful for debugging and for
verifying that your application is correctly interfacing
to the DLL.
------------------------------------------------------------------------
AEC_PCTC_GET_SELECTOR QuickInfo Overview Group
The AEC_PCTC_GET_SELECTOR function is obsolete when used under
the Windows NT operating system. It is included here only
to provide backwards compatibility with the 16-bit 'AECPC-TC.DLL'
DLL used under Windows 3.1 and Windows 95. For Windows NT
applications, see the new API function 'AEC_PCTC_GET_BOARD_POINTER'.
BOOL AEC_PCTC_GET_SELECTOR(
LPWORD lpDat,
LPWORD lpBrdAddr
);
PARAMETERS:
lpDat
Don't care what the value is.
lpBrdAddr
Don't care what the value is.
RETURN VALUE:
This function returns FALSE (0) with Windows NT.
REMARKS:
This function is obsolete except to possibly be used
while debugging to return a 'FALSE' from the DLL.
-----------------------------------------------------------------------
AEC_PCTC_UNINSTALL_BOARD QuickInfo Overview Group
The AEC_PCTC_UNINSTALL_BOARD function can be used to free up
handles for devices that are no longer needed. All registered
devices are automatically "installed" ("opened") the first time
they are accessed by this DLL. The only exception to this rule
is the 'CHECK_BOARD' function, which leaves the board's
open/closed status the same as it was upon entry. A device will
not be opened if it cannot be found in the device registry.
BOOL AEC_PCTC_UNINSTALL_BOARD(
LPWORD lpBrdAddr
);
PARAMETERS:
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
This function returns a TRUE (1, OK) if successful,
otherwise FALSE (0, error).
REMARKS:
This function does not have the same resource
'freeing' capabilities that the 16-bit DLL version
has. The differences are entirely in how the
operating system allows software to talk to the
hardware. This Windows NT 32-bit DLL automatically will
release all open device handles when the DLL is closed
by the operating system. There is little need to ever
use this function. If this function is used, all
HANDLES AND POINTERS that the operating system allocated
for this device will become illegal (obsolete). This
will have special effects on your software if you use
this DLL to pass back pointers and handles that you
store and use in the executable file.
------------------------------------------------------------------------
AEC_PCTC_ECHO_ADDR QuickInfo Overview Group
The AEC_PCTC_ECHO_ADDR function returns an "int" equivalent
of the "board address" variable whose address you supply
as a parameter. Useful for debugging your application code.
This function does not interface to the board hardware.
int AEC_PCTC_ECHO_ADDR(
LPWORD lpBrdAddr
);
PARAMETERS:
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns an int which is the value of
the base address of the board that is passed to the
DLL ( int = (int) *(lpBrdAddr) ).
(ie: 0xcc00 = AEC_PCTC_ECHO_ADDR(&BrdAddr) )
REMARKS:
This function is useful for verifying that your code is
correctly calling and linking to the DLL. Recommended
for use in debugging the DLL calling executable code.
------------------------------------------------------------------------
AEC_PCTC_GET_NUMBER_OF_DEVICES QuickInfo Overview Group
The AEC_PCTC_GET_NUMBER_OF_DEVICES function returns the number of
devices that the DLL detected upon being loaded by the operating
system. This count is based upon the device registry and should
be the same as the number of "WinRTdevX" devices (where X = 0-15)
that the 'DLLMAIN' function automatically detected. In other
words, the number of AEC time code boards installed in the
computer should equal the count that this function returns.
int AEC_PCTC_GET_NUMBER_OF_DEVICES(
VOID
);
PARAMETERS:
(NONE)
RETURN VALUE:
This function returns an int which has a value from 0-16d.
If only one time code board is installed, should be 01h.
REMARKS:
This function is useful for verifying that each of the
time code boards which have been installed in the computer
have been detected as being correctly registered via the
AECSETUP.EXE program.
------------------------------------------------------------------------
AEC_PCTC_DWORD_TO_STR QuickInfo Overview Group
The AEC_PCTC_DWORD_TO_STR function reads the four bytes (DWORD)
pointed to by function parameter 2, then unpacks, converts, and
stores the data into an equivalent ASCII string whose address
is passed as parameter 3. The data is stored as an 11-byte
ASCII string with standard "HH:MM:SS:FF" format. The 'command
byte' parameter determines the returned string format (see below).
int AEC_PCTC_DWORD_TO_STR(
LPBYTE lpComB,
LPDWORD lpFourB,
LPSTR lpStr11,
);
PARAMETERS:
lpComB
This parameter points to a 'command byte' which determines
the returned string format:
00h => Time bits display, so strip out all embedded
bits ('AND' packed BCD data with 0x3F7F7F3F).
01h => User bits display (print "A"-"F" if found).
lpFourB
This parameter points to the 4-byte doubleword which
contains the packed BCD "input data".
lpStr11
Identifies the address of a string that will get the
'unpacked' data written into it. The data will be in
an ASCII string format (ie: "HH:MM:SS:FF"). The data
will be written with the embedded bits removed (stripped
out) if the command byte equals 00h, or will be written
as straight hexadecimal data (like user bits) if the
command byte equals 01h. You should always pass a string
that is at least 12 characters long (ie: char str[12]).
RETURN VALUE:
The function returns an int value of '11' (0Bh).
The string will have 11 data bytes followed by a NULL
(00h) character. You should always pass a string that
is at least 12 characters long (ie: char str[12]).
REMARKS:
This function is callable even if no time code board
is installed in the computer. The unpacking routine
is the same as that used by the ..._ASC_... functions
described earlier.
------------------------------------------------------------------------
AEC_PCTC_GET_BOARD_POINTER QuickInfo Overview Group
The AEC_PCTC_GET_BOARD_POINTER function can be used to pass back
a void pointer that can be used to index into the time code
board's DPRAM and do direct memory pointer access. This call
passes back the pointer that is created when the device is first
opened (first handle). Note that this function is not available
for the PC-LTC/IOR board. This Windows NT function replaces
the Windows 3.1 and Windows 95 'GET_SELECTOR' API function.
PVOID AEC_PCTC_GET_BOARD_POINTER(
LPWORD lpBrdAddr
);
PARAMETERS:
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
This function returns the pointer which is allocated if
the DLL successfully maps the board's address space onto
the memory space of the process. If unsuccessful,
a value of 0xFFFFFFFF is returned. For example:
PVOID pvBoard;
LPBYTE lpBoard;
pvBoard = AEC_PCTC_GET_BOARD_POINTER(&Address);
lpBoard = (LPBYTE)pvBoard;
REMARKS:
The pointer that this function returns will be valid (if
no error) until the 'UNINSTALL_BOARD' function is called
for that board, or until the DLL is closed.
------------------------------------------------------------------------
AEC_PCTC_GET_BOARD_INT_POINTER QuickInfo Overview Group
The AEC_PCTC_GET_BOARD_INT_POINTER function can be used to pass
back a void pointer that can be used to index into the time code
board's DPRAM and do direct memory pointer access. This call
passes back the pointer that is created when the operating system
opens a SECOND handle to the device, which would typically be used
by an interrupt service routine thread. Note that this function
is not available for the PC-LTC/IOR board. This function is very
similar to the 'AEC_PCTC_GET_BOARD_POINTER' function.
PVOID AEC_PCTC_GET_BOARD_INT_POINTER(
LPWORD lpBrdAddr
);
PARAMETERS:
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
This function returns the pointer which is allocated if
the DLL successfully maps the board's address space onto
the memory space of the process. If unsuccessful,
a value of 0xFFFFFFFF is returned. For example:
PVOID pvBoard;
LPBYTE lpBoard;
pvBoard = AEC_PCTC_GET_BOARD_POINTER(&Address);
lpBoard = (LPBYTE)pvBoard;
REMARKS:
The pointer that this function returns will be valid (if
no error) until the 'UNINSTALL_BOARD' function is called
for that board, or until the DLL is closed. This function
provides a second available pointer to the board. This
pointer can be used in an interrupt-service routine thread.
------------------------------------------------------------------------
AEC_PCTC_INIT_BRD_INT QuickInfo Overview Group
The AEC_PCTC_INIT_BRD_INT function is used to set up a new
Windows NT "thread" for hardware interrupt driven applications.
This function writes a valid handle to the memory location
pointed to by parameter 1, and writes an integer value to the
memory location pointed to by parameter 2, all for the board
whose address is pointed to by parameter 3.
BOOL AEC_PCTC_INIT_BRD_INT(
LPHANDLE lphandle,
LPINT lpIntIndex,
LPWORD lpBrdAddr
);
PARAMETERS:
lphandle
Points to an uninitialized handle. If successful,
this function will write a valid handle to this
address. The new handle can then be used to set up
interrupt service routine (ISR) threads.
lpIntIndex
Points to an integer that will be written to with
an index value "X", where "X" is taken from the end
of "WinRTdevX". Needed but not used in demo code
at this time (could be used to verify registry items).
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
The function returns a completion code which is
TRUE (1, OK) or FALSE (0, error). Note that the
return value will be FALSE if no IRQ (interrupt)
line (ie: 2, 3, 4, 5, 10, 11, 12, or 15) has been
entered into the REGISTRY for the selected device.
REMARKS:
See the sample source code that creates separate threads
to handle the device's hardware interrupts. The new
threads will handle the ISR for your application.
Also, see the following ...ISR_n... functions.
------------------------------------------------------------------------
AEC_PCTC_ISR_1 QuickInfo Overview Group
The AEC_PCTC_ISR_1 function prepares the Windows NT operating
system to receive and handle interrupts for the board whose
address you passed as a parameter. Upon receiving an interrupt,
this function reads a byte and clears the interrupt, then control
is passed back to the calling thread. For IOR and MMR boards,
returns TRUE (1, OK) or FALSE (0, error). For PC-VITC, PC-VLTC,
and all other PC-LTC boards, returns the interrupt code byte
that was read at address offset 3FEh.
NOTE: This function must not be called before the
'AEC_PCTC_INIT_BRD_INT' function is called and returns OK!!!
Also, make sure that no interrupts are pending when this function
is called!!! See the sample code on how to use this function.
BYTE AEC_PCTC_ISR_1(
LPWORD lpBrdAddr
);
PARAMETERS:
lpBrdAddr
Identifies the base address where the board
is installed (or may be installed). For example,
set lpBrdAddr = &Address, where WORD Address = 0xCC00
(memory mapped), or Address = 0x2A0 (I/O mapped).
Set Address to match the board's address jumper.
RETURN VALUE:
Returns the byte that was read at 3FEh (for smart boards),
or a TRUE (1, OK) or FALSE (0, error) for IOR & MMR boards.
REMARKS:
For IOR and MMR boards, this function waits for an
interrupt, then it reads address offset 00h to clear the
interrupt. It passes back TRUE if there are no errors.
For PC-VITC, PC-VLTC, and all other PC-LTC boards, this
function waits for an interrupt, then it reads the byte
at address offset 3FEh to clear the interrupt. Then the
function writes 00h to 3FDh and 3FFh to enable the next
interrupt, and passes control and the 3FEh byte back to
the calling thread. The interrupt service routine in the
calling thread should be as short as possible. See the
sample code for interrupt driven applications.
If you are using hardware interrupts, this function
will catch all of the command acknowledgments that the
board will generate after receiving a command at offset
3FFh. See the 'AEC_PCTC_GET_INTCODE' function.
-----------------------------------------------------------------------
AEC_PCTC_ISR_2 QuickInfo Overview Group
The AEC_PCTC_ISR_2 function is a copy of the 'AEC_PCTC_ISR_1'
function that will allow a second board to run a hardware
interrupt driven thread. This function will only be used if
more than one time code board is used in the system. See the
notes above for the 'AEC_PCTC_ISR_1' function for further info.
------------------------------------------------------------------------
AEC_PCTC_ISR_3 QuickInfo Overview Group
The AEC_PCTC_ISR_3 function is a copy of the 'AEC_PCTC_ISR_1'
function that will allow a third board to run a hardware
interrupt driven thread. This function will only be used if
more than two time code boards are used in the system. See the
notes above for the 'AEC_PCTC_ISR_1' function for further info.
***************************** END of FILE ******************************
Download Driver Pack
After your driver has been downloaded, follow these simple steps to install it.
Expand the archive file (if the download file is in zip or rar format).
If the expanded file has an .exe extension, double click it and follow the installation instructions.
Otherwise, open Device Manager by right-clicking the Start menu and selecting Device Manager.
Find the device and model you want to update in the device list.
Double-click on it to open the Properties dialog box.
From the Properties dialog box, select the Driver tab.
Click the Update Driver button, then follow the instructions.
Very important: You must reboot your system to ensure that any driver updates have taken effect.
For more help, visit our Driver Support section for step-by-step videos on how to install drivers for every file type.