cudal.h

ti-Chipcon CCxx11 USB + MCU +RF 应用开发源码实例。包括2.0usb,rf,powermodes,clockmodes底层驱动源码。有了这些实例,包括误码率测试等。对你更

/** \mainpage Chipcon USB Dongle Access Library
 *
 * The Chipcon USB Dongle Access Library (CUDAL) provides a simplified and easy-to-use C++ interface 
 * towards vendor-specific device classes (i.e. proprietary USB solutions). The library is distributed  
 * together with the CC2511 development kit, and is the PC counterpart of the CC2511 USB Library (which 
 * is used for firmware development).
 *
 * \note The CUDAL library is neither needed nor suitable for standardized device classes such as USB 
 * audio, mass storage or HID.
 *
 * \section section_license USB Driver and License Information
 * The CUDAL library is based on the USBIO driver from <a href="http://www.thesycon.de">Thesycon 
 * Systemconsulting & Software GmbH</a>. This driver is not free and requires a licence. Texas 
 * Instruments has a license that allows its customers to do the 
 * following:
 * \li Use the application examples included in the kit.
 * \li Develop own applications using CUDAL (Chipcon USB Dongle Access Library) as long as all  
 *     development and testing is done on the hardware (CC2511 USB Dongle) supplied in the development
 *     kit from Texas Instruments.
 * \li Modify or add functionality in the CUDAL library.
 *
 * The customer must purchase their own license if they wish to do any of the following:
 * \li Develop or test software on hardware that was not supplied in the development kit.
 * \li Go into production with a product that uses the driver.
 *
 * The customer may not:
 * \li Change, decompile, disassemble or in any way reverse engineer the cudal.sys and cudal98.sys files.
 *
 * Please contact Thesycon, <a href="http://www.thesycon.de">www.thesycon.com</a>, for information on the
 * USBIO driver and how to obtain a licence.
 *
 * \section section_features Features
 * This CUDAL library provides the following USB feature set:
 * \li The GET_DESCRIPTOR, GET_STATUS, SET_CONFIGURATION, GET_CONFIGURATION, SET_INTERFACE and 
 *     GET_INTERFACE standard requests
 * \li All IN or OUT vendor requests
 * \li All IN or OUT class requests
 * \li BULK and INTERRUPT pipes, with asynchronous (overlapped) and synchronous (blocking) read and 
 *     write functions.
 * 
 * The following features are not supported:
 * \li The SET_DESCRIPTOR, SET_FEATURE and CLEAR_FEATURE standard requests
 * \li Isochronous transfers
 *
 * \section section_overview Overview
 * The library is based on two C++ classes, along with some helper classes and structures:
 * \li \ref CudalDongle encapsulates a USB dongle, and gives access to standard, vendor and class 
 *     requests. The class provides a simple and safe way to enumerate and create \ref CudalDongle 
 *     objects, and includes a safety mechanism to ensure that only one dongle object is created for each
 *     physical USB dongle.
 * \li \ref CudalPipe encapsulates a USB pipe, which is bound to a specific BULK or INTERRUPT endpoint.
 *     One or more \ref CudalPipe objects can be created for each \ref CudalDongle onject. The class can
 *     be used either in asynchronous mode, where the read and write requests are simply submitted to a 
 *     queue, and the application continues. In synchronous mode, the read and write functions will block
 *     until the transfer succeeds, or a timeout or an error condition occurs.
 */
#ifndef CUDAL_H
#define CUDAL_H
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <stdio.h>
#include <string.h>
#include <usbspec.h>
#include <usbio_i.h>


#ifdef CUDAL_DYNAMIC
    #ifdef CUDAL_EXPORTS
        #define CUDAL_API __declspec(dllexport)
    #else
        #define CUDAL_API __declspec(dllimport)
    #endif
#else
    #define CUDAL_API
#endif


class CudalPipe;
class CUsbIo;
class CUsbIoPipe;
class CUsbIoBuf;


/// USBIO error codes can be found in "usbio_i.h"
typedef DWORD USBIOERR;


/// CUDAL dongle information
typedef struct {
    WORD vendorId;           ///< USB vendor ID
    WORD productId;          ///< USB product ID
    WORD productVersion;     ///< Product version number
    char pManufacturer[129]; ///< Manufacturer (USB string descriptor number 1, ANSI format)
    char pProduct[129];      ///< Product (USB string descriptor number 2, ANSI format)
    char pSerialNumber[129]; ///< Serial number (USB string descriptor number 3, ANSI format)
} CUDAL_DONGLE_INFO;




/** \brief The CudalDongle class that encapsulates a physical Chipcon USB dongle
 *
 * The class provides easy-to-use functions for enumerating and creating \ref CudalDongle objects, and 
 * for performing the most commonly used operations on endpoint 0. It can also create one or more 
 * \ref CudalPipe objects, which support BULK and INTERRUPT transfers at data rates up to 12 
 * Mbits/second.
 *
 * A built-in mutual exclusion mechanism (mutex) ensures that only one \ref CudalDongle object can exist 
 * for each physical USB dongle. In practice this means that:
 * - If multiple applications can access the USB dongles, each dongle is protected from being opened and 
 *   accessed by more than one application at any time. 
 * - If two USB dongles contain the same identification, only one will be recognized. The information 
 *   that uniquely identifies each dongle, consists of the "Manufacturer", "Product" and "Serial number" 
 *   string descriptors, indexed 1, 2 and 3, respectively. Cudal makes this information available through
 *   a structure called \ref CUDAL_DONGLE_INFO.
 *
 * For a USB dongle to be included in the device enumeration, it's VID/PID pair must be registered with a 
 * Globally Unique Identifier (GUID). This is done in the .inf file that is used when installing the
 * hardware (the USB dongle). The default GUID provided with the library is used with the application 
 * examples, and can also be used during prototype development. Use Guidgen.exe provided with Visual
 * Studio or a web-based generator to create your own GUID.
 * 
 * \section section_dongle_const_destr Construction and Destruction
 * A \ref CudalDongle object is constructed in two steps:
 * - First the application builds a table of connected USB dongles by calling the static class function
 *   \ref CudalDongle::EnumDongles(). The resulting table contains a number of valid 
 *   \ref CUDAL_DONGLE_INFO structures, which should uniquely identify all connected dongles. If two or 
 *   more dongles provide the same identification, there will be duplicates in the table, and only the
 *   first entry will be considered in the next step.
 *     \code
 *     // Note that the following example uses the default GUID provided with the library
 *     CUDAL_DONGLE_INFO pDongleInfo[MAX_DONGLE_COUNT];
 *     int dongleCount = CudalDongle::EnumDongles(pDongleInfo, MAX_DONGLE_COUNT);
 *     \endcode
 *
 * - Then the application decides which dongle it desires to connect to, and passes the corresponding 
 *   \ref CUDAL_DONGLE_INFO structure on to another static class function, 
 *   \ref CudalDongle::CreateDongle(). If the dongle object was created, a pointer to it will be 
 *   returned. If the application tries to make a duplicate object, \ref CudalDongle::CreateDongle() will 
 *   return a NULL-pointer instead.
 *     \code
 *     // Open the first available dongle
 *     CudalDongle *pDongle = NULL;
 *     for (int n = 0; n < dongleCount; n++) {
 *         pDongle = CudalDongle::CreateDongle(&pDongleInfo[n]);
 *         if (pDongle) break;
 *     }
 *     // No object was created if pDongle still is NULL :(
 *     \endcode
 *
 * Since the physical USB dongle is "locked" for as long as the \ref CudalDongle object exists, it must 
 * be destroyed properly. To do this, simply delete the object. Note that if this part is skipped, the 
 * dongle will be unavailable until the process creating the object has been terminated - even if it is 
 * physically unplugged from the computer and re-attached.
 *
 * \section section_dongle_usage Usage
 * The class supports the following operations on endpoint 0:
 * - Standard requests:
 *     - GET_STATUS (see \ref GetStatus())
 *     - GET_DESCRIPTOR (see \ref GetDeviceDescriptor(), \ref GetConfigurationDescriptor() and 
 *       \ref GetStringDescriptor())
 *     - GET_CONFIGURATION (see \ref GetConfiguration())
 *     - SET_CONFIGURATION (see \ref SetConfiguration() and \ref Unconfigure())
 *     - GET_INTERFACE (see \ref GetInterface())
 *     - SET_INTERFACE (see \ref SetInterface())
 * - Vendor requests (see \ref VendorRequestIn() and \ref VendorRequestOut())
 * - Class requests (see \ref ClassRequestIn() and \ref ClassRequestOut())
 *
 * To transfer BULK and INTERRUPT data on other endpoints, one or more \ref CudalPipe objects need to be
 * created. This is done using the \ref CreatePipe() function.
 *
 * \section section_dongle_example Example of Usage
 * The following enumerates available dongles, creates a \ref CudalDongle object, sends a vendor request, 
 * and then destroys the object.
 *
 * \code
 * ...
 * #define MAX_DONGLE_COUNT 16
 * CUDAL_DONGLE_INFO pDongleInfo[MAX_DONGLE_COUNT];
 * GUID guid = { 0xF363FDD8, 0xD316, 0x4B3A, { 0xAE, 0xF8, 0x73, 0x70, 0x81, 0x68, 0xAB, 0x1F } };
 *
 * // Enumerate all connected dongles
 * int dongleCount = CudalDongle::EnumDongles(pDongleInfo, MAX_DONGLE_COUNT, &guid);
 * 
 * // Find the correct device by looking for a specific product ID and serial number...
 * CudalDongle *pDongle = NULL;
 * for (int n = 0; n < dongleCount; n++) {
 *     if ((pDongleInfo[n].productId == 0x1234) &&
 *         (strcmp(pDongleInfo[n].pSerialNumber, "123456789") == 0)) {
 *         
 *         // ... and create the dongle object
 *         pDongle = CudalDongle::CreateDongle(&pDongleInfo[n]);
 *         break;
 *     }
 * }
 * 
 * // Perform the vendor request...
 * if (pDongle) {
 *     char pText[] = "Be quiet, Brain, or I'll stab you with a Q-tip";
 *     if (pDongle->VendorRequestOut(VR_SET_LCD_TEXT, 1, 2, sizeof(pText), NULL, pText) == USBIO_ERR_SUCCESS) {
 *         ...
 *     }
 * 
 *     // ... and delete the dongle object (we're done)
 *     delete pDongle;
 * }
 * ...
 * \endcode
 */
class CUDAL_API CudalDongle {
public:
    // Destroys the dongle object, and makes the dongle hardware availble for other applications
	virtual ~CudalDongle();

    // Enumerates available USB dongles
    static int EnumDongles(CUDAL_DONGLE_INFO *pDongleInfo, int maxCount, const GUID *pGuid = NULL);
    // Creates a dongle object
    static CudalDongle* CreateDongle(CUDAL_DONGLE_INFO *pDongleInfo, BYTE configurationIndex = 0, const GUID *pGuid = NULL);

    /// Returns a pointer to the dongle info structure
    CUDAL_DONGLE_INFO* GetDongleInfo() { return &m_dongleInfo; }
    
    // Creates a pipe object to be used for BULK/INTERRUPT IN/OUT data transfers
    CudalPipe* CreatePipe(BYTE endpointIndex, BOOL isDirectionIn);

    // Sends a vendor request with an IN data phase (from the device to the host) 
    USBIOERR VendorRequestIn(BYTE request, WORD index, WORD value, DWORD maxLength, DWORD *pActualLength, BYTE *pData, USBIO_REQUEST_RECIPIENT recepient = RecipientDevice);
    // Sends a vendor request with an OUT data phase (from the host to the device) 
    USBIOERR VendorRequestOut(BYTE request, WORD index, WORD value, DWORD length, DWORD *pActualLength, BYTE *pData, USBIO_REQUEST_RECIPIENT recepient = RecipientDevice);

    // Sends a class request with an IN data phase (from the device to the host) 
    USBIOERR ClassRequestIn(BYTE request, WORD index, WORD value, DWORD maxLength, DWORD *pActualLength, BYTE *pData, USBIO_REQUEST_RECIPIENT recepient = RecipientDevice);
    // Sends a class request with an OUT data phase (from the host to the device) 
    USBIOERR ClassRequestOut(BYTE request, WORD index, WORD value, DWORD length, DWORD *pActualLength, BYTE *pData, USBIO_REQUEST_RECIPIENT recepient = RecipientDevice);

    // Gets the device descriptor from the device