pvmi/pvmf/include/pvmf_port_interface.h - platform/external/opencore - Git at Google

 /* ------------------------------------------------------------------
  * Copyright (C) 1998-2009 PacketVideo
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  * express or implied.
  * See the License for the specific language governing permissions
  * and limitations under the License.
  * -------------------------------------------------------------------
  */
 /**
  * @file pvmf_port_interface.h
  */

 #ifndef PVMF_PORT_INTERFACE_H_INCLUDED
 #define PVMF_PORT_INTERFACE_H_INCLUDED

 #ifndef OSCL_BASE_H_INCLUDED
 #include "oscl_base.h"
 #endif
 #ifndef OSCL_SHARED_PTR_H_INCLUDED
 #include "oscl_shared_ptr.h"
 #endif
 #ifndef PVMF_RETURN_CODES_H_INCLUDED
 #include "pvmf_return_codes.h"
 #endif
 #ifndef PVMF_FORMAT_TYPE_H_INCLUDED
 #include "pvmf_format_type.h"
 #endif
 #ifndef PVMF_MEDIA_MSG_H_INCLUDED
 #include "pvmf_media_msg.h"
 #endif

 // Forward declaration
 class PVMFNodeInterface;
 class PVMFPortInterface;

 /**
  * Enumerated list of port activity. This enumerated type is used to notify the owner
  * node of port activity and events.
  */
 typedef enum
 {
     PVMF_PORT_ACTIVITY_CREATED, /**< constructed*/
     PVMF_PORT_ACTIVITY_DELETED, /**< destroyed*/
     PVMF_PORT_ACTIVITY_CONNECT, /**< Connection with another port is established */
     PVMF_PORT_ACTIVITY_DISCONNECT, /**< Connection with another port is disconnected */
     PVMF_PORT_ACTIVITY_OUTGOING_MSG, /**< Outgoing message received. The node needs to call Send
                                   *  asynchronously to send this message to receiving port. */
     PVMF_PORT_ACTIVITY_INCOMING_MSG, /**< Incoming message received. The node needs to call DequeueIncomingMsg
                                   *  asynchronously to retrieve and handle the message. */
     PVMF_PORT_ACTIVITY_OUTGOING_QUEUE_BUSY, /**< Outgoing queue becomes busy and cannot receive more outgoing messages.
                                          *  The node should suspend calling QueueOutgoingMsg until receiving
                                          *  PORT_ACTIVITY_OUTGOING_QUEUE_READY event. */
     PVMF_PORT_ACTIVITY_OUTGOING_QUEUE_READY, /**< After the outgoing queue size reaches its capacity, the port
                                           * would continue to process its outgoing queue, and when the size
                                           * decreases to below the specified threshold, the owner node would
                                           * be notified that it can resume queueing outgoing data to this port. */
     PVMF_PORT_ACTIVITY_CONNECTED_PORT_BUSY, /**< Connected port is busy and cannot receive more incoming messages. The
                                          *  node should suspend calling Send to process the outgoing messages until
                                          *  receiving PORT_ACTIVITY_CONNECTED_PORT_READY event. */
     PVMF_PORT_ACTIVITY_CONNECTED_PORT_READY, /**< Connected port is ready to receive more incoming messages. The node
                                          *  resume calling Send to process its outgoing queue. */
     PVMF_PORT_ACTIVITY_ERROR    /**< An error occurred in the port. */
 } PVMFPortActivityType;

 /** Structure containing the port activity and the port on which this activity occurred. */
 class PVMFPortActivity
 {
     public:
         PVMFPortActivity(PVMFPortInterface* aPort, PVMFPortActivityType aType) : iPort(aPort), iType(aType) {};
         PVMFPortActivity(const PVMFPortActivity& aActivity)
         {
             Copy(aActivity);
         }
         PVMFPortActivity& operator=(const PVMFPortActivity& aActivity)
         {
             Copy(aActivity);
             return (*this);
         }

         PVMFPortInterface* iPort; /**< Port on which activity occurred */
         PVMFPortActivityType iType; /**< Activity type. */

     private:
         void Copy(const PVMFPortActivity& aActivity)
         {
             iPort = aActivity.iPort;
             iType = aActivity.iType;
         }
 };

 class PVMFPortActivityHandler;
 class PvmiCapabilityAndConfig;

 /**
  * PVMF Port Interface is an input or output interface for communicating media, control,
  * and status data in or out of a graph node.  Through the port interface, media messages,
  * data, status and control may flow in both directions between two connected ports.
  */
 class PVMFPortInterface
 {
     public:
         virtual ~PVMFPortInterface() {}

         /**
          * Returns the tag of this port
          * @return Port tag
          */
         virtual int32 GetPortTag() const = 0;

         /**
          * Establish connection with another port.
          * @param aPort Port to connect with
          * @return Completion status
          */
         virtual PVMFStatus Connect(PVMFPortInterface* aPort) = 0;

         /**
          * Disconnect an established connection with another port
          * @return Completion status
          */
         virtual PVMFStatus Disconnect() = 0;

         /**
          * Queue an outgoing media message to the port.
          *
          * The outgoing message is added to the outgoing message queue, and the message
          * will be delivered to the receiving port asynchronously.
          *
          * @param aMsg Outgoing media message
          * @return Completion status. Returns PVMFFailure if the outgoing message queue is full
          */
         virtual PVMFStatus QueueOutgoingMsg(PVMFSharedMediaMsgPtr aMsg) = 0;

         /**
          * Send a queued outgoing message to the connected receiving port.
          *
          * @return Completion status. Returns PVMFFailure if the port is not connected
          * to another port, or the message is rejected by the receiving port.
          */
         virtual PVMFStatus Send() = 0;

         /**
          * Receives an incoming message.
          *
          * The incoming message is added to the incoming message queue, and the message
          * is processed by the node asynchronously.  If the incoming message queue is full,
          * this method would fail and the sending port should stop sending incoming messages
          * until it is notified by the ReadyToReceive call to resume sending messages.
          *
          * @param aMsg Incoming media message
          * @return Completion status.  Returns PVMFFailure if incoming mesasge queue is full.
          */
         virtual PVMFStatus Receive(PVMFSharedMediaMsgPtr aMsg) = 0;

         /**
          * Dequeue a message from the incoming queue and return the message.
          *
          * If the incoming message queue was full and the queue size has reduced to below
          * a reasonable level, the port should notify the sending port that it can resume
          * sending data by calling ReadyToReceive on the sending port.
          *
          * @param aMsg Outgoing parameter for the port to return the dequeued message
          * @return Completion status.
          */
         virtual PVMFStatus DequeueIncomingMsg(PVMFSharedMediaMsgPtr& aMsg) = 0;

         /**
          * Notification to sender port to resume sending outgoing message to receiving port.
          *
          * After the receiving port's incoming message queue size reached capacity, the port
          * would reject all incoming messages while continue to process queued messages.  When
          * the incoming queue size drops below a specified threshold, the receiving port will
          * call this method on the sender port to notify the sender that it can resume sending
          * incoming messages to the receiving port.
          *
          * @return Completion status.
          */
         virtual PVMFStatus ReadyToReceive() = 0;

         /**
          * Clear both incoming and outgoing queues.
          *
          * The queues messages in both queues will be discarded and not processed. The node will
          * need to clean its port activities queue such that it will not continue processing
          * queued port activities.
          *
          * @return Completion status.
          */
         virtual PVMFStatus ClearMsgQueues() = 0;

         /**
          * Query size of incoming message queue.
          * @return Size of incoming message queue.
          */
         virtual uint32 IncomingMsgQueueSize() = 0;

         /**
          * Query size of outgoing message queue.
          * @return Size of outgoing message queue.
          */
         virtual uint32 OutgoingMsgQueueSize() = 0;

         /**
          * Query whether the outgoing queue can accept more outgoing messages.
          * @return true if outgoing queue is busy, else false.
          */
         virtual bool IsOutgoingQueueBusy() = 0;

         /**
          * Query whether the connected port can receive more incoming messages.
          * @return true if connected port is busy, else false.
          */
         virtual bool IsConnectedPortBusy() = 0;

         /**
          * Methods to allow the node to suspend and resume
          * input queue operation.  When the input queue is
          * suspended, it will not accept data and will return
          * PVMFErrInvalidState.  Suspend & resume can be used
          * to implement the node flush operation.  Port input
          * should be suspended during a flush.
          */
         virtual void SuspendInput() = 0;
         virtual void ResumeInput() = 0;

         virtual bool IsConnected()
         {
             return iConnectedPort != NULL;
         }

         virtual void QueryInterface(const PVUuid &uuid, OsclAny* &ptr) = 0;

         /**
          * This method can be called during a Connect to set
          * the peer connection.
          */
         virtual PVMFStatus PeerConnect(PVMFPortInterface* aPort) = 0;

         /**
          * This method can be called during a Disconnect to disconnect
          * the peer connection.
          */
         virtual PVMFStatus PeerDisconnect() = 0;

     protected:
         PVMFPortInterface()
                 : iConnectedPort(NULL)
                 , iPortActivityHandler(NULL)
         {}
         PVMFPortInterface(PVMFPortActivityHandler* aNode)
                 : iConnectedPort(NULL)
                 , iPortActivityHandler(aNode)
         {}
         virtual void SetActivityHandler(PVMFPortActivityHandler* aNode)
         {
             iPortActivityHandler = aNode;
         }

         /**
         ** The port implementation uses this routine to report
         ** port activity to the activity handler (usually the
         ** node that contains the port).
         */
         virtual void PortActivity(PVMFPortActivityType aActivity) = 0;

         PVMFPortInterface* iConnectedPort;
         PVMFPortActivityHandler *iPortActivityHandler;
 };

 #endif
	/* ------------------------------------------------------------------
	* Copyright (C) 1998-2009 PacketVideo
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
	* express or implied.
	* See the License for the specific language governing permissions
	* and limitations under the License.
	* -------------------------------------------------------------------
	*/
	/**
	* @file pvmf_port_interface.h
	*/

	#ifndef PVMF_PORT_INTERFACE_H_INCLUDED
	#define PVMF_PORT_INTERFACE_H_INCLUDED

	#ifndef OSCL_BASE_H_INCLUDED
	#include "oscl_base.h"
	#endif
	#ifndef OSCL_SHARED_PTR_H_INCLUDED
	#include "oscl_shared_ptr.h"
	#endif
	#ifndef PVMF_RETURN_CODES_H_INCLUDED
	#include "pvmf_return_codes.h"
	#endif
	#ifndef PVMF_FORMAT_TYPE_H_INCLUDED
	#include "pvmf_format_type.h"
	#endif
	#ifndef PVMF_MEDIA_MSG_H_INCLUDED
	#include "pvmf_media_msg.h"
	#endif

	// Forward declaration
	class PVMFNodeInterface;
	class PVMFPortInterface;

	/**
	* Enumerated list of port activity. This enumerated type is used to notify the owner
	* node of port activity and events.
	*/
	typedef enum
	{
	PVMF_PORT_ACTIVITY_CREATED, /*< constructed/
	PVMF_PORT_ACTIVITY_DELETED, /*< destroyed/
	PVMF_PORT_ACTIVITY_CONNECT, /*< Connection with another port is established /
	PVMF_PORT_ACTIVITY_DISCONNECT, /*< Connection with another port is disconnected /
	PVMF_PORT_ACTIVITY_OUTGOING_MSG, /**< Outgoing message received. The node needs to call Send
	* asynchronously to send this message to receiving port. */
	PVMF_PORT_ACTIVITY_INCOMING_MSG, /**< Incoming message received. The node needs to call DequeueIncomingMsg
	* asynchronously to retrieve and handle the message. */
	PVMF_PORT_ACTIVITY_OUTGOING_QUEUE_BUSY, /**< Outgoing queue becomes busy and cannot receive more outgoing messages.
	* The node should suspend calling QueueOutgoingMsg until receiving
	* PORT_ACTIVITY_OUTGOING_QUEUE_READY event. */
	PVMF_PORT_ACTIVITY_OUTGOING_QUEUE_READY, /**< After the outgoing queue size reaches its capacity, the port
	* would continue to process its outgoing queue, and when the size
	* decreases to below the specified threshold, the owner node would
	* be notified that it can resume queueing outgoing data to this port. */
	PVMF_PORT_ACTIVITY_CONNECTED_PORT_BUSY, /**< Connected port is busy and cannot receive more incoming messages. The
	* node should suspend calling Send to process the outgoing messages until
	* receiving PORT_ACTIVITY_CONNECTED_PORT_READY event. */
	PVMF_PORT_ACTIVITY_CONNECTED_PORT_READY, /**< Connected port is ready to receive more incoming messages. The node
	* resume calling Send to process its outgoing queue. */
	PVMF_PORT_ACTIVITY_ERROR /*< An error occurred in the port. /
	} PVMFPortActivityType;

	/** Structure containing the port activity and the port on which this activity occurred. */
	class PVMFPortActivity
	{
	public:
	PVMFPortActivity(PVMFPortInterface* aPort, PVMFPortActivityType aType) : iPort(aPort), iType(aType) {};
	PVMFPortActivity(const PVMFPortActivity& aActivity)
	{
	Copy(aActivity);
	}
	PVMFPortActivity& operator=(const PVMFPortActivity& aActivity)
	{
	Copy(aActivity);
	return (*this);
	}

	PVMFPortInterface* iPort; /*< Port on which activity occurred /
	PVMFPortActivityType iType; /*< Activity type. /

	private:
	void Copy(const PVMFPortActivity& aActivity)
	{
	iPort = aActivity.iPort;
	iType = aActivity.iType;
	}
	};

	class PVMFPortActivityHandler;
	class PvmiCapabilityAndConfig;

	/**
	* PVMF Port Interface is an input or output interface for communicating media, control,
	* and status data in or out of a graph node. Through the port interface, media messages,
	* data, status and control may flow in both directions between two connected ports.
	*/
	class PVMFPortInterface
	{
	public:
	virtual ~PVMFPortInterface() {}

	/**
	* Returns the tag of this port
	* @return Port tag
	*/
	virtual int32 GetPortTag() const = 0;

	/**
	* Establish connection with another port.
	* @param aPort Port to connect with
	* @return Completion status
	*/
	virtual PVMFStatus Connect(PVMFPortInterface* aPort) = 0;

	/**
	* Disconnect an established connection with another port
	* @return Completion status
	*/
	virtual PVMFStatus Disconnect() = 0;

	/**
	* Queue an outgoing media message to the port.
	*
	* The outgoing message is added to the outgoing message queue, and the message
	* will be delivered to the receiving port asynchronously.
	*
	* @param aMsg Outgoing media message
	* @return Completion status. Returns PVMFFailure if the outgoing message queue is full
	*/
	virtual PVMFStatus QueueOutgoingMsg(PVMFSharedMediaMsgPtr aMsg) = 0;

	/**
	* Send a queued outgoing message to the connected receiving port.
	*
	* @return Completion status. Returns PVMFFailure if the port is not connected
	* to another port, or the message is rejected by the receiving port.
	*/
	virtual PVMFStatus Send() = 0;

	/**
	* Receives an incoming message.
	*
	* The incoming message is added to the incoming message queue, and the message
	* is processed by the node asynchronously. If the incoming message queue is full,
	* this method would fail and the sending port should stop sending incoming messages
	* until it is notified by the ReadyToReceive call to resume sending messages.
	*
	* @param aMsg Incoming media message
	* @return Completion status. Returns PVMFFailure if incoming mesasge queue is full.
	*/
	virtual PVMFStatus Receive(PVMFSharedMediaMsgPtr aMsg) = 0;

	/**
	* Dequeue a message from the incoming queue and return the message.
	*
	* If the incoming message queue was full and the queue size has reduced to below
	* a reasonable level, the port should notify the sending port that it can resume
	* sending data by calling ReadyToReceive on the sending port.
	*
	* @param aMsg Outgoing parameter for the port to return the dequeued message
	* @return Completion status.
	*/
	virtual PVMFStatus DequeueIncomingMsg(PVMFSharedMediaMsgPtr& aMsg) = 0;

	/**
	* Notification to sender port to resume sending outgoing message to receiving port.
	*
	* After the receiving port's incoming message queue size reached capacity, the port
	* would reject all incoming messages while continue to process queued messages. When
	* the incoming queue size drops below a specified threshold, the receiving port will
	* call this method on the sender port to notify the sender that it can resume sending
	* incoming messages to the receiving port.
	*
	* @return Completion status.
	*/
	virtual PVMFStatus ReadyToReceive() = 0;

	/**
	* Clear both incoming and outgoing queues.
	*
	* The queues messages in both queues will be discarded and not processed. The node will
	* need to clean its port activities queue such that it will not continue processing
	* queued port activities.
	*
	* @return Completion status.
	*/
	virtual PVMFStatus ClearMsgQueues() = 0;

	/**
	* Query size of incoming message queue.
	* @return Size of incoming message queue.
	*/
	virtual uint32 IncomingMsgQueueSize() = 0;

	/**
	* Query size of outgoing message queue.
	* @return Size of outgoing message queue.
	*/
	virtual uint32 OutgoingMsgQueueSize() = 0;

	/**
	* Query whether the outgoing queue can accept more outgoing messages.
	* @return true if outgoing queue is busy, else false.
	*/
	virtual bool IsOutgoingQueueBusy() = 0;

	/**
	* Query whether the connected port can receive more incoming messages.
	* @return true if connected port is busy, else false.
	*/
	virtual bool IsConnectedPortBusy() = 0;

	/**
	* Methods to allow the node to suspend and resume
	* input queue operation. When the input queue is
	* suspended, it will not accept data and will return
	* PVMFErrInvalidState. Suspend & resume can be used
	* to implement the node flush operation. Port input
	* should be suspended during a flush.
	*/
	virtual void SuspendInput() = 0;
	virtual void ResumeInput() = 0;

	virtual bool IsConnected()
	{
	return iConnectedPort != NULL;
	}

	virtual void QueryInterface(const PVUuid &uuid, OsclAny* &ptr) = 0;

	/**
	* This method can be called during a Connect to set
	* the peer connection.
	*/
	virtual PVMFStatus PeerConnect(PVMFPortInterface* aPort) = 0;

	/**
	* This method can be called during a Disconnect to disconnect
	* the peer connection.
	*/
	virtual PVMFStatus PeerDisconnect() = 0;

	protected:
	PVMFPortInterface()
	: iConnectedPort(NULL)
	, iPortActivityHandler(NULL)
	{}
	PVMFPortInterface(PVMFPortActivityHandler* aNode)
	: iConnectedPort(NULL)
	, iPortActivityHandler(aNode)
	{}
	virtual void SetActivityHandler(PVMFPortActivityHandler* aNode)
	{
	iPortActivityHandler = aNode;
	}

	/**
	** The port implementation uses this routine to report
	** port activity to the activity handler (usually the
	** node that contains the port).
	*/
	virtual void PortActivity(PVMFPortActivityType aActivity) = 0;

	PVMFPortInterface* iConnectedPort;
	PVMFPortActivityHandler *iPortActivityHandler;
	};

	#endif