/* * Copyright (c) 1999-2000, Eric Moon. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions, and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions, and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * 3. The name of the author may not be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ // NodeRef.h (Cortex/NodeManager) // // * PURPOSE // Represents a NodeManager reference to a live Media Kit Node. // // * FEATURES UNDER CONSIDERATION +++++ // - lazy referencing: m_released becomes m_referenced; only reference // externally created nodes once they've been grouped or connected. // +++++ or disconnected? keep a'thinkin... // - expose dormant_node_info // // * HISTORY // e.moon 11aug99 Added kind(). // e.moon 9aug99 Moved position & cycle threads into NodeRef; // no more 'group transport thread'. // e.moon 25jun99 Begun #ifndef __NodeRef_H__ #define __NodeRef_H__ #include <MediaAddOn.h> #include <MediaNode.h> #include <String.h> #include <vector> #include "ILockable.h" #include "MultiInvoker.h" #include "ObservableHandler.h" #include "observe.h" #include "cortex_defs.h" __BEGIN_CORTEX_NAMESPACE class Connection; class NodeManager; class NodeGroup; class NodeSyncThread; class NodeRef : public ObservableHandler, protected ILockable { typedef ObservableHandler _inherited; friend class NodeManager; friend class NodeGroup; public: // *** messages enum message_t { // OUTBOUND // nodeID: int32 // target: BMessenger M_OBSERVER_ADDED =NodeRef_message_base, M_OBSERVER_REMOVED, M_RELEASED, // OUTBOUND // nodeID: int32 // groupID: int32 M_GROUP_CHANGED, // nodeID: int32 // runMode: int32 M_RUN_MODE_CHANGED, // +++++ M_INPUTS_CHANGED, //nyi M_OUTPUTS_CHANGED, //nyi // OUTBOUND // * only sent to position listeners // nodeID: int32 // when: int64 // position: int64 M_POSITION, // INBOUND // runMode: int32 // delay: int64 (bigtime_t; applies only to B_RECORDING mode) M_SET_RUN_MODE, // INBOUND M_PREROLL, // INBOUND // "cycling"; bool (OR "be:value"; int32) M_SET_CYCLING, // OUTBOUND // "cycling"; bool M_CYCLING_CHANGED }; public: // *** flags enum flag_t { // node-level transport restrictions NO_START_STOP = 1<<1, NO_SEEK = 1<<2, NO_PREROLL = 1<<3, // [e.moon 28sep99] useful for misbehaved nodes NO_STOP = 1<<4, // [e.moon 11oct99] // Disables media-roster connection (which currently // only makes use of B_MEDIA_NODE_STOPPED.) // This flag may become deprecated as the Media Kit // evolves (ie. more node-level notifications come // along.) NO_ROSTER_WATCH = 1<<5, // [e.moon 14oct99] // Disables position reporting (via BMediaRoster::SyncToNode().) // Some system-provided nodes tend to explode when SyncToNode() is // called on them (like the video-file player in BeOS R4.5.2). NO_POSITION_REPORTING = 1<<6 }; public: // *** dtor // free the node (this call will result in the eventual // deletion of the object.) // returns B_OK on success; B_NOT_ALLOWED if release() has // already been called; other error codes if the Media Roster // call fails. status_t release(); // call release() rather than deleting NodeRef objects virtual ~NodeRef(); public: // *** const accessors // [e.moon 13oct99] moved method definitions here to keep inline // in the face of a balky PPC compiler inline const media_node& node() const { return m_info.node; } inline uint32 kind() const { return m_info.node.kind; } inline const live_node_info& nodeInfo() const { return m_info; } inline const char* name() const { return m_info.name; } inline media_node_id id() const { return m_info.node.node; } public: // *** member access // turn cycle mode (looping) on or off void setCycling( bool cycle); bool isCycling() const; // is the node running? bool isRunning() const; // was the node created via NodeManager::instantiate()? bool isInternal() const; // fetch the group, or 0 if the node is ungrouped. NodeGroup* group() const; // flag access uint32 flags() const; void setFlags( uint32 flags); // [e.moon 29sep99] // access addon-hint info // - returns B_BAD_VALUE if not an add-on node created by this NodeManager status_t getDormantNodeInfo( dormant_node_info* outInfo); // [e.moon 29sep99] // access file being played // - returns B_BAD_VALUE if not an add-on node created by this NodeManager, // or if the node has no associated file status_t getFile( entry_ref* outFile); // [e.moon 8dec99] // set file to play status_t setFile( const entry_ref& file, bigtime_t* outDuration=0); //nyi // [e.moon 23oct99] // returns true if the media_node has been released (call releaseNode() to // make this happen.) bool isNodeReleased() const; // now implemented by ObservableHandler [20aug99] // // has this reference been released? // bool isReleased() const; public: // *** run-mode operations void setRunMode( uint32 runMode, bigtime_t delay=0LL); uint32 runMode() const; bigtime_t recordingDelay() const; // calculates the minimum amount of delay needed for // B_RECORDING mode // +++++ 15sep99: returns biggest_output_buffer_duration * 2 // +++++ 28sep99: adds downstream latency bigtime_t calculateRecordingModeDelay(); //nyi public: // *** connection access // connection access: vector versions status_t getInputConnections( std::vector<Connection>& ioConnections, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getOutputConnections( std::vector<Connection>& ioConnections, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; // connection access: flat array versions status_t getInputConnections( Connection* outConnections, int32 maxConnections, int32* outNumConnections, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getOutputConnections( Connection* outConnections, int32 maxConnections, int32* outNumConnections, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; // +++++ connection matching by source/destination +++++ public: // *** position reporting/listening bool positionReportsEnabled() const; void enablePositionReports(); void disablePositionReports(); // Fetch the approximate current position: // Returns the last reported position, and the // performance time at which that position was reached. If the // transport has never been started, the start position and // a performance time of 0 will be returned. If position updating // isn't currently enabled, returns B_NOT_ALLOWED. status_t getLastPosition( bigtime_t* outPosition, bigtime_t* outPerfTime) const; // Subscribe to regular position reports: // Position reporting isn't rolled into the regular observer // interface because a large number of messages are generated // (the frequency can be changed; see below.) status_t addPositionObserver( BHandler* handler); status_t removePositionObserver( BHandler* handler); // Set how often position updates will be sent: // Realistically, period should be > 10000 or so. status_t setPositionUpdatePeriod( bigtime_t period); bigtime_t positionUpdatePeriod() const; public: // *** BMediaRoster wrappers & convenience methods // release the media node // (if allowed, will trigger the release/deletion of this object) status_t releaseNode(); // calculate total (internal + downstream) latency for this node status_t totalLatency( bigtime_t* outLatency) const; // retrieve input/output matching the given destination/source. // returns B_MEDIA_BAD_[SOURCE | DESTINATION] if the destination // or source don't correspond to this node. status_t findInput( const media_destination& forDestination, media_input* outInput) const; status_t findOutput( const media_source& forSource, media_output* outOutput) const; // endpoint matching (given name and/or format as 'hints'). // If no hints are given, returns the first free endpoint, if // any exist. // returns B_ERROR if no matching endpoint is found. status_t findFreeInput( media_input* outInput, media_type type=B_MEDIA_UNKNOWN_TYPE, const char* name=0) const; status_t findFreeInput( media_input* outInput, const media_format* format, const char* name=0) const; status_t findFreeOutput( media_output* outOutput, media_type type=B_MEDIA_UNKNOWN_TYPE, const char* name=0) const; status_t findFreeOutput( media_output* outOutput, const media_format* format, const char* name=0) const; // node endpoint access: vector versions (wrappers for BMediaRoster // calls.) status_t getFreeInputs( std::vector<media_input>& ioInputs, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getConnectedInputs( std::vector<media_input>& ioInputs, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getFreeOutputs( std::vector<media_output>& ioOutputs, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getConnectedOutputs( std::vector<media_output>& ioOutputs, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; // node endpoint access: array versions (wrappers for BMediaRoster // calls.) status_t getFreeInputs( media_input* outInputs, int32 maxInputs, int32* outNumInputs, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getConnectedInputs( media_input* outInputs, int32 maxInputs, int32* outNumInputs) const; status_t getFreeOutputs( media_output* outOutputs, int32 maxOutputs, int32* outNumOutputs, media_type filterType=B_MEDIA_UNKNOWN_TYPE) const; status_t getConnectedOutputs( media_output* outOutputs, int32 maxOutputs, int32* outNumOutputs) const; public: // *** BHandler: virtual void MessageReceived( BMessage* message); public: // *** IObservable: [20aug99] virtual void observerAdded( const BMessenger& observer); virtual void observerRemoved( const BMessenger& observer); virtual void notifyRelease(); virtual void releaseComplete(); protected: // *** ILockable // Only WRITE locking is allowed! bool lock( lock_t type=WRITE, bigtime_t timeout=B_INFINITE_TIMEOUT); bool unlock( lock_t type=WRITE); bool isLocked( lock_t type=WRITE) const; protected: // *** ctor (accessible to NodeManager) // throws runtime_error NodeRef( const media_node& node, NodeManager* manager, uint32 userFlags, uint32 implFlags); protected: // *** endpoint-fixing operations (no lock required) // 'fix' (fill in node if needed) sets of inputs/outputs void _fixInputs( media_input* inputs, int32 count) const; void _fixInputs( std::vector<media_input>& inputs) const; void _fixOutputs( media_output* outputs, int32 count) const; void _fixOutputs( std::vector<media_output>& outputs) const; protected: // *** internal/NodeManager operations (LOCK REQUIRED) // call after instantiation to register info used to select and // create this add-on node void _setAddonHint( const dormant_node_info* info, const entry_ref* file=0); // call to set a new group; if 0, the node must have no // connections void _setGroup( NodeGroup* group); // *** NodeGroup API *** // 9aug99: moved from NodeGroup // [e.moon 13oct99] removed inlines for the sake of PPC sanity // initialize the given node's transport-state members // (this may be called from the transport thread or from // an API-implementation method.) status_t _initTransportState(); status_t _setTimeSource( media_node_id timeSourceID); status_t _setRunMode( const uint32 runMode, bigtime_t delay=0LL); status_t _setRunModeAuto( const uint32 runMode); // seek and preroll the given node. // *** this method should not be called from the transport thread // (since preroll operations can block for a relatively long time.) // // returns B_NOT_ALLOWED if the node is running, or if its NO_PREROLL // flag is set; otherwise, returns B_OK on success or a Media Roster // error. status_t _preroll( bigtime_t position); // seek the given node if possible // (this may be called from the transport thread or from // an API-implementation method.) status_t _seek( bigtime_t position, bigtime_t when); // seek the given (stopped) node // (this may be called from the transport thread or from // an API-implementation method.) status_t _seekStopped( bigtime_t position); // start the given node, if possible & necessary, at // the given time // (this may be called from the transport thread or from // an API-implementation method.) status_t _start( bigtime_t when); // stop the given node (which may or may not still be // a member of this group.) // (this may be called from the transport thread or from // an API-implementation method.) status_t _stop(); // roll the given node, if possible. // (this may be called from the transport thread or from // an API-implementation method.) status_t _roll( bigtime_t start, bigtime_t stop, bigtime_t position); // refresh the node's current latency; if I reference // a B_RECORDING node, update its 'producer delay'. status_t _updateLatency(); // +++++ this method may not be needed 10aug99 +++++ // Figure the earliest time at which the given node can be started. // Also calculates the position at which it should start from to // play in sync with other nodes in the group, if the transport is // running; if stopped, *outPosition will be set to the current // start position. // Pass the estimated amount of time needed to prepare the // node for playback (ie. preroll & a little fudge factor) in // startDelay. // // (this may be called from the transport thread or from // an API-implementation method.) status_t _calcStartTime( bigtime_t startDelay, bigtime_t* outTime, bigtime_t* outPosition); //nyi // *** Position reporting *** // callers: _start(), _roll(), enablePositionReports() status_t _startPositionThread(); // callers: _stop(), disablePositionReports(), dtor status_t _stopPositionThread(); // [e.moon 14oct99] handle a report status_t _handlePositionUpdate( bigtime_t perfTime, bigtime_t position); // callers: _handlePositionUpdate // (schedules a position update for the given time and position; // if the position overlaps a cycle, adjusts time & position // so that the notification is sent at the cycle point.) status_t _schedulePositionUpdate( bigtime_t when, bigtime_t position); // callers: _handlePositionUpdate, _initPositionThread() // Send a message to all position observers status_t _notifyPosition( bigtime_t when, bigtime_t position); private: // *** members // the node manager NodeManager* m_manager; // owning (parent) group; may be 0 if node is not connected. // A connected node always has a group, since groups allow transport // operations. New groups are created as necessary. NodeGroup* m_group; // the node's state live_node_info m_info; // user-definable transport behavior uint32 m_flags; // private/implementation flags enum impl_flag_t { // the node was created by NodeManager _INTERNAL = 1<<1, // the node should NOT be released when this instance is destroyed _NO_RELEASE = 1<<2, // notification of the node's instantiation has been received // [e.moon 11oct99] _CREATE_NOTIFIED = 1<<3 }; uint32 m_implFlags; // takes BMediaNode::run_mode values or 0 (wildcard: // group run mode used instead) // May not be B_OFFLINE; that must be specified at the group level. uint32 m_runMode; // only valid if m_runMode is BMediaNode::B_RECORDING bigtime_t m_recordingDelay; // Media Roster connection [e.moon 11oct99] bool m_watching; // hint information: this info is serialized with the object // to provide 'hints' towards properly finding the same add-on // node later on. If no hint is provided, the node is assumed // to be external to (not created by) the NodeManager. struct addon_hint; addon_hint* m_addonHint; // * position listening: // - moved from NodeGroup 9aug99 bool m_positionReportsEnabled; bool m_positionReportsStarted; bigtime_t m_positionUpdatePeriod; static const bigtime_t s_defaultPositionUpdatePeriod = 50000LL; ::MultiInvoker m_positionInvoker; bigtime_t m_tpLastPositionUpdate; bigtime_t m_lastPosition; // * synchronization threads // only active if position listening has been enabled NodeSyncThread* m_positionThread; // // only active if this node is cycling (looping) // CycleSyncThread* m_cycleSyncThread; // +++++ 10aug99: moved back to NodeGroup private: // *** transport state members // is this node running? bool m_running; // has the media_node (NOT this object) been released? bool m_nodeReleased; // is this node supposed to loop? bool m_cycle; // has the node been prepared to start? bool m_prerolled; // when was the node started? bigtime_t m_tpStart; // if the node has been prerolled, m_tpLastSeek will be 0 but // m_lastSeekPos will reflect the node's prerolled position bigtime_t m_tpLastSeek; bigtime_t m_lastSeekPos; // has a stop event been queued? [e.moon 11oct99] bigtime_t m_stopQueued; // last known latency for this node bigtime_t m_latency; }; __END_CORTEX_NAMESPACE #endif /*__NodeRef_H__*/
