haiku.git

/*
 * Copyright (c) 2008 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the the MIT licence.
 *
 */

//! The BMediaRoster is the main API to the Media Kit.

#ifndef _MEDIA_ROSTER_H
#define _MEDIA_ROSTER_H

#include <MediaDefs.h>
#include <MediaNode.h>


typedef enum {
	B_ISA_BUS,
	B_PCI_BUS,
	B_PCMCIA_BUS,
	B_UNKNOWN_BUS = 0x80
} bus_type;


class BBufferGroup;
class BMediaAddOn;
class BMimeType;
class BParameterWeb;
class BString;

struct dormant_flavor_info;
struct entry_ref;

namespace BPrivate { namespace media {
	class DefaultDeleter;
	class BMediaRosterEx;
} } // BPrivate::media


class BMediaRoster : public BLooper {
public:

	// Retrieving the global instance of the BMediaRoster:
	static	BMediaRoster*		Roster(status_t* _error = NULL);
				// This version will create a roster instance if there isn't
				// one already. Thread safe for multiple calls to Roster().

	static	BMediaRoster*		CurrentRoster();
				// This version won't create an instance if there isn't one
				// already. It is not thread safe if you call Roster() at the
				// same time.

	// Check if the media services are running.
	static	bool				IsRunning();

	// Getting common instances of system nodes:
			status_t			GetVideoInput(media_node* _node);
			status_t			GetAudioInput(media_node* _node);
			status_t			GetVideoOutput(media_node* _node);
			status_t			GetAudioMixer(media_node* _node);
			status_t			GetAudioOutput(media_node* _node);
				// The output should not be used directly in common use cases.
				// Use the mixer node instead.
			status_t			GetAudioOutput(media_node* _node,
									int32* _inputId, BString* _inputName);
			status_t			GetTimeSource(media_node* _node);

	// Setting common system nodes:
			status_t			SetVideoInput(const media_node& producer);
			status_t			SetVideoInput(
									const dormant_node_info& producer);

			status_t			SetAudioInput(const media_node& producer);
			status_t			SetAudioInput(
									const dormant_node_info& producer);

			status_t			SetVideoOutput(const media_node& consumer);
			status_t			SetVideoOutput(
									const dormant_node_info& consumer);

			status_t			SetAudioOutput(
									const media_node& consumer);
			status_t			SetAudioOutput(
									const media_input& inputToOutput);
			status_t			SetAudioOutput(
									const dormant_node_info& consumer);

	// Get a media_node from a node ID -- this is how you reference your
	// own nodes!
			status_t			GetNodeFor(media_node_id node,
									media_node* clone);
			status_t			GetSystemTimeSource(media_node* clone);
				// Typically, you'll want to use GetTimeSource() instead.
			status_t			ReleaseNode(const media_node& node);
				// This method might free the node if there are no
				// more references.
			BTimeSource*		MakeTimeSourceFor(const media_node& for_node);
				// Release() the returned object when done!

			status_t			Connect(const media_source& from,
									const media_destination& to,
									media_format* _inOutFormat,
									media_output* _output,
									media_input* _input);
				// Note that the media_source and media_destination found in
				// _output and _input are the ones actually used. From and to
				// are only "hints" that the app should not use once a real
				// connection has been established.

			enum connect_flags {
				B_CONNECT_MUTED = 0x1
			};
		
			status_t			Connect(const media_source& from,
									const media_destination& to,
									media_format* _inOutFormat,
									media_output* _output,
									media_input* _input,
									uint32 flags, void* _reserved = NULL);
				
			status_t			Disconnect(media_node_id sourceNode,
									const media_source& source,
									media_node_id destinationNode,
									const media_destination& destination);

		
			status_t			Disconnect(const media_output& output,
									const media_input& input);
				// NOTE: This is a Haiku extension.

			status_t			StartNode(const media_node& node,
									bigtime_t atPerformanceTime);
			status_t			StopNode(const media_node& node,
									bigtime_t atPerformanceTime,
									bool immediate = false);
				// If "immediate" is true, "atPerformanceTime" is ignored.
			status_t			SeekNode(const media_node& node,
									bigtime_t toMediaTime,
									bigtime_t atPerformanceTime = 0);
				// NOTE: The node needs to be running.

			status_t			StartTimeSource(const media_node& node,
									bigtime_t atRealTime);
			status_t			StopTimeSource(const media_node& node,
									bigtime_t atRealTime,
									bool immediate = false);
			status_t			SeekTimeSource(const media_node& node,
									bigtime_t toPerformanceTime,
									bigtime_t atRealTime);

			status_t			SyncToNode(const media_node& node,
									bigtime_t atTime,
									bigtime_t timeout = B_INFINITE_TIMEOUT);
			status_t			SetRunModeNode(const media_node& node,
									BMediaNode::run_mode mode);
			status_t			PrerollNode(const media_node& node);
				// NOTE: This method is synchronous.
			status_t			RollNode(const media_node& node, 
									bigtime_t startPerformance,
									bigtime_t stopPerformance,
									bigtime_t atMediaTime
										= -B_INFINITE_TIMEOUT);

			status_t			SetProducerRunModeDelay(const media_node& node,
									bigtime_t delay,
									BMediaNode::run_mode mode
										= BMediaNode::B_RECORDING);
				// NOTE: Should only be used with B_RECORDING
			status_t			SetProducerRate(const media_node& producer,
									int32 numer, int32 denom);
				// NOTE: This feature is not necessarily supported by the node.

	// Retrieving information about available inputs/outputs.
	// Nodes will have available inputs/outputs as long as they are capable
	// of accepting more connections. The node may create an additional
	// output or input as the currently available is taken into usage.
			status_t			GetLiveNodeInfo(const media_node& node,
									live_node_info* _liveInfo);
			status_t			GetLiveNodes(live_node_info* _liveNodes,
									int32* inOutTotalCount,
									const media_format* hasInput = NULL,
									const media_format* hasOutput = NULL,
									const char* name = NULL,
									uint64 nodeKinds = 0);
										// B_BUFFER_PRODUCER etc.

			status_t			GetFreeInputsFor(const media_node& node,
									media_input* _freeInputsBuffer,
									int32 bufferCapacity,
									int32* _foundCount,
									media_type filterType
										= B_MEDIA_UNKNOWN_TYPE);
			status_t			GetConnectedInputsFor(const media_node& node,
									media_input* _activeInputsBuffer,
									int32 bufferCapacity,
									int32* _foundCount);
			status_t			GetAllInputsFor(const media_node& node,
									media_input* _inputsBuffer,
									int32 bufferCapacity,
									int32* _foundCount);
			status_t			GetFreeOutputsFor(const media_node& node,
									media_output* _freeOutputsBuffer,
									int32 bufferCapacity,
									int32* _foundCount,
									media_type filterType
										= B_MEDIA_UNKNOWN_TYPE);
			status_t			GetConnectedOutputsFor(const media_node& node,
									media_output* _activeOutputsBuffer,
									int32 bufferCapacity,
									int32* _foundCount);
			status_t			GetAllOutputsFor(const media_node& node,
									media_output* _outputsBuffer,
									int32 bufferCapacity,
									int32* _foundCount);

	// Event notification support:
			status_t			StartWatching(const BMessenger& target);
			status_t			StartWatching(const BMessenger& target,
									int32 notificationType);
			status_t			StartWatching(const BMessenger& target,
									const media_node& node,
									int32 notificationType);
			status_t			StopWatching(const BMessenger& target);
			status_t			StopWatching(const BMessenger& target,
									int32 notificationType);
			status_t			StopWatching(const BMessenger& target,
									const media_node& node,
									int32 notificationType);

			status_t			RegisterNode(BMediaNode* node);
			status_t			UnregisterNode(BMediaNode* node);

			status_t			SetTimeSourceFor(media_node_id node,
									media_node_id timeSource);

	// Building a control GUI for a node:
			status_t			GetParameterWebFor(const media_node& node, 
									BParameterWeb** _web);
			status_t			StartControlPanel(const media_node& node,
									BMessenger* _messenger = NULL);

	// Information about nodes which are not running, but could
	// be instantiated from add-ons:
			status_t			GetDormantNodes(dormant_node_info* _info,
									int32* _inOutCount,
									const media_format* _hasInput = NULL,
									const media_format* _hasOutput = NULL,
									const char* name = NULL,
									uint64 requireKinds = 0,
									uint64 denyKinds = 0);
			status_t			InstantiateDormantNode(
									const dormant_node_info& info,
									media_node* _node,
									uint32 flags);
				// NOTE: Supported flags are currently B_FLAVOR_IS_GLOBAL
				// or B_FLAVOR_IS_LOCAL
			status_t			InstantiateDormantNode(
									const dormant_node_info& info,
									media_node* _node);
			status_t			GetDormantNodeFor(const media_node& node,
									dormant_node_info* _info);
			status_t			GetDormantFlavorInfoFor(
									const dormant_node_info& info,
									dormant_flavor_info* _flavor);

	// Latency information:
			status_t			GetLatencyFor(const media_node& producer,
									bigtime_t* _latency);
			status_t			GetInitialLatencyFor(
									const media_node& producer,
									bigtime_t* _latency,
									uint32* _flags = NULL);
			status_t			GetStartLatencyFor(
									const media_node& timeSource,
									bigtime_t* _latency);

	// Finding a suitable node to playback a file:
			status_t			GetFileFormatsFor(
									const media_node& fileInterface, 
									media_file_format* _formatsBuffer,
									int32* _inOutNumInfos);
			status_t			SetRefFor(const media_node& fileInterface,
									const entry_ref& file,
									bool createAndTruncate,
									bigtime_t* _length);
										// if create is false
			status_t			GetRefFor(const media_node& node,
									entry_ref* _ref,
									BMimeType* mimeType = NULL);
			status_t			SniffRefFor(const media_node& fileInterface,
									const entry_ref& ref, BMimeType* _mimeType,
									float* _capability);
	// This is the generic "here's a file, now can someone please play it"
	// interface:
			status_t			SniffRef(const entry_ref& ref,
									uint64 requireNodeKinds,
										// if you need an EntityInterface
										// or BufferConsumer or something
									dormant_node_info* _node,
									BMimeType* _mimeType = NULL);
			status_t			GetDormantNodeForType(const BMimeType& type,
									uint64 requireNodeKinds,
									dormant_node_info* _info);
			status_t			GetReadFileFormatsFor(
									const dormant_node_info& node,
									media_file_format* _readFormatsBuffer,
									int32 bufferCapacity, int32* _foundCount);
			status_t			GetWriteFileFormatsFor(
									const dormant_node_info& node,
									media_file_format* _writeFormatsBuffer,
									int32 bufferCapacity, int32* _foundCount);

			status_t			GetFormatFor(const media_output& output,
									media_format* _inOutFormat,
									uint32 flags = 0);
			status_t			GetFormatFor(const media_input& input,
									media_format* _inOutFormat,
									uint32 flags = 0);
			status_t			GetFormatFor(const media_node& node,
									media_format* _inOutFormat,
									float quality = B_MEDIA_ANY_QUALITY);
			ssize_t				GetNodeAttributesFor(const media_node& node,
									media_node_attribute* outArray,
									size_t inMaxCount);
			media_node_id		NodeIDFor(port_id sourceOrDestinationPort);
			status_t			GetInstancesFor(media_addon_id addon,
									int32 flavor,media_node_id* _id,
									int32* _inOutCount = NULL);
										// _inOutCount defaults to 1
										// if unspecified (NULL).

	// Returns the preferred audio buffer size
			ssize_t				AudioBufferSizeFor(int32 channelCount,
									uint32 sampleFormat, float frameRate,
									bus_type busType = B_UNKNOWN_BUS);

	// Use MediaFlags to inquire about specific features of the Media Kit.
	// Returns < 0 for "not present", positive size for output data size.
	// 0 means that the capability is present, but no data about it.
	static	ssize_t				MediaFlags(media_flags cap, void* buffer,
									size_t maxSize);

	// BLooper overrides
	virtual	void				MessageReceived(BMessage* message);
	virtual	bool				QuitRequested();

	virtual	BHandler*			ResolveSpecifier(BMessage* message,
									int32 index, BMessage* specifier,
									int32 form, const char* property);
	virtual	status_t			GetSupportedSuites(BMessage* data);

	virtual						~BMediaRoster();

private:

	// Reserving virtual function slots.
	virtual	status_t			_Reserved_MediaRoster_0(void*);
	virtual	status_t			_Reserved_MediaRoster_1(void*);
	virtual	status_t			_Reserved_MediaRoster_2(void*);
	virtual	status_t			_Reserved_MediaRoster_3(void*);
	virtual	status_t			_Reserved_MediaRoster_4(void*);
	virtual	status_t			_Reserved_MediaRoster_5(void*);
	virtual	status_t			_Reserved_MediaRoster_6(void*);
	virtual	status_t			_Reserved_MediaRoster_7(void*);

	friend class BPrivate::media::DefaultDeleter;
	friend class BPrivate::media::BMediaRosterEx;

	// Constructor is private, since you are supposed to use
	// Roster() or CurrentRoster().
								BMediaRoster();

	// Those methods are deprecated or considered useless
	// NOTE: planned to be removed once we break the API.
			status_t			SetOutputBuffersFor(const media_source& output,
									BBufferGroup* group,
									bool willReclaim = false);

			status_t			SetRealtimeFlags(uint32 enabledFlags);
			status_t			GetRealtimeFlags(uint32* _enabledFlags);

	static	status_t			ParseCommand(BMessage& reply);

			status_t			GetDefaultInfo(media_node_id forDefault,
									BMessage& _config);
			status_t			SetRunningDefault(media_node_id forDefault,
									const media_node& node);
	// End of deprecated methods

private:
			uint32				_reserved_media_roster_[67];

	static	BMediaRoster*		sDefaultInstance;
};


#endif // _MEDIA_ROSTER_H