cudal.h

reference about wireless design which is helpful to everyone

    USBIOERR SetInterface(BYTE interfaceIndex, BYTE alternateSettingIndex);
    // Gets the current alternate setting of an interface 
    USBIOERR GetInterface(BYTE interfaceIndex, BYTE *pAlternateSettingIndex);

protected:
    // Protected constructor (to prevent user instantiation)
    CudalDongle(CUDAL_DONGLE_INFO *pDongleInfo, CUsbIo *pUsbIo);
    
    /// The dongle info for this object (a copy of the struct passed to CreateDongle())
    CUDAL_DONGLE_INFO m_dongleInfo;
    /// Pointer to the associated CUsbIo object
    CUsbIo *m_pUsbIo;

private:
    /// Mutex used to ensure that dongle enumeration and creation safe
    static HANDLE m_hMutexEnum;
    /// Mutex used to ensure that only one CudalDongle object can be created for each physical dongle
	HANDLE m_hMutexDongle;
    /// Tells whether or not a created dongle is already used (if so, CreateDongle() should fail)
    BOOL m_dongleUsed;
    /// GUID used by the USBIO driver to identify the 
    const GUID *m_pGuid;

    /// Is the dongle already in use? (a mutex is used to ensure exclusive access)
    BOOL IsDongleUsed() { return m_dongleUsed; }
    // Enters data into the supplied CUDAL_DONGLE_INFO struct
    static BOOL CreateDongleInfo(CUDAL_DONGLE_INFO *pDongleInfo, CUsbIo *pUsbIo);

}; // CudalDongle




/** \brief  A \ref CudalPipe helper class used for asynchronous transfers 
 *
 * The class supports transfers up to 4096 bytes.
 */
class CUDAL_API CudalAsyncInfo {
public:
    // Constructor
    CudalAsyncInfo();
    // Destroys the pipe object
    virtual ~CudalAsyncInfo();

    /// Pointer to the USBIO buffer object
    CUsbIoBuf *m_pUsbIoBuf;
    /// In read mode a pointer to the user-provided receive buffer, in write mode \c NULL.
    void *m_pData;
    /// The (maximum) number bytes to transfer
    DWORD m_length;

}; // CudalAsyncInfo




/** \brief  The \ref CudalPipe class encapsulates a BULK or INTERRUPT pipe.
 *
 * A \ref CudalPipe object supports data transfers on a single endpoint, either from the host to the 
 * device (OUT), or from the device to the host (IN). To enable for transfers in both directions, or on 
 * additional endpoints, simply create more \ref CudalPipe objects.
 *
 * \section section_pipe_const_dest Construction and Destruction
 * The pipe object is always associated with a \ref CudalDongle object. Call
 * \ref CudalDongle::CreatePipe() with the desired endpoint index and direction to create it. When the
 * \ref CudalPipe object is no longer to be used, it should be destroyed by simply deleting it. Be sure
 * to delete all pipe objects before deleting the associated dongle object.
 *
 * \section section_pipe_data_transfers Data Transfers
 * There is support for both synchronous and asynchronous transfers. In \b synchronous mode, using 
 * \ref ReadSync() or \ref WriteSync(), the read or write function waits until the operation is done or
 * the specified timeout is reached. If a transfer was started before the timeout, but did not complete,
 * there is no way to tell how far it actually got.
 * 
 * In \b asynchronous mode, the \ref ReadAsync() or \ref WriteAsync() function returns immediately, 
 * and the result is polled later on by using the \ref WaitAsync() function. If \ref WaitAsync() 
 * experiences a timeout, nothing happens, and the transfer still remains active.
 *
 * To \b abort all submitted transfers, the \ref AbortAll function must be called once, followed by a 
 * call to \ref WaitAsyncTermination() for each pending asynchronous transfer.
 *
 * \section section_pipe_examples Examples of Usage
 * The following code creates a pipe object bound to endpoint 4 IN, and reads up to 42 bytes from it, 
 * with a 300 msec timeout. It then destroys the object.
 *
 * \code
 * CudalDongle *pDongle;
 * ... Create the CudalDongle object ...
 * 
 * // Create an IN pipe on endpoint 4
 * CudalPipe *pPipe = pDongle->CreatePipe(4, TRUE);
 * if (pPipe) {
 * 
 *     // Read 42 bytes from it
 *     BYTE pData[42];
 *     DWORD length = sizeof(pData);
 *     switch (ReadSync(pData, &length, 300)) {
 *     case USBIO_ERR_SUCCESS:
 *         if (length == 42) {
 *             ... Process pData ...
 *         } else {
 *             ... Process pData ...
 *         }
 *         break;
 *     case USBIO_ERR_TIMEOUT:
 *         ... Handle timeout ...
 *         break;
 *     default:
 *         ... Handle other error ...
 *     }
 *
 *     // Destroy the pipe
 *     delete pPipe;
 * }
 * ...
 * \endcode
 *
 * The following code creates a pipe object bound to endpoint 3 IN, and repeatedly reads up to 30 bytes.
 * Each time something is received, a processing function is called. The quit flag can be set by another 
 * thread to abort the operation. Pay special attention to the clean-up procedure at the end!
 *
 * \code
 * CudalDongle *pDongle;
 * ... Create the CudalDongle object ...
 * 
 * // Create an IN pipe on endpoint 3
 * CudalPipe *pPipe = pDongle->CreatePipe(3, TRUE);
 * if (pPipe) {
 *
 *     CudalAsyncInfo asyncInfo;
 *     BYTE pBuffer[30];
 *     DWORD length;
 *
 *     // Start polling
 *     if (pPipe->ReadAsync(&asyncInfo, pBuffer, sizeof(pBuffer))) {
 *         
 *         // As long as we're not ordered to quit...
 *         while (!quitAsap) {
 * 
 *             // Did we get anything?
 *             switch (pPipe->WaitAsync(&asyncInfo, &length, 100)) 
 *             case USBIO_ERR_SUCCESS:
 *
 *                 // Process the received data
 *                 ProcessFunction(pBuffer, length);
 *
 *                 // Continue polling
 *                 if (!pPipe->ReadAsync(&asyncInfo, pBuffer, sizeof(pBuffer))) {
 *                     goto error;
 *                 }
 *                 break;
 *             case USBIO_ERR_TIMEOUT:
 *                 // A timeout does not have any effect
 *                 break;
 *             default:
 *                 // Fatal error (possibly disconnection)
 *                 goto error;
 *             }
 *         }
 *
 * error:  // Clean up if necessary
 *         pPipe->AbortAll();
 *         pPipe->WaitAsyncTermination(&asyncInfo);
 *     }
 *
 *     // Destroy the pipe
 *     delete pPipe;
 * }
 * ...
 * \endcode
 */
class CUDAL_API CudalPipe {
public:
    // Destroys the pipe object
    virtual ~CudalPipe();

    // Submits a read request on the pipe, and waits for it to complete
    USBIOERR ReadSync(void *pData, DWORD *pLength, DWORD timeout = 5000);
    // Submits a write request on the pipe, and waits for it to complete
    USBIOERR WriteSync(void *pData, DWORD *pLength, DWORD timeout = 5000);

    // Submits a read request on the pipe, and returns immediately
    BOOL ReadAsync(CudalAsyncInfo *pInfo, void *pData, DWORD maxLength);
    // Submits a write request on the pipe, and returns immediately
    BOOL WriteAsync(CudalAsyncInfo *pInfo, void *pData, DWORD length);
    // Waits for an asynchronous read/write operation to complete
    USBIOERR WaitAsync(CudalAsyncInfo *pInfo, DWORD *pActualLength, DWORD timeout = 5000);
    /// Waits for an asynchronous operation to be terminatated
    USBIOERR WaitAsyncTermination(CudalAsyncInfo *pInfo) { return WaitAsync(pInfo, NULL, INFINITE); }
    

    // Aborts all transfer on the pipe
    USBIOERR AbortAll();
    
    /// Returns the endpoint index that was passed to \ref CudalDongle::CreatePipe() when creating the pipe
    int GetEndpointIndex() { return m_endpointIndex; }
    /// Returns the data direction that was passed to \ref CudalDongle::CreatePipe() when creating the pipe
    BOOL IsDirectionIn() { return m_directionIsIn; }

protected:
	// Protected constructor (to prevent user instantiation)
	CudalPipe(CUsbIoPipe *pUsbIoPipe, BYTE endpointIndex, BOOL directionIsIn);

	/// Pointer to the associated CUsbIoPipe object
    CUsbIoPipe *m_pUsbIoPipe;
        
private:
    /// The endpoint index (consisting of the 7 LSBs of the endpoint address)
    int m_endpointIndex;
    /// Is this an IN pipe (for data transfer from the dongle to the host)?
    BOOL m_directionIsIn;

    // Let CudalDongle access private members
    friend CudalDongle;

}; // CudalPipe


#endif