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