Overview of the Winford Engineering Portal API
Winford Engineering is pleased to provide an API
for programming and controlling Winford Engineering's complete line of
Portal I/O cards. This overview is intended to show how different functions of
the API work together. To gain a better understanding of the individual
functions, you should access specific function documentation from the reference
page. Also you should check the programming guide for the card model that you have.
What is the API and why do I need it?
API stands for Application Programming Interface.
This API is a set of functions and routines provided to you, the programmer
and user, to make the use of Winford's I/O Cards easy, reliable, and consistent.
Although I/O cards may be directly programmed by using low-level input
and output functions, the API provides a more intuitive method. When using
the Portal API, the programmer does not need to know how the card works nor how
to use the card with low-level input and output functions. Because the
programmer doesn't need to keep track of numerous details, the API helps
to avoid frustrating mistakes and bugs.
How do I use the Portal API?
Before you can create programs using the API, you must
do two things: install it on your system, and
learn how to call the API functions from your programming language.
(As a note, every function
provided in the API begins with "we_". The "we" stands for Winford Engineering.
This small prefix indicates that a function is part of Winford's API. Hopefully
this will reduce some confusion for programmers.) Once you have access
to the API functions, you may begin programming and using your Portal I/O cards.
The first step in using any card is to call the we_OpenCard
function, telling the API what card model you have and what base address
it is configured for. The we_OpenCard function initializes the card and
returns a new "handle" to the programmer. A handle is a number generated
by the API (in this case by the we_OpenCard function) to identify the newly
opened card. The programmer must have the handle to call other API functions
which perform an operation on the card. A valid handle tells the other
API functions what card model and base address the programmer is using.
If there is a conflict or error while opening or initializing the card,
the we_OpenCard function returns an error code instead of a valid handle.
After the card has been successfully opened, you may use the handle as
a parameter to most of the other API functions.
Most I/O cards can be configured
in different ways. For example, the CRD155B has 3 ports that can be individually
configured as inputs or outputs. In order to configure your card after opening it,
you may call the we_ConfigureCard function.
In addition to the handle, you must tell the function which port you want
to configure and what mode you want that port to be set up for.
Now all that you must do to actually use the
card is to call the we_OutputValue or
we_InputValue
functions, which write a value out to the port, or read in a value, respectively.
You must tell these functions which port you want to write to or read from.
If a port is currently configured for input, we_OutputValue
will return an error code, and the value will not be written to the port.
Similarly, if a port is configured for output, we_InputValue will
return an error code.
When a port is configured
for output, the last value written to an output port can be read back using
the we_ReadBack function. It is never necessary
to use this function. However, if you need to know the current state of an output
port, this function may be useful.
When you are done using the card, you should
call the we_CloseCard function. This causes
the Portal API to release any information it has stored about the card,
and indicates that the card is available for use. If the card has not been closed using
we_CloseCard any following attempt to reopen the card using we_OpenCard
within the same application instance will fail due to conflict.
(Note that when your application terminates, the
API is unloaded causing all cards to be closed.) There is an additional
function provided for convenience called we_CloseAllCards.
This function causes any cards that the Portal API has opened to be closed. This
allows the cards to then be reopened using we_OpenCard.
Copyright 2004 Winford Engineering.