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