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
67class NodeManager;
68class NodeGroup;
69class NodeRef;
70
71class Connection {
72
73	// rather incestuous set of classes we've got here...
74	friend class NodeRef;
75	friend class NodeManager;
76
77public:					// *** 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
86public:					// *** 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
95public:					// *** 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
138protected:				// *** 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
173private:					// *** 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__*/
220