src/apps/cortex/NodeManager/Connection.h

   1 /*
   2  * Copyright (c) 1999-2000, Eric Moon.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions, and the following disclaimer.
  11  *
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions, and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * 3. The name of the author may not be used to endorse or promote products
  17  *    derived from this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
  20  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21  * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  23  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
  27  * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31
  32 // Connection.h (Cortex)
  33 // * PURPOSE
  34 //   Represents a general connection between two media nodes.
  35 //
  36 // * NOTES 13aug99
  37 //   Connection is undergoing massive resimplification(TM).
  38 //   1) It's now intended to be stored and passed by value; synchronization
  39 //      and reference issues are no more.
  40 //   2) It now refers to the participatory nodes by ID, not pointer.  This
  41 //      makes the nodes slightly more cumbersome to look up, but makes
  42 //      Connection completely 'safe': an outdated instance doesn't contain
  43 //      any dangerous information.
  44 //
  45 // * NOTES 29jul99
  46 //   1) For completeness, a release() or disconnect() method would be nice.  Problems?
  47 //   2) How will connections between 'external' nodes be denoted?  For example,
  48 //      the audioMixer->audioOutput connection must not be broken EVER.  Other external
  49 //      connections might be manually broken, but should be left alone when the
  50 //      NodeManager quits (whereas all internal connections need to be removed by
  51 //      the dtor.)  This implies two flags: 'internal' and 'locked'...
  52 //
  53 // * HISTORY
  54 //   e.moon             25jun99         Begun
  55
  56 #ifndef __Connection_H__
  57 #define __Connection_H__
  58
  59 #include <Debug.h>
  60 #include <MediaNode.h>
  61 #include <String.h>
  62
  63 #include "cortex_defs.h"
  64
  65 __BEGIN_CORTEX_NAMESPACE
  66
  67 class NodeManager;
  68 class NodeGroup;
  69 class NodeRef;
  70
  71 class Connection {
  72
  73         // rather incestuous set of classes we've got here...
  74         friend class NodeRef;
  75         friend class NodeManager;
  76
  77 public:                                 // *** types & constants
  78         enum flag_t {
  79                 // connection should be removed automatically when the NodeManager
  80                 //   is destroyed
  81                 INTERNAL                                        = 1<<1,
  82                 // connection must never be removed
  83                 LOCKED                                          = 1<<2
  84         };
  85
  86 public:                                 // *** dtor/user-level ctors
  87         virtual ~Connection();
  88
  89         Connection();
  90         Connection(
  91                 const Connection&                                       clone); //nyi
  92         Connection& operator=(
  93                 const Connection&                                       clone); //nyi
  94
  95 public:                                 // *** accessors
  96
  97         uint32 id() const                                                                                                                               { return m_id; }
  98
  99         bool isValid() const                                                                                                            { return
 100                                                                                                                                                                                                                 m_sourceNode != media_node::null &&
 101                                                                                                                                                                                                                 m_destinationNode != media_node::null &&
 102                                                                                                                                                                                                                 !m_disconnected; }
 103
 104         // changed 13aug99
 105         media_node_id sourceNode() const                                                                { return m_sourceNode.node; }
 106         const media_source& source() const                                                      { return m_source; }
 107         const char* outputName() const                                                                  { return m_outputName.String(); }
 108
 109         // changed 13aug99
 110         media_node_id destinationNode() const                                   { return m_destinationNode.node; }
 111         const media_destination& destination() const            { return m_destination; }
 112         const char* inputName() const                                                                   { return m_inputName.String(); }
 113
 114         const media_format& format() const                                                      { return m_format; }
 115
 116         uint32 flags() const                                                                                                            { return m_flags; }
 117
 118         // input/output access [e.moon 14oct99]
 119         status_t getInput(
 120                 media_input*                                                    outInput) const;
 121
 122         status_t getOutput(
 123                 media_output*                                                   outOutput) const;
 124
 125         // hint access
 126
 127         status_t getOutputHint(
 128                 const char**                                                    outName,
 129                 media_format*                                                   outFormat) const;
 130
 131         status_t getInputHint(
 132                 const char**                                                    outName,
 133                 media_format*                                                   outFormat) const;
 134
 135         const media_format& requestedFormat() const { return m_requestedFormat; }
 136
 137
 138 protected:                              // *** general ctor accessible to subclasses &
 139                                                                         //     cortex::NodeManager
 140
 141         // id must be non-0
 142         Connection(
 143                 uint32                                                                          id,
 144                 media_node                                                              srcNode,
 145                 const media_source&                             src,
 146                 const char*                                                             outputName,
 147                 media_node                                                              destNode,
 148                 const media_destination&        dest,
 149                 const char*                                                             inputName,
 150                 const media_format&                             format,
 151                 uint32                                                                          flags);
 152
 153         // if any information about the pre-connection (free) output format
 154         // is known, call this method.  this info may be useful in
 155         // finding the output to re-establish the connection later on.
 156
 157         void setOutputHint(
 158                 const char*                                                             origName,
 159                 const media_format&                             origFormat);
 160
 161         // if any information about the pre-connection (free) input format
 162         // is known, call this method.  this info may be useful in
 163         // finding the output to re-establish the connection later on.
 164
 165         void setInputHint(
 166                 const char*                                                             origName,
 167                 const media_format&                             origFormat);
 168
 169         // [e.moon 8dec99]
 170         void setRequestedFormat(
 171                 const media_format&                             reqFormat);
 172
 173 private:                                        // *** members
 174
 175         // info that may be useful for reconstituting a particular
 176         // connection later on.
 177         struct endpoint_hint {
 178                 endpoint_hint(const char* _name, const media_format& _format) :
 179                         name(_name), format(_format) {}
 180
 181                 BString                                 name;
 182                 media_format            format;
 183         };
 184
 185         // waiting to die?
 186         bool                                                                                            m_disconnected;
 187
 188         // unique connection ID
 189         uint32                                                                                  m_id;
 190
 191         // [e.moon 14oct99] now stores media_nodes
 192
 193         // source/output info
 194         media_node                                                                      m_sourceNode;
 195         media_source                                                            m_source;
 196         BString                                                                                 m_outputName;
 197
 198         endpoint_hint*                                                  m_outputHint;
 199
 200         // dest/input info
 201         media_node                                                                      m_destinationNode;
 202         media_destination                                               m_destination;
 203         BString                                                                                 m_inputName;
 204
 205         endpoint_hint*                                                  m_inputHint;
 206
 207         // connection format
 208         media_format                                                            m_format;
 209
 210         // behaviour modification
 211         uint32                                                                                  m_flags;
 212
 213         // [e.moon 8dec99] initial requested format
 214         media_format                                                            m_requestedFormat;
 215 };
 216
 217 __END_CORTEX_NAMESPACE
 218
 219 #endif /*__Connection_H__*/