cudal.h

reference about wireless design which is helpful to everyone

/** \mainpage Chipcon USB Dongle Access Library
 *
 * \author [e-mail]
 * 
 * The following features are supported:
 * \li The GET_DESCRIPTOR, GET_STATUS, SET_CONFIGURATION, GET_CONFIGURATION, SET_INTERFACE and 
 *     GET_INTERFACE standard requests
 * \li All vendor requests
 * \li All class requests
 * \li BULK and INTERRUPT pipes, with asynchronous and synchronous read and write functions
 * 
 * The following features are not supported:
 * \li The SET_DESCRIPTOR, SET_FEATURE and CLEAR_FEATURE standard requests
 * \li Isochronous transfers
 */
#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 "usbio_i.h"
typedef DWORD USBIOERR;


/// CUDAL error codes
typedef enum {
    CUDALERR_USB_COMM_FAILURE      = -1, ///< USB communication error (device malfunction or removal)
    CUDALERR_SUCCESS               = 0,  ///< Success
    CUDALERR_YES                   = 1,  ///< Success, the answer is yes
    CUDALERR_NO                    = 2,  ///< Success, the answer is no
} CUDALERR;


/// 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
    USBIOERR GetDeviceDescriptor(USB_DEVICE_DESCRIPTOR *pDesc);
    // Gets a configuration descriptor from the device
    USBIOERR GetConfigurationDescriptor(USB_CONFIGURATION_DESCRIPTOR *pDesc, DWORD maxLength, DWORD *pActualLength, BYTE index);
    // Gets a string descriptor from the device
    USBIOERR GetStringDescriptor(char *pAnsiString, DWORD maxLength, DWORD *pActualLength, BYTE index);
    // Sends a get status request to the device
    USBIOERR GetStatus(WORD *pStatusValue, USBIO_REQUEST_RECIPIENT recipient, BYTE index);

    // Sets the device to the configured state
    USBIOERR SetConfiguration(BYTE configurationIndex, BYTE *pAlternateSettingIndexes = NULL);
    // Gets the current configuration value
    USBIOERR GetConfiguration(BYTE *pConfigurationValue);
    // Sets the device to the unconfigured state
    USBIOERR Unconfigure();

    // Changes the alternate setting of an interface