| /* ------------------------------------------------------------------ |
| * 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 |