controller.h

Go to the documentation of this file.
00001 ///
00002 /// \file       controller.h
00003 ///             High level BlackBerry API class
00004 ///
00005 
00006 /*
00007     Copyright (C) 2005-2012, Net Direct Inc. (http://www.netdirect.ca/)
00008 
00009     This program is free software; you can redistribute it and/or modify
00010     it under the terms of the GNU General Public License as published by
00011     the Free Software Foundation; either version 2 of the License, or
00012     (at your option) any later version.
00013 
00014     This program is distributed in the hope that it will be useful,
00015     but WITHOUT ANY WARRANTY; without even the implied warranty of
00016     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00017 
00018     See the GNU General Public License in the COPYING file at the
00019     root directory of this project for more details.
00020 */
00021 
00022 #ifndef __BARRY_CONTROLLER_H__
00023 #define __BARRY_CONTROLLER_H__
00024 
00025 #include "dll.h"
00026 #include "socket.h"
00027 
00028 /// Project namespace, containing all related functions and classes.
00029 /// This is the only namespace applications should be concerned with,
00030 /// for now.
00031 namespace Barry {
00032 
00033 // forward declarations
00034 class SocketRoutingQueue;
00035 class ProbeResult;
00036 
00037 class PrivateControllerData;
00038 
00039 namespace Mode {
00040         class Mode;
00041         class IpModem;
00042         class Serial;
00043         class JavaLoader;
00044         class JVMDebug;
00045         class RawChannel;
00046 }
00047 
00048 //
00049 // Controller class
00050 //
00051 /// The main interface class.  This class coordinates the communication to
00052 /// a single handheld.  This class also owns the only Usb::Device object
00053 /// the handheld.  All other classes reference this one for the low level
00054 /// device object.  This class owns the only SocketZero object as well,
00055 /// which is the object that any SocketRoutingQueue is plugged into
00056 /// if constructed that way.
00057 ///
00058 /// To use this class, use the following steps:
00059 ///
00060 ///     - Probe the USB bus for matching devices with the Probe class
00061 ///     - Create an optional SocketRoutingQueue object and create a
00062 ///             read thread for it, or use its default read thread.
00063 ///     - Pass one of the probe results into the Controller constructor
00064 ///             to connect to the USB device.  Pass the routing queue
00065 ///             to the Controller constructor here too, if needed.
00066 ///     - Create the Mode object of your choice.  See m_desktop.h
00067 ///             and m_serial.h for these mode classes.  You pass
00068 ///             your controller object into these mode constructors
00069 ///             to create the mode.
00070 ///
00071 class BXEXPORT Controller
00072 {
00073         friend class Barry::Mode::Mode;
00074         friend class Barry::Mode::IpModem;
00075         friend class Barry::Mode::Serial;
00076         friend class Barry::Mode::JavaLoader;
00077         friend class Barry::Mode::JVMDebug;
00078         friend class Barry::Mode::RawChannel;
00079 
00080 public:
00081         /// Handheld mode type
00082         enum ModeType {
00083                 Unspecified,            //< default on start up (unused)
00084                 Bypass,                 //< unsupported, unknown
00085                 Desktop,                //< desktop mode required for database
00086                                         //< operation
00087                 JavaLoader,             //< experimental
00088                 JVMDebug,               //< experimental
00089                 UsbSerData,             //< GPRS modem support over USB
00090                 UsbSerCtrl,             //< internally used behind the scenes
00091                 RawChannel              //< raw channel
00092         };
00093 
00094 private:
00095         std::auto_ptr<PrivateControllerData> m_priv;
00096 
00097 private:
00098         void SetupUsb(const ProbeResult &device);
00099 
00100 protected:
00101         uint16_t SelectMode(ModeType mode);     // returns mode socket
00102         uint16_t SelectMode(ModeType mode, const char *explicitModeName); // returns mode socket
00103         SocketHandle OpenSocket(uint16_t socket, const char *password = 0);
00104         PrivateControllerData* GetPrivate() { return m_priv.get(); }
00105 
00106 public:
00107         explicit Controller(const ProbeResult &device,
00108                 int default_timeout = USBWRAP_DEFAULT_TIMEOUT);
00109         Controller(const ProbeResult &device, SocketRoutingQueue &queue,
00110                 int default_timeout = USBWRAP_DEFAULT_TIMEOUT);
00111         ~Controller();
00112 
00113         bool HasQueue() const;
00114         SocketRoutingQueue* GetQueue(); // FIXME - not really ideal to have
00115                                         // this exposed, but oh well
00116 
00117         const ProbeResult& GetProbeResult() const;
00118 };
00119 
00120 } // namespace Barry
00121 
00122 #endif
00123