1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 /** 19 * @file pvmf_port_interface.h 20 */ 21 22 #ifndef PVMF_PORT_INTERFACE_H_INCLUDED 23 #define PVMF_PORT_INTERFACE_H_INCLUDED 24 25 #ifndef OSCL_BASE_H_INCLUDED 26 #include "oscl_base.h" 27 #endif 28 #ifndef OSCL_SHARED_PTR_H_INCLUDED 29 #include "oscl_shared_ptr.h" 30 #endif 31 #ifndef PVMF_RETURN_CODES_H_INCLUDED 32 #include "pvmf_return_codes.h" 33 #endif 34 #ifndef PVMF_FORMAT_TYPE_H_INCLUDED 35 #include "pvmf_format_type.h" 36 #endif 37 #ifndef PVMF_MEDIA_MSG_H_INCLUDED 38 #include "pvmf_media_msg.h" 39 #endif 40 41 // Forward declaration 42 class PVMFNodeInterface; 43 class PVMFPortInterface; 44 45 /** 46 * Enumerated list of port activity. This enumerated type is used to notify the owner 47 * node of port activity and events. 48 */ 49 typedef enum 50 { 51 PVMF_PORT_ACTIVITY_CREATED, /**< constructed*/ 52 PVMF_PORT_ACTIVITY_DELETED, /**< destroyed*/ 53 PVMF_PORT_ACTIVITY_CONNECT, /**< Connection with another port is established */ 54 PVMF_PORT_ACTIVITY_DISCONNECT, /**< Connection with another port is disconnected */ 55 PVMF_PORT_ACTIVITY_OUTGOING_MSG, /**< Outgoing message received. The node needs to call Send 56 * asynchronously to send this message to receiving port. */ 57 PVMF_PORT_ACTIVITY_INCOMING_MSG, /**< Incoming message received. The node needs to call DequeueIncomingMsg 58 * asynchronously to retrieve and handle the message. */ 59 PVMF_PORT_ACTIVITY_OUTGOING_QUEUE_BUSY, /**< Outgoing queue becomes busy and cannot receive more outgoing messages. 60 * The node should suspend calling QueueOutgoingMsg until receiving 61 * PORT_ACTIVITY_OUTGOING_QUEUE_READY event. */ 62 PVMF_PORT_ACTIVITY_OUTGOING_QUEUE_READY, /**< After the outgoing queue size reaches its capacity, the port 63 * would continue to process its outgoing queue, and when the size 64 * decreases to below the specified threshold, the owner node would 65 * be notified that it can resume queueing outgoing data to this port. */ 66 PVMF_PORT_ACTIVITY_CONNECTED_PORT_BUSY, /**< Connected port is busy and cannot receive more incoming messages. The 67 * node should suspend calling Send to process the outgoing messages until 68 * receiving PORT_ACTIVITY_CONNECTED_PORT_READY event. */ 69 PVMF_PORT_ACTIVITY_CONNECTED_PORT_READY, /**< Connected port is ready to receive more incoming messages. The node 70 * resume calling Send to process its outgoing queue. */ 71 PVMF_PORT_ACTIVITY_ERROR /**< An error occurred in the port. */ 72 } PVMFPortActivityType; 73 74 /** Structure containing the port activity and the port on which this activity occurred. */ 75 class PVMFPortActivity 76 { 77 public: 78 PVMFPortActivity(PVMFPortInterface* aPort, PVMFPortActivityType aType) : iPort(aPort), iType(aType) {}; 79 PVMFPortActivity(const PVMFPortActivity& aActivity) 80 { 81 Copy(aActivity); 82 } 83 PVMFPortActivity& operator=(const PVMFPortActivity& aActivity) 84 { 85 Copy(aActivity); 86 return (*this); 87 } 88 89 PVMFPortInterface* iPort; /**< Port on which activity occurred */ 90 PVMFPortActivityType iType; /**< Activity type. */ 91 92 private: 93 void Copy(const PVMFPortActivity& aActivity) 94 { 95 iPort = aActivity.iPort; 96 iType = aActivity.iType; 97 } 98 }; 99 100 class PVMFPortActivityHandler; 101 class PvmiCapabilityAndConfig; 102 103 /** 104 * PVMF Port Interface is an input or output interface for communicating media, control, 105 * and status data in or out of a graph node. Through the port interface, media messages, 106 * data, status and control may flow in both directions between two connected ports. 107 */ 108 class PVMFPortInterface 109 { 110 public: 111 virtual ~PVMFPortInterface() {} 112 113 /** 114 * Returns the tag of this port 115 * @return Port tag 116 */ 117 virtual int32 GetPortTag() const = 0; 118 119 /** 120 * Establish connection with another port. 121 * @param aPort Port to connect with 122 * @return Completion status 123 */ 124 virtual PVMFStatus Connect(PVMFPortInterface* aPort) = 0; 125 126 /** 127 * Disconnect an established connection with another port 128 * @return Completion status 129 */ 130 virtual PVMFStatus Disconnect() = 0; 131 132 /** 133 * Queue an outgoing media message to the port. 134 * 135 * The outgoing message is added to the outgoing message queue, and the message 136 * will be delivered to the receiving port asynchronously. 137 * 138 * @param aMsg Outgoing media message 139 * @return Completion status. Returns PVMFFailure if the outgoing message queue is full 140 */ 141 virtual PVMFStatus QueueOutgoingMsg(PVMFSharedMediaMsgPtr aMsg) = 0; 142 143 /** 144 * Send a queued outgoing message to the connected receiving port. 145 * 146 * @return Completion status. Returns PVMFFailure if the port is not connected 147 * to another port, or the message is rejected by the receiving port. 148 */ 149 virtual PVMFStatus Send() = 0; 150 151 /** 152 * Receives an incoming message. 153 * 154 * The incoming message is added to the incoming message queue, and the message 155 * is processed by the node asynchronously. If the incoming message queue is full, 156 * this method would fail and the sending port should stop sending incoming messages 157 * until it is notified by the ReadyToReceive call to resume sending messages. 158 * 159 * @param aMsg Incoming media message 160 * @return Completion status. Returns PVMFFailure if incoming mesasge queue is full. 161 */ 162 virtual PVMFStatus Receive(PVMFSharedMediaMsgPtr aMsg) = 0; 163 164 /** 165 * Dequeue a message from the incoming queue and return the message. 166 * 167 * If the incoming message queue was full and the queue size has reduced to below 168 * a reasonable level, the port should notify the sending port that it can resume 169 * sending data by calling ReadyToReceive on the sending port. 170 * 171 * @param aMsg Outgoing parameter for the port to return the dequeued message 172 * @return Completion status. 173 */ 174 virtual PVMFStatus DequeueIncomingMsg(PVMFSharedMediaMsgPtr& aMsg) = 0; 175 176 /** 177 * Notification to sender port to resume sending outgoing message to receiving port. 178 * 179 * After the receiving port's incoming message queue size reached capacity, the port 180 * would reject all incoming messages while continue to process queued messages. When 181 * the incoming queue size drops below a specified threshold, the receiving port will 182 * call this method on the sender port to notify the sender that it can resume sending 183 * incoming messages to the receiving port. 184 * 185 * @return Completion status. 186 */ 187 virtual PVMFStatus ReadyToReceive() = 0; 188 189 /** 190 * Clear both incoming and outgoing queues. 191 * 192 * The queues messages in both queues will be discarded and not processed. The node will 193 * need to clean its port activities queue such that it will not continue processing 194 * queued port activities. 195 * 196 * @return Completion status. 197 */ 198 virtual PVMFStatus ClearMsgQueues() = 0; 199 200 /** 201 * Query size of incoming message queue. 202 * @return Size of incoming message queue. 203 */ 204 virtual uint32 IncomingMsgQueueSize() = 0; 205 206 /** 207 * Query size of outgoing message queue. 208 * @return Size of outgoing message queue. 209 */ 210 virtual uint32 OutgoingMsgQueueSize() = 0; 211 212 /** 213 * Query whether the outgoing queue can accept more outgoing messages. 214 * @return true if outgoing queue is busy, else false. 215 */ 216 virtual bool IsOutgoingQueueBusy() = 0; 217 218 /** 219 * Query whether the connected port can receive more incoming messages. 220 * @return true if connected port is busy, else false. 221 */ 222 virtual bool IsConnectedPortBusy() = 0; 223 224 /** 225 * Methods to allow the node to suspend and resume 226 * input queue operation. When the input queue is 227 * suspended, it will not accept data and will return 228 * PVMFErrInvalidState. Suspend & resume can be used 229 * to implement the node flush operation. Port input 230 * should be suspended during a flush. 231 */ 232 virtual void SuspendInput() = 0; 233 virtual void ResumeInput() = 0; 234 235 virtual bool IsConnected() 236 { 237 return iConnectedPort != NULL; 238 } 239 240 virtual void QueryInterface(const PVUuid &uuid, OsclAny* &ptr) = 0; 241 242 /** 243 * This method can be called during a Connect to set 244 * the peer connection. 245 */ 246 virtual PVMFStatus PeerConnect(PVMFPortInterface* aPort) = 0; 247 248 /** 249 * This method can be called during a Disconnect to disconnect 250 * the peer connection. 251 */ 252 virtual PVMFStatus PeerDisconnect() = 0; 253 254 protected: 255 PVMFPortInterface() 256 : iConnectedPort(NULL) 257 , iPortActivityHandler(NULL) 258 {} 259 PVMFPortInterface(PVMFPortActivityHandler* aNode) 260 : iConnectedPort(NULL) 261 , iPortActivityHandler(aNode) 262 {} 263 virtual void SetActivityHandler(PVMFPortActivityHandler* aNode) 264 { 265 iPortActivityHandler = aNode; 266 } 267 268 /** 269 ** The port implementation uses this routine to report 270 ** port activity to the activity handler (usually the 271 ** node that contains the port). 272 */ 273 virtual void PortActivity(PVMFPortActivityType aActivity) = 0; 274 275 PVMFPortInterface* iConnectedPort; 276 PVMFPortActivityHandler *iPortActivityHandler; 277 }; 278 279 #endif 280
