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