Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members

l1394_session.h

Go to the documentation of this file.
00001 /***************************************************************************
00002                           l1394_session.h  -  description
00003                              -------------------
00004     begin                : Thu Jul 6 2000
00005     copyright            : (C) 2000-2004 by Michael Repplinger
00006     email                : repplix@studcs.uni-sb.de
00007  ***************************************************************************/
00008 
00009 /***************************************************************************
00010  *                                                                         *
00011  *   This program is free software; you can redistribute it and/or modify  *
00012  *   it under the terms of the GNU General Public License as published by  *
00013  *   the Free Software Foundation; either version 2 of the License, or     *
00014  *   (at your option) any later version.                                   *
00015  *                                                                         *
00016  ***************************************************************************/
00017 
00018 #ifndef L1394SESSION_H
00019 #define L1394SESSION_H
00020 
00021 #include <list>
00022 #include <vector>
00023 #include <string>
00024 #include <iostream>
00025 
00026 #include "Thread.hpp"
00027 
00028 #include "l1394_vcr.h"
00029 #include "l1394_camera.h"
00030 #include "l1394_card.h"
00031 #include "l1394_csrrom.h"
00032 #include "l1394_resource.h"
00033 #include "l1394_dcccamera.h"
00034 #include "l1394_fcpnode.h"
00035 #include "l1394_nodefactory.h"
00036 #include "l1394_eventhandle.h"
00037 #include "l1394_message.h"
00038 #include "Singleton.hpp"
00039 
00040 
00041 /*! \mainpage L1394 API documentation
00042   * \section about About L1394
00043   * L1394 is a high-level object oriented library to controll and access devices connected
00044   * to a FireWire (aka IEEE-1394) bus under Linux. Main goal of this library is to hide
00045   * the generic interfaces of the libraw1394 library and to provide simple and uniform
00046   * interfaces to access and control the different devices. <BR>
00047   * The following features are realized:<BR>
00048   *    - Automatic devices detection : Connected nodes on the bus are detected automaically
00049   *      and corresponding objects are created to access and control the device.
00050   *    - Automatic bus rest handling : After a bus reset the internal states of the software
00051   *      objects are updated automatically.
00052   *    - Easy event handling : This library provides an easy to used event handling mechanism
00053   *      to inform the application developer about changes on the FireWire bus via eventlistener.
00054   *      So the application developer can be informed about new devices or that currently used
00055   *      devices are no longer available. 
00056   *    - Well defined interfaces : Every device has a well defined interface for simple control.
00057   *      In the current version, this library provides unifrom interfaces for Cameras(A/VC and DCC)
00058   *      and Vcrs.
00059   *    - Simple control mechanism : To control a device this library provides two objects. The first one access the
00060   *      feature and the second one defines how to execute a feature.
00061   *    - Simple access to available devices : The Session object provides functions to access the different devices easily.
00062   *
00063   *
00064   * See <A HREF="../L1394_about.html"> L1394 Homepage</A> for more information.
00065   *  <BR> <BR>
00066   *  <HR WIDTH="100%">
00067   *  \section short_intro Short introduction
00068   *
00069   *  The most important object for the application developer is the L1394::Session object.
00070   *  The Session object is responsible to initialize this library and provides an interface
00071   *  to access the different devices as well as automatic memeory management.<BR>
00072   *  Every program using this library needs a single Session object, that can be created
00073   *  using the the static member function SSession::getSession().
00074   *  <BR>
00075   *  The following program shows a little example how to use this library. See
00076   *  <A HREF="../L1394_tutorial.html">here </A> for a step by step introduction
00077   *  \code
00078   *  #include <l1394_session.h>
00079   *
00080   *  using namespace L1394;
00081   *  int main(int argc, char*argv[])
00082   *  {
00083   *    //Start a new Session
00084   *    Session* session = SSession::getSession();
00085   *
00086   *    //Search a camera
00087   *    Camera* camera = session->findCamera();
00088   *
00089   *   if (camera == 0) {
00090   *      cout << "No Camera available" << endl;
00091   *     return 0;
00092   *   }
00093   *
00094   *    //Now you can use the camera.
00095   *    //Test if the camera support zooming.
00096   *    if(camera->zoom()->hasFeature())
00097   *      //If true set zoom value to the minimum.
00098   *      camera->zoom()->setValue(
00099   *          camera->zoom()->getMinValue() )
00100   *    else
00101   *      cout << "Zoom is not supported" << endl;
00102   *
00103   *    //Before you quit the application, delete the Session
00104   *    delete session;
00105   *  }
00106   *
00107   *  \endcode
00108   */
00109 
00110 /*! \defgroup L1394_Node
00111   *  \brief All classes representing a FireWire node are member of this group.
00112   *
00113   *  Every node connected to the FireWire bus is represented as a software object.
00114   *  These software objects are called L1394 nodes. Base class for the different L1394 nodes is
00115   *  the class L1394::Node.
00116   *  For information about the different L1394 nodes see the corresponding class documentation.
00117   */
00118 
00119 /*! \defgroup L1394_Device
00120   * \brief All classes representing interfaces for the different devices are member of this group.
00121   *
00122   *  This library provides a well defined interface for all supported devices. Each interface provides
00123   *  functions to access the different features.
00124   *  For more information about device specific interfaces see the corresponding class documentation.
00125   */
00126 
00127 /*! \defgroup L1394_Register
00128   * \brief All classes representing a L1394 Register are member of this group.
00129   *
00130   *  If you call a method to execute a feature of a Device a so called L1394 Register object
00131   *  is returned. The L1394 Register object provides an interface how to execute a command.
00132   * So you can specify how to execute the actual feature. For information about the different
00133   * L1394 Register see the corresponding class documentation.
00134   */
00135 
00136 /*! \defgroup L1394_Event
00137   * \brief All classes for events and event handling are member of this group.
00138   *
00139   *  In the actual version of this library, only the classes EventHandle and internal::Event are implemented.
00140   */
00141 
00142 
00143 /*! \defgroup L1394_Extensions
00144   * \brief Member of this group define so called L1394 Modules.
00145   *
00146   *  A L1394 module is not part of the raw L1394 library and defines
00147   * extensions for this library. For more information about a L1394 module
00148   *  see the specific class documentation.
00149   */
00150 
00151 /*! \defgroup L1394_Display
00152   * \ingroup L1394_Extensions
00153   *  \brief L1394_Display module. This module can be used to display the video
00154   *  content of a device. This module is still under develop.
00155   */
00156 
00157 /*! \defgroup Internal
00158   * \brief All classes for internal use are member of this group.
00159   *
00160   *  Be careful using the CSR-specific classes. They can cause a lot of problems
00161   * with FireWire cards because The CSR-Rom of the actual FireWire driver is still buggy.
00162   */
00163 
00164 /*! \namespace L1394
00165   * \brief The base namespace for this library is L1394.
00166   *
00167   * This namespace provides all important classes, like L1394 Nodes and L1394 Devices.
00168   *
00169   */
00170 namespace L1394{
00171 /*! \class Session
00172   * \brief The Session class is the most most important class for the programmer.
00173   *
00174   * Every program using this library needs exactly one Session object.
00175   * (There is further now way to create more than one object.)
00176   *
00177   * The Session object has two major jobs. The first part is, to instantiate the Card
00178   * objects and handle incoming events from the driver, like bus-resets. The Card object
00179   * instantiate the L1394 Nodes for the connected nodes on FireWire bus.<BR>
00180   * The second one is, to represent a simple interface to find or get the L1394 Nodes for
00181   *  a FireWire node.  These functions search on all FireWire cards.<BR>
00182   * There are also some static functions to set some internal parameters, like the
00183   * output streams, or a so called 'safe-mode'. For more information about these mothods
00184   *  see the section 'Configure the Library'.
00185   *
00186   * Normally your application needs to include the l1394_session.h file, for classes
00187   * in namespace L1394.<BR>
00188   * To create a Session object you can call the static member function Session::getSession(), or the macro
00189   * GetSession();
00190   *
00191   * The session object is also responsible to delete all L1394 objects. You must not
00192   * delete any object from this class, except the Session object itself!! If you delete
00193   *  some objects, no correct work is possible!!!!
00194   *
00195   *  If the getSession() function fails, the library quit the application with an error message.
00196   *  (The library quits an application only if the getSession() function fails)
00197   *
00198   *  A little example:
00199   *  \code
00200   *  #include <l1394_session.h>
00201   *
00202   *  using namespace L1394;
00203   *
00204   *  int main(int argc, char* argv[])
00205   *  {
00206   *    //Start a new Session.
00207   *    Session *session = GetSession();
00208   *
00209   *    for (int i = 0; i< session->getCardCount(); i++)
00210   *      session->getCard(i)->printNodeList();  //prints the device list to cout
00211   *
00212   *    //Get all cameras
00213   *    list<Camera*> camera_list = session->getAllCameras();
00214   *    list<Camera*>::iterator camera_iterator = camera_list.begin();
00215   *
00216   *    // Now you can work with the cameras. For example calibrate all cameras.
00217   *    for (int i = 0; i< camera_list.size(); i++)
00218   *    {
00219   *      if ((*camera_iterator)->whiteBalance()->hasFeature())
00220   *        (*camera_iterator)->whiteBalance()->onePush();
00221   *      if ((*camera_iterator)->zoom()->hasFeature())
00222   *        (*camera_iterator)->zoom()->setValue((*camera_iterator)->zoom()->getMinValue));
00223   *      //and so on ....
00224   *    }
00225   *
00226   *    //Get all vcrs
00227   *    list<Vcr*> vcr_list = session->getAllVcrs();
00228   *    list<Vcr*>::iterator vcr_iterator = vcr_iterator.begin();
00229   *
00230   *    //Now you can work with the devices.
00231   *    for (int i = 0; i< vcr_list.size(); i++)
00232   *    {
00233   *      //start all vcrs
00234   *      (*vcr_iterator)->play()->send();
00235   *      vcr_iterator++;
00236   *    }
00237   *
00238   *  }
00239   *  \endcode
00240   *
00241   * For more information see the tutorial.
00242   *
00243   * @author Michael Repplinger
00244   */
00245 
00246 /*! \namespace internal
00247   * \brief Namespace for internal classes
00248   *
00249   * The internal namespace provides all classes and structures, for internal use. These classes
00250   * can be used to get detailed information about the FireWire bus and the connected nodes.
00251   */
00252 class Card;
00253 class FcpNode;
00254 
00255 class Session
00256 {
00257 friend class L1394::CreateUsingNew<Session>;
00258 public:
00259 
00260 /*! \name Access the FireWire bus
00261   * These functions search and return the different nodes on the FireWire bus.
00262   *  All functions search on all installed FireWire cards.
00263   */
00264 //@{
00265 /*! \fn getCardCount() const
00266  *  \brief This method returns the number of cards in your computer.
00267  *  \return int : integer with the card count.
00268  */
00269   inline int getCardCount()                              const { return card_count; }
00270 
00271   inline const std::vector<std::string>& getIsoDevices() const { return __iso_devices; }
00272 
00273 /*! \fn addEventHandle(EventHandle*)
00274   * \brief An EventHandle object added with this method reports about busresets on all cards
00275   */
00276   void addEventHandle(EventHandle*)          ;
00277 
00278 
00279 /*! \fn removeEventHandle(EventHandle*)
00280   * \brief This method removes an EventHandle
00281   */
00282   void removeEventHandle(EventHandle*)  ;
00283 
00284 
00285 /*! \fn nodeExist(u_int64_t guid) const
00286  *  \brief This method tests, if a node with a specific guid exist.
00287  *
00288  *  This method searches on all cards.
00289  *  \param guid : u_int64_t for the guid of the node.
00290  *  \return bool : true if a node exist, else false.
00291  */
00292   bool nodeExist(u_int64_t guid) const;
00293 
00294 
00295 /*! \fn getCard(unsigned int card_id) const
00296  *  \brief This method returns a pointer to the i'th card (beginning by 0).
00297  *
00298  *  \param card_id : the current card-id (value between 0..15).
00299  *  \return Card*  : pointer to the Card object, if a card with this id exist, else NULL.
00300  */
00301   const Card* getCard(unsigned int card_id)  const;
00302 
00303 
00304 /*! \fn getCardList()  const
00305   * \brief This method returns the card_array.
00306   *
00307   *  The card_array has size 16 and stores the pointer to all Card objects.
00308   * If less than 16 cards the array is filled with NULL.
00309   * \return list<const Card*> : Pointer to an array of size 16 with Card objects.
00310   */
00311   list<const Card*> getCardList()              const;
00312 
00313 
00314 /*! \fn findDevice(const string& name) const
00315   * \brief This method finds the first Camera and returns it.
00316   *
00317   * This method searches on all Card objects.
00318   * \return Device* : pointer to the first Camera found on a card, NULL if no Camera exist.
00319   */
00320   Device* findDevice(const string& name = "Device")  const;
00321 
00322 /*! \fn findDevice(u_int64_t guid)
00323   * \brief This method finds the Device with GUID guid.
00324   *
00325   * This method searches on all Card objects.
00326   * \return Device* : pointer to the device with GUID guid, NULL if no such Device exist.
00327   */
00328   Device* findDevice(u_int64_t guid);
00329 
00330 /*! \fn findCamera(u_int64_t guid)
00331   * \brief This method finds the Camera with GUID guid.
00332   *
00333   * This method searches on all Card objects.
00334   * \return Camera* : pointer to the Camera with GUID guid, NULL if no such Camera exist.
00335   */
00336   Camera* findCamera(u_int64_t guid);
00337 
00338 /*! \fn findVcr(u_int64_t guid)
00339   * \brief This method finds the Device with GUID guid.
00340   *
00341   * This method searches on all Card objects.
00342   * \return Vcr* : pointer to the Vcr with GUID guid, NULL if no such Device exist.
00343   */
00344   Vcr* findVcr(u_int64_t guid);
00345 
00346 
00347 /*! \fn findCamera(const string& name) const
00348   * \brief This method finds the first Camera and returns it.
00349   *
00350   * This method searches on all Card objects.
00351   * \return Camera* : pointer to the first Camera found on a card, NULL if no Camera exist.
00352   */
00353   Camera* findCamera(const string& name = "Camera")  const;
00354 
00355 
00356 /*! \fn findVcr(const string& name) const
00357   * \brief This method finds a Vcr and returns a pointer to it.
00358   * \return Vcr* : pointer to the first vcr found, NULL if no Vcr exist.
00359   */
00360   Vcr* findVcr(const string& name = "Vcr")            const;
00361 
00362 
00363 /*! \fn findAvcVcr(const string& name) const
00364   * \brief This method finds an AvcVcr and returns a pointer to it.
00365   * \return Vcr* : pointer to the first AvcVcr found, NULL if no AvcVcr exist.
00366   */
00367   AvcVcr* findAvcVcr(const string& name = "AvcVcr")   const;
00368 
00369 
00370 /*! \fn findDccCamera(const string& name) const
00371   * \brief This method finds the first DccCamera on FireWire bus and return it.
00372   * \return DccCamera* : pointer to the first DccCamera, NULL if no DccCamera exist.
00373   */
00374   DccCamera* findDccCamera(const string& name = "DccCamera")  const;
00375 
00376 
00377 /*! \fn findAvcCamera(const string& name) const
00378   * \brief This method find the first AvcCamera on the FireWire bus.
00379   * \return AvcCamera* : pointer to the first AvcCamera, NULL if no AvcCamera exist.
00380   */
00381   AvcCamera* findAvcCamera(const string& name = "AvcCamera")  const;
00382 
00383 
00384 /*! \fn getAllDevices() const
00385   * \brief This method returns a list of all Cameras on the FireWire bus.
00386   *
00387   * This method searches on all Cards
00388   * \return list<Camera*> : returns a stl-list with pointer to all Cameras.
00389   */
00390   list<Device*> getAllDevices()          const;
00391 
00392 
00393 /*! \fn getAllCameras() const
00394   * \brief This method returns a list of all Cameras on the FireWire bus.
00395   *
00396   * This method searches on all Cards
00397   * \return list<Camera*> : returns a stl-list with pointer to all Cameras.
00398   */
00399   list<Camera*> getAllCameras()          const;
00400 
00401 
00402 /*! \fn getAllVcrs() const
00403   * \brief This method returns a list with all Vcrs on the FireWire bus.
00404   * \return list<Vcr*> : return a stl-list with pointer to all Vcrs.
00405   */
00406   list<Vcr*> getAllVcrs()                const;
00407 
00408 
00409 /*! \fn getAllAvcVcrs() const
00410   * \brief This method returns a list with all AvcVcrs on the FireWire bus.
00411   * \return list<AvcVcr*> : return a stl-list with pointer to all AvcVcrs .
00412   */
00413   list<AvcVcr*> getAllAvcVcrs()          const;
00414 
00415 
00416 /*! \fn getAllDccCameras() const
00417   * \brief This method finds all DccCameras and return a list of them.
00418   * \return list<DccCamera*> :a stl-list with pointer to all DccCameras.
00419   */
00420   list<DccCamera*> getAllDccCameras()    const;
00421 
00422 
00423 /*! \fn getAllAvcCameras() const
00424   * \brief This method finds all AvcCameras and return a list of them.
00425   * \return list<AvcCamera*> :a stl-list with pointer to all AvcCameras.
00426   */
00427   list<AvcCamera*> getAllAvcCameras()    const;
00428 
00429 //@}
00430 
00431 
00432 /*! \name Configure the library
00433   * These functions set some internal parameters. This library uses three ostreams
00434   * to print messages. The debug_stream prints debug_messages, the message_stream
00435   * prints some more or less informative messages and the error_stream prints error
00436   * messages. By default all streams are set to cout. To disable the messages, set
00437   *  the stream to NULL.
00438   */
00439 
00440 //@{
00441 /*! \fn setDebugStream(std::ostream* output)
00442   * \brief This method sets the debug output.
00443   *
00444   *  \param output : pointer to the output for debug messages.
00445   */
00446   static void setDebugStream(std::ostream* o)     { internal::SMessage::getInstance()->setDebugStream(o);}
00447 
00448 /*! \fn setMessageStream(std::ostream* output)
00449   * \brief This method sets the standard output.
00450   *
00451   *  \param output : pointer to the output for debug messages.
00452   */
00453   static void setMessageStream(std::ostream* o)  { internal::SMessage::getInstance()->setMessageStream(o);}
00454 
00455 
00456 /*! \fn setErrorStream(std::ostream* output)
00457   * \brief This method sets the error output.
00458   *
00459   *  \param output : pointer to the output for debug messages.
00460   */
00461   static void setErrorStream(std::ostream* o)    { internal::SMessage::getInstance()->setErrorStream(o);}
00462 
00463 /*! \fn setWarningStream(std::ostream* output)
00464   * \brief This method sets the error output.
00465   *
00466   *  \param output : pointer to the output for debug messages.
00467   */
00468   static void setWarningStream(std::ostream* o)  { internal::SMessage::getInstance()->setWarningStream(o);}
00469 
00470 /*! \fn safeMode(bool mode , int delay)
00471  *  \brief This method enables the safe-mode for the read and write functions.
00472  *
00473  *  By enabling safe mode the read, write and lock functions are
00474  *  delayed for some msecs. If you send a lot of asynchrone commands, a bus rest
00475  *  can occur.
00476  *  \param mode : true enables safe-mode, false disables safe-mode
00477  *  \param delay : how many msecs delayed between asynchronous commands.
00478  */
00479   static void safeMode(bool mode = false, int delay = 30){internal::Transaction::setSafeMode(mode, delay);}
00480 //@}
00481 
00482 protected:
00483 /*! \name Session constructor
00484   * These functions creates the Session objects.
00485   */
00486 //@{
00487 /*! \fn getSession()
00488  *  \brief This method returns a pointer to the Session object.
00489  *
00490  *  If no session object exist, it is created.
00491  *  \return Session* : pointer to the Session object.
00492  */
00493   static Session* getSession();
00494 
00495 
00496 /*! \fn Session()
00497  *  \brief Init a Session.
00498  */
00499   Session();
00500 
00501   virtual ~Session();
00502 //@}
00503 
00504 /*! \fn getNode(u_int64_t guid)   const
00505  *  \brief This method returns a pointer to a node specified by its guid return NULL, if node doesn't exist.
00506  *
00507  *  This method searches on all cards.
00508  *  \param guid : u_int64_t value for the guid.
00509  *  \return Node* : pointer to the Node, if a node with this guid exist, else NULL.
00510  */
00511   Node* getNode(u_int64_t guid)    const;
00512 
00513 
00514 /*! \fn findNode(int node_type) const
00515  *  \brief finds a node, specified by it's node_type.
00516  *
00517  *   A pointer to the first found node was returned, NULL if no node with this type was found.
00518  *  \param node_type : value that specify a node-type, defined in class Node.
00519  */
00520   Node* findNode(int node_type) const;
00521 
00522 
00523 /*! \fn getAllNodes(int node_type) const
00524  *  \brief returns a list with Nodes from type node_type
00525  *  \param node_type : the node type
00526  */
00527   list<Node*> getAllNodes(int node_type) const;
00528 
00529 private: //method
00530   void allocate();
00531   void deallocate();
00532   void initCard(int);
00533   void scanIsoDevices();
00534 
00535 private: //member
00536   raw1394handle_t  session_default_handle, tmp_handle;
00537   raw1394_portinfo pinf[16];
00538 
00539   int card_count;
00540 
00541   Card **card_array;
00542 
00543   std::vector<std::string> __iso_devices;
00544 
00545   static int  busResetHandler(raw1394handle_t h, unsigned int);
00546   static void *startBusReset(void*);
00547 
00548   raw1394handle_t *reset_handle_array;
00549   raw1394handle_t *default_handle_array;
00550   Thread          *thread_array;
00551   internal::Message* message;
00552 public:  
00553   static bool        session_is_running;
00554   static ThreadMutex global_mutex;
00555 };
00556 
00557 typedef  Singleton<L1394::Session, CreateUsingNew> SSession;
00558 
00559 }
00560 #endif

Generated on Wed Aug 24 00:36:41 2005 for L1394 by doxygen 1.4.2
L1394 library (NMM) grahics.cs.uni-sb.de/~repplix/l1394_home/