Description

Brief Description

After the execution of this function, no internal handle inside of USBDeviceList is open.

These handles are internally managed by CyAPI.lib and there is no need to expose them to the user.

The TE_USB_FX2_Close() function takes an already initialized USB device list (USBDeviceList) and closes the handle to the Trenz Electronic device driver, if one is open. This function closes all internal handles of USBDeviceList.

Warning about derived variables

If TE_USB_FX2_Close() is called, then dynamically allocated members of the CCyUSBDevice class are de-allocated. And, all "shortcut" pointers to elements of the EndPoints array (ControlEndPt, IsocIn/OutEndPt, BulkIn/OutEndPt, InterruptIn/OutEndPt) are reset to NULL.
This function does not differ much from from its homonym of the previous TE0300DLL.dll; the only difference is that this function closes a handle (like TE0300DLL.dll) to the driver but the handle is not exposed to user because it is not exposed by USBDeviceList (unlike TE0300DLL.dll).

In the code, it is possible to call TE_USB_FX2_Open() where TE0300_Open() is used.

In the code, it is possible to call TE_USB_FX2_Close() where TE0300_Close() is used, but

  • it is rare that you would ever need to call TE_USB_FX2_Close() explicitly (though doing so would not cause any problems). 
  • TE_USB_FX2_Open() realize automatically much of the TE_USB_FX2_Close() work.

Other internal handles (inside USBDeviceList) are automatically closed by TE_USB_FX2_Open() function when another handle to the device driver is already open (i.e. a TE_USB_FX2_Open() has been successfully used before). It is a behavior inherithed by CyAPI.dll Open() function.

Description of internal procedure

This function takes an already initialized USB device list, searches for Trenz Electronic USB FX2 devices (any Cypress driver derivative and VID = 0xbd0, PID=0x0300) and opens (and immediately after closes) the first device found.
The selected module is not directly given by USBDeviceList (CCyUSBDevice type). An internal operation that opens and immediately after closes an handle to CyUSB.sys driver (or a derivative like TE_USB_FX2_xx.sys) is executed instead (see page 45 of CyAPI.pdf). The open method closes every other handle already opened, and close method closes the only handle open; in this way, all handles are closed. These handles are internally managed by CyAPI.lib and there is no need to expose them to the user.

Difference with C# TE_USB_FX2_Close() function

Managed C# TE_USB_FX2_Close() of TE_USB_FX2_CyUSB.dll disposes USBdevList.

Unmanaged C++ TE_USB_FX2_Close()
of TE_USB_FX2_CyAPI.dll

It can be freely called but it is rare that you would ever need to call TE_USB_FX2_Close() explicitly (though doing so would not cause any problems).

Managed C# TE_USB_FX2_Close()
of TE_USB_FX2_CyUSB.dll

It cannot be freely called and it is rare that you would ever need to call TE_USB_FX2_Close() explicitly. Furthermore, if it is used in the wrong way, the program can raise exceptions.

Use of the code

Declaration

TE_USB_FX2_CYAPI int TE_USB_FX2_Close(CCyUSBDevice *USBDeviceList)

Function Call

Your application program shall call this function like this:

TE_USB_FX2_Close(USBDeviceList);

Parameters

CCyUSBDevice *USBDeviceList

CCyUSBDevice is a type defined in CyAPI.lib. Its name is misleading because it is not a class that represents a single USB device, but it rather represents a list of USB devices. CCyUSBDevice is the list of devices served by the CyUSB.sys driver (or a derivative like TE_USB_FX2_xx.sys). This parameter is passed by pointer. See page 7 and pages 23-49 of CyAPI.pdf (Cypress CyAPI Programmer's Reference).

Return Value

int : integer type

This function returns true (ST_OK=0) if it is able to find the module selected by CardNumber. If unable to do so, it returns false (ST_ERROR=1).

enum ST_Status
{
     ST_OK = 0,
     ST_ERROR = 1
};
  • No labels