User manual

Technical reference 16
Copyright 2004 Pico Technology Limited. All rights reserved.
3.3.2 New USB mode and legacy mode
3.3.2.1 usb_tc08_open_unit
short usb_tc08_open_unit (void)
This routine returns a valid handle to the USB TC-08 if the driver successfully opens it. In the case of the
routine failing, see the error code explanations in the
usb_tc08_get_last_error
section.
If you wish to use
more than one USB TC-08, this routine should be called once for each unit connected to the PC the
function will return 0 if there are no more units found. The driver is thread safe and will not allow access
to a single unit from more than one application. If, therefore,
usb_tc08_open_unit
does not find a
unit, check that other applications are not using the USB TC-08. This includes applications on other
user accounts on the same computer, where fast user switching is supported.
Note: The
usb_tc08_open_unit
function provides a simple way to open USB TC-08 units.
However, the function call locks up the calling thread until the attached USB TC-08 unit has been fully
enumerated. If a single threaded application needs to perform concurrent processing, such as
displaying a progress bar,
usb_tc08_open_unit_async
should be used.
Arguments:
None
Returns:
Positive short
- The handle to a unit.
0
- No more units were found.
-1
- Unit failed to open. Call
usb_tc08_get_last_error
with a handle of 0 to obtain
the error code.
Example
The following code is a fragment of a C application which demonstrates how to open multiple units with
the USB TC-08 driver. The handles to the open units are stored in an array for later use:
//======================================================
// Opening multiple units
//======================================================
for
(i =
0
; (new_handle =
usb_tc08_open_unit
()) >
0
; i++)
{
// store the handle in an array
handle_array[i] = new_handle;
}
no_of_units = i;
// deal with the error if there is one,
// if new_handle was zero, then there was no error
// and we reached the last available unit
if
(new_handle == -
1
)
{
error_code =
usb_tc08_get_last_error
(
0
);
printf(
"Unit failed to open\nThe error code is %d"
, error_code);