1/*
2 * Copyright (c) 2008 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the the MIT licence.
4 *
5 */
6
7//! The BMediaRoster is the main API to the Media Kit.
8
9#ifndef _MEDIA_ROSTER_H
10#define _MEDIA_ROSTER_H
11
12#include <MediaDefs.h>
13#include <MediaNode.h>
14
15
16typedef enum {
17	B_ISA_BUS,
18	B_PCI_BUS,
19	B_PCMCIA_BUS,
20	B_UNKNOWN_BUS = 0x80
21} bus_type;
22
23
24class BBufferGroup;
25class BMediaAddOn;
26class BMimeType;
27class BParameterWeb;
28class BString;
29
30struct dormant_flavor_info;
31struct entry_ref;
32
33namespace BPrivate { namespace media {
34	class DefaultDeleter;
35	class BMediaRosterEx;
36} } // BPrivate::media
37
38
39class BMediaRoster : public BLooper {
40public:
41
42	// Retrieving the global instance of the BMediaRoster:
43	static	BMediaRoster*		Roster(status_t* _error = NULL);
44				// This version will create a roster instance if there isn't
45				// one already. Thread safe for multiple calls to Roster().
46
47	static	BMediaRoster*		CurrentRoster();
48				// This version won't create an instance if there isn't one
49				// already. It is not thread safe if you call Roster() at the
50				// same time.
51
52	// Check if the media services are running.
53	static	bool				IsRunning();
54
55	// Getting common instances of system nodes:
56			status_t			GetVideoInput(media_node* _node);
57			status_t			GetAudioInput(media_node* _node);
58			status_t			GetVideoOutput(media_node* _node);
59			status_t			GetAudioMixer(media_node* _node);
60			status_t			GetAudioOutput(media_node* _node);
61				// The output should not be used directly in common use cases.
62				// Use the mixer node instead.
63			status_t			GetAudioOutput(media_node* _node,
64									int32* _inputId, BString* _inputName);
65			status_t			GetTimeSource(media_node* _node);
66
67	// Setting common system nodes:
68			status_t			SetVideoInput(const media_node& producer);
69			status_t			SetVideoInput(
70									const dormant_node_info& producer);
71
72			status_t			SetAudioInput(const media_node& producer);
73			status_t			SetAudioInput(
74									const dormant_node_info& producer);
75
76			status_t			SetVideoOutput(const media_node& consumer);
77			status_t			SetVideoOutput(
78									const dormant_node_info& consumer);
79
80			status_t			SetAudioOutput(
81									const media_node& consumer);
82			status_t			SetAudioOutput(
83									const media_input& inputToOutput);
84			status_t			SetAudioOutput(
85									const dormant_node_info& consumer);
86
87	// Get a media_node from a node ID -- this is how you reference your
88	// own nodes!
89			status_t			GetNodeFor(media_node_id node,
90									media_node* clone);
91			status_t			GetSystemTimeSource(media_node* clone);
92				// Typically, you'll want to use GetTimeSource() instead.
93			status_t			ReleaseNode(const media_node& node);
94				// This method might free the node if there are no
95				// more references.
96			BTimeSource*		MakeTimeSourceFor(const media_node& for_node);
97				// Release() the returned object when done!
98
99			status_t			Connect(const media_source& from,
100									const media_destination& to,
101									media_format* _inOutFormat,
102									media_output* _output,
103									media_input* _input);
104				// Note that the media_source and media_destination found in
105				// _output and _input are the ones actually used. From and to
106				// are only "hints" that the app should not use once a real
107				// connection has been established.
108
109			enum connect_flags {
110				B_CONNECT_MUTED = 0x1
111			};
112
113			status_t			Connect(const media_source& from,
114									const media_destination& to,
115									media_format* _inOutFormat,
116									media_output* _output,
117									media_input* _input,
118									uint32 flags, void* _reserved = NULL);
119
120			status_t			Disconnect(media_node_id sourceNode,
121									const media_source& source,
122									media_node_id destinationNode,
123									const media_destination& destination);
124
125
126			status_t			Disconnect(const media_output& output,
127									const media_input& input);
128				// NOTE: This is a Haiku extension.
129
130			status_t			StartNode(const media_node& node,
131									bigtime_t atPerformanceTime);
132			status_t			StopNode(const media_node& node,
133									bigtime_t atPerformanceTime,
134									bool immediate = false);
135				// If "immediate" is true, "atPerformanceTime" is ignored.
136			status_t			SeekNode(const media_node& node,
137									bigtime_t toMediaTime,
138									bigtime_t atPerformanceTime = 0);
139				// NOTE: The node needs to be running.
140
141			status_t			StartTimeSource(const media_node& node,
142									bigtime_t atRealTime);
143			status_t			StopTimeSource(const media_node& node,
144									bigtime_t atRealTime,
145									bool immediate = false);
146			status_t			SeekTimeSource(const media_node& node,
147									bigtime_t toPerformanceTime,
148									bigtime_t atRealTime);
149
150			status_t			SyncToNode(const media_node& node,
151									bigtime_t atTime,
152									bigtime_t timeout = B_INFINITE_TIMEOUT);
153			status_t			SetRunModeNode(const media_node& node,
154									BMediaNode::run_mode mode);
155			status_t			PrerollNode(const media_node& node);
156				// NOTE: This method is synchronous.
157			status_t			RollNode(const media_node& node,
158									bigtime_t startPerformance,
159									bigtime_t stopPerformance,
160									bigtime_t atMediaTime
161										= -B_INFINITE_TIMEOUT);
162
163			status_t			SetProducerRunModeDelay(const media_node& node,
164									bigtime_t delay,
165									BMediaNode::run_mode mode
166										= BMediaNode::B_RECORDING);
167				// NOTE: Should only be used with B_RECORDING
168			status_t			SetProducerRate(const media_node& producer,
169									int32 numer, int32 denom);
170				// NOTE: This feature is not necessarily supported by the node.
171
172	// Retrieving information about available inputs/outputs.
173	// Nodes will have available inputs/outputs as long as they are capable
174	// of accepting more connections. The node may create an additional
175	// output or input as the currently available is taken into usage.
176			status_t			GetLiveNodeInfo(const media_node& node,
177									live_node_info* _liveInfo);
178			status_t			GetLiveNodes(live_node_info* _liveNodes,
179									int32* inOutTotalCount,
180									const media_format* hasInput = NULL,
181									const media_format* hasOutput = NULL,
182									const char* name = NULL,
183									uint64 nodeKinds = 0);
184										// B_BUFFER_PRODUCER etc.
185
186			status_t			GetFreeInputsFor(const media_node& node,
187									media_input* _freeInputsBuffer,
188									int32 bufferCapacity,
189									int32* _foundCount,
190									media_type filterType
191										= B_MEDIA_UNKNOWN_TYPE);
192			status_t			GetConnectedInputsFor(const media_node& node,
193									media_input* _activeInputsBuffer,
194									int32 bufferCapacity,
195									int32* _foundCount);
196			status_t			GetAllInputsFor(const media_node& node,
197									media_input* _inputsBuffer,
198									int32 bufferCapacity,
199									int32* _foundCount);
200			status_t			GetFreeOutputsFor(const media_node& node,
201									media_output* _freeOutputsBuffer,
202									int32 bufferCapacity,
203									int32* _foundCount,
204									media_type filterType
205										= B_MEDIA_UNKNOWN_TYPE);
206			status_t			GetConnectedOutputsFor(const media_node& node,
207									media_output* _activeOutputsBuffer,
208									int32 bufferCapacity,
209									int32* _foundCount);
210			status_t			GetAllOutputsFor(const media_node& node,
211									media_output* _outputsBuffer,
212									int32 bufferCapacity,
213									int32* _foundCount);
214
215	// Event notification support:
216			status_t			StartWatching(const BMessenger& target);
217			status_t			StartWatching(const BMessenger& target,
218									int32 notificationType);
219			status_t			StartWatching(const BMessenger& target,
220									const media_node& node,
221									int32 notificationType);
222			status_t			StopWatching(const BMessenger& target);
223			status_t			StopWatching(const BMessenger& target,
224									int32 notificationType);
225			status_t			StopWatching(const BMessenger& target,
226									const media_node& node,
227									int32 notificationType);
228
229			status_t			RegisterNode(BMediaNode* node);
230			status_t			UnregisterNode(BMediaNode* node);
231
232			status_t			SetTimeSourceFor(media_node_id node,
233									media_node_id timeSource);
234
235	// Building a control GUI for a node:
236			status_t			GetParameterWebFor(const media_node& node,
237									BParameterWeb** _web);
238			status_t			StartControlPanel(const media_node& node,
239									BMessenger* _messenger = NULL);
240
241	// Information about nodes which are not running, but could
242	// be instantiated from add-ons:
243			status_t			GetDormantNodes(dormant_node_info* _info,
244									int32* _inOutCount,
245									const media_format* _hasInput = NULL,
246									const media_format* _hasOutput = NULL,
247									const char* name = NULL,
248									uint64 requireKinds = 0,
249									uint64 denyKinds = 0);
250			status_t			InstantiateDormantNode(
251									const dormant_node_info& info,
252									media_node* _node,
253									uint32 flags);
254				// NOTE: Supported flags are currently B_FLAVOR_IS_GLOBAL
255				// or B_FLAVOR_IS_LOCAL
256			status_t			InstantiateDormantNode(
257									const dormant_node_info& info,
258									media_node* _node);
259			status_t			GetDormantNodeFor(const media_node& node,
260									dormant_node_info* _info);
261			status_t			GetDormantFlavorInfoFor(
262									const dormant_node_info& info,
263									dormant_flavor_info* _flavor);
264
265	// Latency information:
266			status_t			GetLatencyFor(const media_node& producer,
267									bigtime_t* _latency);
268			status_t			GetInitialLatencyFor(
269									const media_node& producer,
270									bigtime_t* _latency,
271									uint32* _flags = NULL);
272			status_t			GetStartLatencyFor(
273									const media_node& timeSource,
274									bigtime_t* _latency);
275
276	// Finding a suitable node to playback a file:
277			status_t			GetFileFormatsFor(
278									const media_node& fileInterface,
279									media_file_format* _formatsBuffer,
280									int32* _inOutNumInfos);
281			status_t			SetRefFor(const media_node& fileInterface,
282									const entry_ref& file,
283									bool createAndTruncate,
284									bigtime_t* _length);
285										// if create is false
286			status_t			GetRefFor(const media_node& node,
287									entry_ref* _ref,
288									BMimeType* mimeType = NULL);
289			status_t			SniffRefFor(const media_node& fileInterface,
290									const entry_ref& ref, BMimeType* _mimeType,
291									float* _capability);
292	// This is the generic "here's a file, now can someone please play it"
293	// interface:
294			status_t			SniffRef(const entry_ref& ref,
295									uint64 requireNodeKinds,
296										// if you need an EntityInterface
297										// or BufferConsumer or something
298									dormant_node_info* _node,
299									BMimeType* _mimeType = NULL);
300			status_t			GetDormantNodeForType(const BMimeType& type,
301									uint64 requireNodeKinds,
302									dormant_node_info* _info);
303			status_t			GetReadFileFormatsFor(
304									const dormant_node_info& node,
305									media_file_format* _readFormatsBuffer,
306									int32 bufferCapacity, int32* _foundCount);
307			status_t			GetWriteFileFormatsFor(
308									const dormant_node_info& node,
309									media_file_format* _writeFormatsBuffer,
310									int32 bufferCapacity, int32* _foundCount);
311
312			status_t			GetFormatFor(const media_output& output,
313									media_format* _inOutFormat,
314									uint32 flags = 0);
315			status_t			GetFormatFor(const media_input& input,
316									media_format* _inOutFormat,
317									uint32 flags = 0);
318			status_t			GetFormatFor(const media_node& node,
319									media_format* _inOutFormat,
320									float quality = B_MEDIA_ANY_QUALITY);
321			ssize_t				GetNodeAttributesFor(const media_node& node,
322									media_node_attribute* outArray,
323									size_t inMaxCount);
324			media_node_id		NodeIDFor(port_id sourceOrDestinationPort);
325			status_t			GetInstancesFor(media_addon_id addon,
326									int32 flavor,media_node_id* _id,
327									int32* _inOutCount = NULL);
328										// _inOutCount defaults to 1
329										// if unspecified (NULL).
330
331	// Returns the preferred audio buffer size
332			ssize_t				AudioBufferSizeFor(int32 channelCount,
333									uint32 sampleFormat, float frameRate,
334									bus_type busType = B_UNKNOWN_BUS);
335
336	// Use MediaFlags to inquire about specific features of the Media Kit.
337	// Returns < 0 for "not present", positive size for output data size.
338	// 0 means that the capability is present, but no data about it.
339	static	ssize_t				MediaFlags(media_flags cap, void* buffer,
340									size_t maxSize);
341
342	// BLooper overrides
343	virtual	void				MessageReceived(BMessage* message);
344	virtual	bool				QuitRequested();
345
346	virtual	BHandler*			ResolveSpecifier(BMessage* message,
347									int32 index, BMessage* specifier,
348									int32 form, const char* property);
349	virtual	status_t			GetSupportedSuites(BMessage* data);
350
351	virtual						~BMediaRoster();
352
353private:
354
355	// Reserving virtual function slots.
356	virtual	status_t			_Reserved_MediaRoster_0(void*);
357	virtual	status_t			_Reserved_MediaRoster_1(void*);
358	virtual	status_t			_Reserved_MediaRoster_2(void*);
359	virtual	status_t			_Reserved_MediaRoster_3(void*);
360	virtual	status_t			_Reserved_MediaRoster_4(void*);
361	virtual	status_t			_Reserved_MediaRoster_5(void*);
362	virtual	status_t			_Reserved_MediaRoster_6(void*);
363	virtual	status_t			_Reserved_MediaRoster_7(void*);
364
365	friend class BPrivate::media::DefaultDeleter;
366	friend class BPrivate::media::BMediaRosterEx;
367
368	// Constructor is private, since you are supposed to use
369	// Roster() or CurrentRoster().
370								BMediaRoster();
371
372	// Those methods are deprecated or considered useless
373	// NOTE: planned to be removed once we break the API.
374			status_t			SetOutputBuffersFor(const media_source& output,
375									BBufferGroup* group,
376									bool willReclaim = false);
377
378			status_t			SetRealtimeFlags(uint32 enabledFlags);
379			status_t			GetRealtimeFlags(uint32* _enabledFlags);
380
381	static	status_t			ParseCommand(BMessage& reply);
382
383			status_t			GetDefaultInfo(media_node_id forDefault,
384									BMessage& _config);
385			status_t			SetRunningDefault(media_node_id forDefault,
386									const media_node& node);
387	// End of deprecated methods
388
389private:
390			uint32				_reserved_media_roster_[67];
391
392	static	BMediaRoster*		sDefaultInstance;
393};
394
395
396#endif // _MEDIA_ROSTER_H
397
398