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 #ifndef PVMF_NODE_INTERFACE_H_INCLUDED 19 #define PVMF_NODE_INTERFACE_H_INCLUDED 20 21 22 #ifndef OSCL_BASE_H_INCLUDED 23 #include "oscl_base.h" 24 #endif 25 #ifndef OSCL_VECTOR_H_INCLUDED 26 #include "oscl_vector.h" 27 #endif 28 #ifndef PVMF_EVENT_HANDLING_H_INCLUDED 29 #include "pvmf_event_handling.h" 30 #endif 31 #ifndef PVMF_PORT_INTERFACE_H_INCLUDED 32 #include "pvmf_port_interface.h" 33 #endif 34 #ifndef PV_UUID_H_INCLUDED 35 #include "pv_uuid.h" 36 #endif 37 #ifndef PV_INTERFACE_H_INCLUDED 38 #include "pv_interface.h" 39 #endif 40 41 #ifndef OSCL_MEM_H_INCLUDED 42 #include "oscl_mem.h" 43 #endif 44 45 typedef struct 46 { 47 // PVMFPortType iInputCapability; 48 Oscl_Vector<PVMFFormatType, OsclMemAllocator> iInputFormatCapability; 49 // PVMFPortType iOutputCapability; 50 Oscl_Vector<PVMFFormatType, OsclMemAllocator> iOutputFormatCapability; 51 bool iCanSupportMultipleOutputPorts; 52 bool iCanSupportMultipleInputPorts; 53 bool iHasMaxNumberOfPorts; 54 int32 iMaxNumberOfPorts; 55 } PVMFNodeCapability; 56 57 58 /** 59 The events generated by the generic node/port base classes and the 60 sample node have all been replaced with the PVMF event codes, so no 61 event or error codes are defined here. However, some nodes may 62 still define additional event codes starting with these placeholder 63 values. The values are chosen to avoid conflict with any PVMF 64 return codes. 65 **/ 66 #define PVMF_NODE_INFO_EVENT_LAST 4096 67 #define PVMF_NODE_ERROR_EVENT_LAST 8192 68 69 70 /** 71 Node states 72 **/ 73 typedef enum 74 { 75 EPVMFNodeCreated 76 , EPVMFNodeIdle 77 , EPVMFNodeInitialized 78 , EPVMFNodePrepared 79 , EPVMFNodeStarted 80 , EPVMFNodePaused 81 , EPVMFNodeError 82 , EPVMFNodeLastState // derived nodes can add more states as needed 83 } TPVMFNodeInterfaceState; 84 85 /** 86 Oscl shared libary class 87 **/ 88 class OsclSharedLibrary; 89 90 /** 91 * PVMFNodeErrorEventObserver Class 92 * 93 * PVMFNodeErrorEventObserver is the node event observer class. It is used 94 * for communicating unsolicited error events back to the user. 95 * 96 * Applications using the module must have a class derived from 97 * PVMFNodeErrorEventObserver and implement the pure virtual function in 98 * order to receive error notifications. 99 **/ 100 class PVMFNodeErrorEventObserver 101 { 102 public: 103 /** 104 * Handle an error event that has been generated. 105 * 106 * @param "aEvent" "The event to be handled." 107 */ 108 virtual void HandleNodeErrorEvent(const PVMFAsyncEvent& aEvent) = 0; 109 110 virtual ~PVMFNodeErrorEventObserver() {} 111 }; 112 113 /** 114 * PVMFNodeInfoEventObserver Class 115 * 116 * PVMFNodeInfoEventObserver is the PVMF node event observer class. It is used 117 * for communicating unsolicited informational events back to the user. 118 * 119 * Applications using the module must have a class derived from 120 * PVMFNodeInfoEventObserver and implement the pure virtual function in 121 * order to receive informational event notifications. 122 **/ 123 class PVMFNodeInfoEventObserver 124 { 125 public: 126 /** 127 * Handle an informational event that has been generated. 128 * 129 * @param "aEvent" "The event to be handled." 130 */ 131 virtual void HandleNodeInformationalEvent(const PVMFAsyncEvent& aEvent) = 0; 132 133 virtual ~PVMFNodeInfoEventObserver() {} 134 }; 135 136 137 /** 138 * PVMFNodeCmdStatusObserver Class 139 * 140 * PVMFNodeCmdStatusObserver is the PVMF node observer class for notifying the 141 * status of issued command messages. The API provides a mechanism for 142 * the status of each command to be passed back along with context specific 143 * information where applicable. 144 * Applications using the module must have a class derived from 145 * PVMFNodeCmdStatusObserver and implement the pure virtual function in 146 * order to receive event notifications from a PV SDK. Addtional 147 * information is optionally provided via derived classes. 148 **/ 149 class PVMFNodeCmdStatusObserver 150 { 151 public: 152 /** 153 Handle an event that has been generated. 154 155 @param "aResponse" "The response to a previously issued command." 156 */ 157 virtual void NodeCommandCompleted(const PVMFCmdResp& aResponse) = 0; 158 159 virtual ~PVMFNodeCmdStatusObserver() {} 160 }; 161 162 163 class PVMFNodeInterface; 164 165 166 /** 167 A simple iterator for ports which just returns the number of ports 168 and the next in the list 169 **/ 170 171 class PVMFPortIter : public HeapBase 172 { 173 public: 174 virtual uint16 NumPorts() = 0; 175 virtual PVMFPortInterface* GetNext() = 0; 176 virtual void Reset() = 0; 177 virtual ~PVMFPortIter() {} 178 }; 179 180 /** 181 A base class for filter for ports 182 **/ 183 class PVMFPortFilter 184 { 185 public: 186 PVMFPortFilter() {}; 187 }; 188 189 class PVMFNodeSessionInfo 190 { 191 public: 192 PVMFNodeSessionInfo() 193 : iCmdStatusObserver(NULL) 194 , iInfoObserver(NULL) 195 , iErrorObserver(NULL) 196 , iInfoContext(NULL) 197 , iErrorContext(NULL) 198 {} 199 PVMFNodeSessionInfo(PVMFNodeCmdStatusObserver*c, 200 PVMFNodeInfoEventObserver*i, 201 OsclAny* ic, 202 PVMFNodeErrorEventObserver*e, 203 OsclAny* ec) 204 : iCmdStatusObserver(c) 205 , iInfoObserver(i) 206 , iErrorObserver(e) 207 , iInfoContext(ic) 208 , iErrorContext(ec) 209 {} 210 PVMFNodeCmdStatusObserver* iCmdStatusObserver; 211 PVMFNodeInfoEventObserver* iInfoObserver; 212 PVMFNodeErrorEventObserver* iErrorObserver; 213 OsclAny* iInfoContext; 214 OsclAny* iErrorContext; 215 }; 216 217 #define PVMF_NODE_DEFAULT_SESSION_RESERVE 10 218 219 class PVMFNodeSession 220 { 221 public: 222 PVMFSessionId iId; 223 PVMFNodeSessionInfo iInfo; 224 }; 225 226 class PVMFPortActivity; 227 class PVMFPortActivityHandler 228 { 229 public: 230 virtual ~PVMFPortActivityHandler() {} 231 virtual void HandlePortActivity(const PVMFPortActivity &) = 0; 232 }; 233 234 class OSCL_IMPORT_REF PVMFNodeInterface: public PVMFPortActivityHandler 235 { 236 public: 237 238 virtual ~PVMFNodeInterface() 239 { 240 iSessions.clear(); 241 } 242 243 virtual PVMFStatus ThreadLogon() = 0; 244 virtual PVMFStatus ThreadLogoff() = 0; 245 246 virtual PVMFSessionId Connect(const PVMFNodeSessionInfo &aSession) 247 { 248 PVMFNodeSession session; 249 session.iId = iSessions.size(); 250 session.iInfo = aSession; 251 iSessions.push_back(session); 252 return session.iId; 253 } 254 255 virtual PVMFStatus Disconnect(PVMFSessionId aSessionId) 256 { 257 for (uint32 i = 0; i < iSessions.size(); i++) 258 { 259 if (iSessions[i].iId == aSessionId) 260 { 261 iSessions.erase(&iSessions[i]); 262 return PVMFSuccess; 263 } 264 } 265 return PVMFFailure; 266 } 267 268 /** 269 GetCapability can be invoked only when after a node is initialized 270 **/ 271 virtual PVMFStatus GetCapability(PVMFNodeCapability& aNodeCapability) = 0; 272 273 274 /** 275 * Returns a list of ports currently available in the node that 276 * meet the filter criteria We can add fancier iterators and 277 * filters as needed. 278 * For now we return all the available ports. If no ports are 279 * present, NULL is returned 280 **/ 281 virtual PVMFPortIter* GetPorts(const PVMFPortFilter* aFilter = NULL) = 0; 282 283 /** 284 * Retrieves state information of this node 285 **/ 286 virtual TPVMFNodeInterfaceState GetState() 287 { 288 return iInterfaceState; 289 } 290 291 /** 292 * This API is to allow for extensibility of the PVMF Node interface. 293 * It allows a caller to ask for all UUIDs associated with a 294 * particular MIME type. If interfaces of the requested MIME type 295 * are found within the system, they are added to the UUIDs array. 296 * 297 * Also added to the UUIDs array will be all interfaces which have 298 * the requested MIME type as a base MIME type. This 299 * functionality can be turned off. 300 * 301 * @param aMimeType The MIME type of the desired interfaces 302 * @param aUuids A vector to hold the discovered UUIDs 303 * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with 304 * aMimeType as a base type 305 * @param aContext Optional opaque data to be passed back to user 306 * with the command response 307 * @returns A unique command id for asynchronous completion 308 */ 309 virtual PVMFCommandId QueryUUID(PVMFSessionId aSession 310 , const PvmfMimeString& aMimeType 311 , Oscl_Vector<PVUuid, OsclMemAllocator>& aUuids 312 , bool aExactUuidsOnly = false 313 , const OsclAny* aContext = NULL) = 0; 314 315 /** 316 * This API is to allow for extensibility of the PVMF Node interface. 317 * It allows a caller to ask for an instance of a particular 318 * interface object to be returned. The mechanism is analogous to 319 * the COM IUnknown method. The interfaces are identified with an 320 * interface ID that is a UUID as in DCE and a pointer to the 321 * interface object is returned if it is supported. Otherwise the 322 * returned pointer is NULL. 323 * 324 * @param aUuid The UUID of the desired interface 325 * @param aInterfacePtr The output pointer to the desired interface 326 * @param aContext Optional opaque data to be passed back to user 327 * with the command response 328 * @returns A unique command id for asynchronous completion 329 */ 330 virtual PVMFCommandId QueryInterface(PVMFSessionId aSession 331 , const PVUuid& aUuid 332 , PVInterface*& aInterfacePtr 333 , const OsclAny* aContext = NULL) = 0; 334 335 /** 336 * Requests the node to return a port meeting certain criteria for 337 * format types and buffering capabilities. The node may return a 338 * reference to an already created unused port or it may 339 * dynamically create one if it has the capability to do so. 340 * Since there might be some port specific initializations that 341 * might need to be done for ports created on demand, it will be 342 * most flexible to have this as an asynchronous API. 343 * 344 * A reference to the port interface is returned with the the 345 * command completion. It is passed as an auto ptr carrying 346 * opaque data that needs to be cast to PVMFPortInterface* 347 * @exception PVMFErrNotSupported leaves if this is not supported. 348 **/ 349 virtual PVMFCommandId RequestPort(PVMFSessionId aSession 350 , int32 aPortTag 351 , const PvmfMimeString* aPortConfig = NULL 352 , const OsclAny* aContext = NULL) = 0; 353 354 /** 355 * Releases a port back to the owning node. 356 * @exception PVMFErrArgument leaves if this node is not the owner. 357 **/ 358 virtual PVMFCommandId ReleasePort(PVMFSessionId aSession 359 , PVMFPortInterface& aPort 360 , const OsclAny* aContext = NULL) = 0; 361 362 /** 363 * Starts initialization of the node. At the minimum, the node 364 * should be ready to advertize its capabilities after 365 * initialization is complete 366 **/ 367 virtual PVMFCommandId Init(PVMFSessionId aSession 368 , const OsclAny* aContext = NULL) = 0; 369 370 /** 371 * Starts preparation of the node. 372 * Node should be ready to Start after the Prepare is 373 * complete. 374 **/ 375 virtual PVMFCommandId Prepare(PVMFSessionId aSession 376 , const OsclAny* aContext = NULL) = 0; 377 378 /** 379 * Causes the node to start servicing all connected ports. 380 **/ 381 virtual PVMFCommandId Start(PVMFSessionId aSession 382 , const OsclAny* aContext = NULL) = 0; 383 384 /** 385 * Causes the node to stop servicing all connected ports and 386 * discard any un-processed data. 387 **/ 388 virtual PVMFCommandId Stop(PVMFSessionId aSession 389 , const OsclAny* aContext = NULL) = 0; 390 391 /** 392 * Causes the node to stop servicing all connected ports as 393 * soon as current data is processed. 394 **/ 395 virtual PVMFCommandId Flush(PVMFSessionId aSession 396 , const OsclAny* aContext = NULL) = 0; 397 398 /** 399 * Causes the node to pause servicing all connected ports without 400 * discarding un-processed data. 401 **/ 402 virtual PVMFCommandId Pause(PVMFSessionId aSession 403 , const OsclAny* aContext = NULL) = 0; 404 405 /** 406 * Resets the node. The node should relinquish all resources that 407 * is has acquired as part of the initialization process and 408 * should be ready to be deleted when this completes. 409 **/ 410 virtual PVMFCommandId Reset(PVMFSessionId aSession 411 , const OsclAny* aContext = NULL) = 0; 412 413 /** 414 * Cancel all pending requests. The current request being 415 * processed, if any, will also be aborted. 416 * 417 * @param aContextData Optional opaque data that will be passed 418 * back to the user with the command response 419 * @returns A unique command id for asynchronous completion 420 */ 421 virtual PVMFCommandId CancelAllCommands(PVMFSessionId aSession 422 , const OsclAny* aContextData = NULL) = 0; 423 424 /** 425 * Cancels pending command with the specified ID. 426 * 427 * @param aCmdId Command Id of the command to be cancelled 428 * @param aContextData Optional opaque data that will be passed 429 * back to the user with the command response 430 * @returns A unique command id for asynchronous completion 431 */ 432 virtual PVMFCommandId CancelCommand(PVMFSessionId aSession 433 , PVMFCommandId aCmdId 434 , const OsclAny* aContextData = NULL) = 0; 435 436 /** 437 * Ports call this API to report activity to the node. 438 * 439 * @param aActivity Information regarding the activity. 440 */ 441 virtual void HandlePortActivity(const PVMFPortActivity& aActivity) = 0; 442 443 /** 444 * This API is a synchronous version of QueryInterface. 445 * The mechanism is analogous to the COM IUnknown method. The 446 * interfaces are identified with an interface ID that is a UUID 447 * as in DCE and a pointer to the interface object is returned if 448 * it is supported. Otherwise the returned pointer is NULL. 449 * 450 * @param aUuid The UUID of the desired interface 451 * @param aInterfacePtr The output pointer to the desired interface 452 * @returns PVMFSuccess or PVMFErrNotSupported 453 */ 454 virtual PVMFStatus QueryInterfaceSync(PVMFSessionId aSession 455 , const PVUuid& aUuid 456 , PVInterface*& aInterfacePtr) 457 { 458 return PVMFErrNotImplemented; 459 } 460 461 462 /** 463 * Set shared library pointer 464 * @param aPtr Pointer to the shared library. 465 **/ 466 virtual void SetSharedLibraryPtr(OsclSharedLibrary* aPtr) 467 { 468 iOsclSharedLibrary = aPtr; 469 } 470 471 /** 472 * Retrieves shared library pointer 473 * @returns Pointer to the shared library. 474 **/ 475 virtual OsclSharedLibrary* GetSharedLibraryPtr() 476 { 477 return iOsclSharedLibrary; 478 } 479 480 protected: 481 PVMFNodeInterface(int32 aSessionReserve = PVMF_NODE_DEFAULT_SESSION_RESERVE): 482 iInterfaceState(EPVMFNodeCreated) 483 , iOsclSharedLibrary(NULL) 484 { 485 iSessions.reserve(aSessionReserve); 486 } 487 488 Oscl_Vector<PVMFNodeSession, OsclMemAllocator> iSessions; 489 TPVMFNodeInterfaceState iInterfaceState; 490 491 OsclSharedLibrary* iOsclSharedLibrary; 492 493 /** This method can be used to update the state and 494 ** notify observers of the state change event. 495 */ 496 OSCL_IMPORT_REF virtual void SetState(TPVMFNodeInterfaceState); 497 498 /* For the given session id, forward the command response if an 499 * observer exists. No-op if the session id is bad or no command 500 * complete observer exists on that session. 501 * 502 * @param session_id Created when the user who should receive this 503 * event connected to that node. 504 * @param resp Command complete event. 505 */ 506 OSCL_IMPORT_REF virtual void ReportCmdCompleteEvent(PVMFSessionId session_id, 507 const PVMFCmdResp &resp); 508 509 /* For each session handled by the node, if an appropriate 510 * observer exists (info, error) a copy of the event is 511 * dispatched with a copy of the session info/error context. 512 * No-op if the event category is wrong. 513 * 514 * @param event To be reported to the session(s) observer(s) for 515 * the event's category. 516 */ 517 OSCL_IMPORT_REF virtual void ReportErrorEvent(const PVMFAsyncEvent& aEvent); 518 OSCL_IMPORT_REF virtual void ReportInfoEvent(const PVMFAsyncEvent& aEvent); 519 520 /* Similar to the above except the event is built first. 521 * TODO: Get rid of these. Callers should build the event object 522 * including the pointer to their interfaces. 523 */ 524 OSCL_IMPORT_REF virtual void ReportErrorEvent(PVMFEventType aEventType, 525 void* aEventData = NULL, 526 PVInterface*aExtMsg = NULL); 527 OSCL_IMPORT_REF virtual void ReportInfoEvent(PVMFEventType aEventType, 528 void* aEventData = NULL, 529 PVInterface*aExtMsg = NULL); 530 }; 531 532 #endif 533
