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 PVAUTHORENGINEINTERFACE_H_INCLUDED 19 #define PVAUTHORENGINEINTERFACE_H_INCLUDED 20 21 #ifndef OSCL_BASE_H_INCLUDED 22 #include "oscl_base.h" 23 #endif 24 #ifndef OSCL_STRING_H_INCLUDED 25 #include "oscl_string.h" 26 #endif 27 #ifndef PV_ENGINE_TYPES_H_INCLUDED 28 #include "pv_engine_types.h" 29 #endif 30 31 // Forward declarations 32 class PVMFNodeInterface; 33 class PVLoggerAppender; 34 template<class T, class Alloc> class Oscl_Vector; 35 36 /** 37 * An enumeration of the major states of the pvAuthor Engine. 38 */ 39 enum PVAEState 40 { 41 PVAE_STATE_IDLE = 0, 42 PVAE_STATE_OPENED, 43 PVAE_STATE_INITIALIZED, 44 PVAE_STATE_RECORDING, 45 PVAE_STATE_PAUSED, 46 PVAE_STATE_ERROR 47 }; 48 49 /** 50 * Enumeration of errors from pvAuthor Engine. 51 */ 52 enum PVAEErrorEvent 53 { 54 // TBD 55 PVAE_ENCODE_ERROR 56 }; 57 58 /** 59 * Enumeration of informational events from pvAuthor Engine. 60 */ 61 enum PVAEInfoEvent 62 { 63 // TBD 64 PVAE_OUTPUT_PROGRESS 65 }; 66 67 68 /** 69 * PVAuthorEngineInterface 70 **/ 71 class PVAuthorEngineInterface 72 { 73 public: 74 /** 75 * Destructor. 76 */ 77 virtual ~PVAuthorEngineInterface() {}; 78 79 /** 80 * Allows a logging appender to be attached at some point in the 81 * logger tag tree. The location in the tag tree is specified by the 82 * input tag string. A single appender can be attached multiple times in 83 * the tree, but it may result in duplicate copies of log messages if the 84 * appender is not attached in disjoint portions of the tree. 85 * A logging appender is responsible for actually writing the log message 86 * to its final location (e.g., memory, file, network, etc). 87 * Currently this API is NOT SUPPORTED. 88 * 89 * @param aTag Specifies the logger tree tag where the appender should be attached. 90 * @param aAppender The log appender to attach. 91 * @param aContextData 92 * Optional opaque data that will be passed back to the user with the command response 93 * 94 * @exception memory_error leaves on memory allocation error. 95 * 96 * @returns A unique command id for asynchronous completion 97 */ 98 virtual PVCommandId SetLogAppender(const char* aTag, PVLoggerAppender& aAppender, const OsclAny* aContextData = NULL) = 0; 99 100 /** 101 * Allows a logging appender to be removed from the logger tree at the 102 * point specified by the input tag. If the input tag is NULL then the 103 * appender will be removed from locations in the tree. 104 * Currently this API is NOT SUPPORTED. 105 * 106 * @param aTag Specifies the logger tree tag where the appender should be removed. 107 * Can be NULL to remove at all locations. 108 * @param aAppender The log appender to remove. 109 * @param aContextData 110 * Optional opaque data that will be passed back to the user with the command response 111 * 112 * @exception memory_error leaves on memory allocation error. 113 * 114 * @returns A unique command id for asynchronous completion 115 */ 116 virtual PVCommandId RemoveLogAppender(const char* aTag, PVLoggerAppender& aAppender, const OsclAny* aContextData = NULL) = 0; 117 118 /** 119 * Allows the logging level to be set for the logging node specified by the 120 * tag. A larger log level will result in more messages being logged. A message 121 * will only be logged if its level is LESS THAN or equal to the current log level. 122 * The set_subtree flag will allow an entire subtree, with the specified tag as the root, 123 * to be reset to the specified value. 124 * Currently this API is NOT SUPPORTED. 125 * 126 * @param aTag Specifies the logger tree tag where the log level should be set. 127 * @param aLevel Specifies the log level to set. 128 * @param aSetSubtree Specifies whether the entire subtree with aTag as the root should 129 * be reset to the log level. 130 * @param aContextData 131 * Optional opaque data that will be passed back to the user with the command response 132 * 133 * @exception memory_error leaves on memory allocation error. 134 * 135 * @returns A unique command id for asynchronous completion 136 */ 137 virtual PVCommandId SetLogLevel(const char* aTag, int32 aLevel, bool aSetSubtree = false, const OsclAny* aContextData = NULL) = 0; 138 139 /** 140 * Allows the logging level to be queried for a particular logging tag. 141 * A larger log level will result in more messages being logged. 142 * 143 * In the asynchronous response, this should return the log level along with an 144 * indication of where the level was inherited (i.e., the ancestor tag). 145 * Currently this API is NOT SUPPORTED. 146 * 147 * @param aTag Specifies the logger tree tag where the log level should be retrieved. 148 * @param aLogInfo An output parameter which will be filled in with the log level information. 149 * @param aContextData 150 * Optional opaque data that will be passed back to the user with the command response 151 * @exception memory_error leaves on memory allocation error. 152 * 153 * @returns A unique command id for asynchronous completion 154 */ 155 virtual PVCommandId GetLogLevel(const char* aTag, PVLogLevelInfo& aLogInfo, const OsclAny* aContextData = NULL) = 0; 156 157 /** 158 * Opens an authoring session. 159 * 160 * This command is valid only when pvAuthor engine is in PVAE_STATE_IDLE state. Upon completion 161 * of this method, pvAuthor engine will be in PVAE_STATE_OPENED state. 162 * 163 * @param aContextData Optional opaque data to be passed back to user with the command response 164 * @return Unique command ID to identify this command in command response 165 */ 166 virtual PVCommandId Open(const OsclAny* aContextData = NULL) = 0; 167 168 /** 169 * Closes an authoring session. 170 * 171 * All resources added and allocated to the authoring session will be released. 172 * 173 * This command is valid only when pvAuthor engine is in PVAE_STATE_OPENED state and Upon 174 * completion of this command, pvAuthor Engine will be in PVAE_STATE_IDLE state. 175 * 176 * @param aContextData Optional opaque data to be passed back to user with the command response 177 * @return Unique command ID to identify this command in command response 178 */ 179 virtual PVCommandId Close(const OsclAny* aContextData = NULL) = 0; 180 181 /** 182 * Adds a media source to be used as input to an authoring session. 183 * 184 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. 185 * This command does not change the pvAuthor Engine engine state. 186 * 187 * @param aDataSource Reference to the data source 188 * @param aContextData Optional opaque data to be passed back to user with the command response 189 * @return Unique command ID to identify this command in command response 190 */ 191 virtual PVCommandId AddDataSource(const PVMFNodeInterface& aDataSource, const OsclAny* aContextData = NULL) = 0; 192 193 /** 194 * Unbinds a previously added data source. 195 * 196 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. 197 * This command does not change the pvAuthor Engine engine state. 198 * 199 * @param aDataSource Reference to the data source to be removed 200 * @param aContextData Optional opaque data to be passed back to user with the command response 201 * @returns A unique command id for asynchronous completion 202 */ 203 virtual PVCommandId RemoveDataSource(const PVMFNodeInterface& aDataSource, const OsclAny* aContextData = NULL) = 0; 204 205 /** 206 * Selects an output composer by specifying its MIME type. 207 * 208 * pvAuthor engine will use the most suitable output composer of the specified MIME type available 209 * in the authoring session. This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED 210 * state. This command does not change the pvAuthor Engine state. 211 * 212 * Upon completion of this command, opaque data to indentify the selected composer is provided in the 213 * callback. The user needs to use this opaque data to identify the composer when calling AddMediaTrack(), 214 * AddDataSink(). A configuration interface for the selected composer will be 215 * saved to the PVInterface pointer provided in aConfigInterface parameter. User should call 216 * queryInterface to query for the configuration interfaces supported by the composer. When 217 * configuration is complete or before calling Reset(), user must call 218 * removeRef on the PVInterface object to remove its reference to the object. 219 * 220 * @param aComposerType MIME type of output composer to be used 221 * @param aConfigInterface Pointer to configuration object for the selected composer will be 222 * saved to this parameter upon completion of this call 223 * @param aContextData Optional opaque data to be passed back to user with the command response 224 * @returns A unique command id for asynchronous completion 225 */ 226 virtual PVCommandId SelectComposer(const PvmfMimeString& aComposerType, 227 PVInterface*& aConfigInterface, 228 const OsclAny* aContextData = NULL) = 0; 229 230 /** 231 * Selects an output composer by specifying its Uuid. 232 * 233 * pvAuthor engine the composer of the specified Uuid in the authoring session. 234 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. This command does 235 * not change the pvAuthor Engine state. 236 * 237 * Upon completion of this command, opaque data to indentify the selected composer is provided in the 238 * callback. The user needs to use this opaque data to identify the composer when calling AddMediaTrack(), 239 * AddDataSink(). A configuration interface for the selected composer will be 240 * saved to the PVInterface pointer provided in aConfigInterface parameter. User should call 241 * queryInterface to query for the configuration interfaces supported by the composer. When 242 * configuration is complete or before calling Reset(), user must call 243 * removeRef on the PVInterface object to remove its reference to the object. 244 * 245 * @param aComposerUuid Uuid of output composer to be used 246 * @param aConfigInterface Pointer to configuration object for the selected composer will be 247 * saved to this parameter upon completion of this call 248 * @param aContextData Optional opaque data to be passed back to user with the command response 249 * @returns A unique command id for asynchronous completion 250 */ 251 virtual PVCommandId SelectComposer(const PVUuid& aComposerUuid, 252 PVInterface*& aConfigInterface, 253 const OsclAny* aContextData = NULL) = 0; 254 255 /** 256 * Add a media track to the specified composer. 257 * 258 * The source data of this media track will come from the specified data source. pvAuthor engine 259 * will select the most suitable available encoder of the specified type. A media track will be 260 * added to the specified composer, and encoded data will be written to the composer during the 261 * authoring session. 262 * 263 * A configuration object for the selected composer will be saved to the PVInterface pointer 264 * provided in aConfigInterface parameter. User should call queryInterface to query for the 265 * configuration interfaces supported by the encoder. Before calling Reset(), user must call 266 * removeRef on the PVInterface object to remove its reference to the object. 267 * 268 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. The referenced 269 * data source and composer must be already added before this method is called. 270 * This command does not change the pvAuthor Engine engine state. 271 * 272 * @param aDataSource Data source node to provide input data 273 * @param aEncoderType MIME type of encoder to encode the source data 274 * @param aComposer Opaque data to identify the composer in which a media track will be added. 275 * @param aConfigInterface Pointer to configuration object for the selected encoder will be 276 * saved to this parameter upon completion of this call 277 * @param aContextData Optional opaque data to be passed back to user with the command response 278 * @returns A unique command id for asynchronous completion 279 */ 280 virtual PVCommandId AddMediaTrack(const PVMFNodeInterface& aDataSource, 281 const PvmfMimeString& aEncoderType, 282 const OsclAny* aComposer, 283 PVInterface*& aConfigInterface, 284 const OsclAny* aContextData = NULL) = 0; 285 286 /** 287 * Add a media track to the specified composer. 288 * 289 * The source data of this media track will come from the specified data source. pvAuthor engine 290 * will encoder of the specified Uuid to encode the source data. A media track will be 291 * added to the specified composer, and encoded data will be written to the composer during the 292 * authoring session. 293 * 294 * A configuration object for the selected composer will be saved to the PVInterface pointer 295 * provided in aConfigInterface parameter. User should call queryInterface to query for the 296 * configuration interfaces supported by the encoder. Before calling Reset(), user must call 297 * removeRef on the PVInterface object to remove its reference to the object. 298 * 299 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. The referenced 300 * data source and composer must be already added before this method is called. 301 * This command does not change the pvAuthor Engine engine state. 302 * 303 * @param aDataSource Data source node to provide input data 304 * @param aEncoderUuid Uuid of encoder to encode the source data 305 * @param aComposer Opaque data to identify the composer in which a media track will be added. 306 * @param aConfigInterface Pointer to configuration object for the selected encoder will be 307 * saved to this parameter upon completion of this call 308 * @param aContextData Optional opaque data to be passed back to user with the command response 309 * @returns A unique command id for asynchronous completion 310 */ 311 virtual PVCommandId AddMediaTrack(const PVMFNodeInterface& aDataSource, 312 const PVUuid& aEncoderUuid, 313 const OsclAny* aComposer, 314 PVInterface*& aConfigInterface, 315 const OsclAny* aContextData = NULL) = 0; 316 317 /** 318 * Adds a media sink where output data from the specified composer will be written to. 319 * Currently this API does not cause any action as it is not relevant. 320 * 321 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. The 322 * referenced composer must be previously selected. 323 * 324 * This command does not change the pvAuthor Engine engine state. 325 * 326 * @param aDataSink Reference to the data sink to be used 327 * @param aComposer Opaque data identifying the composer to which the data sink will connect to. 328 * @param aContextData Optional opaque data to be passed back to user with the command response 329 * @returns A unique command id for asynchronous completion 330 */ 331 virtual PVCommandId AddDataSink(const PVMFNodeInterface& aDataSink, 332 const OsclAny* aComposer, 333 const OsclAny* aContextData = NULL) = 0; 334 335 /** 336 * Removes a previously added data sink. 337 * Currently this API does not cause any action as it is not relevant. 338 339 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. 340 * This command does not change the pvAuthor Engine engine state. 341 * 342 * @param aDataSink Reference to the data sink to be removed 343 * @param aContextData Optional opaque data to be passed back to user with the command response 344 * @returns A unique command id for asynchronous completion 345 */ 346 virtual PVCommandId RemoveDataSink(const PVMFNodeInterface& aDataSink, const OsclAny* aContextData = NULL) = 0; 347 348 349 /** 350 * Initialize an authoring session. 351 * 352 * Upon calling this method, no more data sources and sinks can be added to the 353 * session. Also, all configuration settings will be locked and cannot 354 * be modified until the session is reset by calling Reset(). Resources for the 355 * session will allocated and initialized to the configuration settings specified. 356 * This command is valid only when pvAuthor Engine is in PVAE_STATE_OPENED state. 357 * 358 * Upon completion of this command, pvAuthor Engine will be in PVAE_STATE_INITIALIZED 359 * state, and the authoring session is ready to start. 360 * 361 * @param aContextData Optional opaque data to be passed back to user with the command response 362 * @returns A unique command id for asynchronous completion 363 */ 364 virtual PVCommandId Init(const OsclAny* aContextData = NULL) = 0; 365 366 /** 367 * Reset an initialized authoring session. 368 * 369 * The authoring session will be stopped and all composers and encoders selected for 370 * the session will be removed. All data sources and sinks will be reset but will 371 * continue to be available for authoring the next output clip. 372 * 373 * User must call removeRef() to remove its reference to any PVInterface objects 374 * received from SelectComposer() or AddMediaTrack() or QueryInterface() APIs 375 * before calling this method. This method would fail otherwise. 376 * 377 * This method can be called from ANY state but PVAE_STATE_IDLE. Upon completion of this command, pvAuthor 378 * Engine will be in PVAE_STATE_OPENED state. 379 * 380 * @param aContextData Optional opaque data to be passed back to user with the command response 381 * @returns A unique command id for asynchronous completion 382 */ 383 virtual PVCommandId Reset(const OsclAny* aContextData = NULL) = 0; 384 385 /** 386 * Start the authoring session. 387 * 388 * pvAuthor Engine will begin to receive source data, encode them to the specified format 389 * and quality, and send the output data to the specified data sinks. 390 * This function is valid only in the PVAE_STATE_INITIALIZED state. 391 * 392 * Upon completion of this command, pvAuthor Engine will be in PVAE_STATE_RECORDING state. 393 * 394 * @param aContextData Optional opaque data to be passed back to user with the command response 395 * @returns A unique command id for asynchronous completion 396 */ 397 virtual PVCommandId Start(const OsclAny* aContextData = NULL) = 0; 398 399 /** 400 * Pause the authoring session. 401 * 402 * The authoring session will be paused and no encoded output data will be sent to 403 * the data sink. This function is valid only in the PVAE_STATE_RECORDING state. 404 * 405 * Upon completion of this command, pvAuthor Engine will be in PVAE_STATE_PAUSED state. 406 * 407 * @param aContextData Optional opaque data to be passed back to user with the command response 408 * @returns A unique command id for asynchronous completion 409 */ 410 virtual PVCommandId Pause(const OsclAny* aContextData = NULL) = 0; 411 412 /** 413 * Resume a paused authoring session. 414 * 415 * The authoring session will be resumed and pvAuthor Engine will resume sending encoded 416 * output data to the data sinks. This function is valid only in the PVAE_STATE_PAUSED state. 417 * 418 * Upon completion of this command, pvAuthor Engine will be in PVAE_STATE_RECORDING state. 419 * 420 * @param aContextData Optional opaque data to be passed back to user with the command response 421 * @returns A unique command id for asynchronous completion 422 */ 423 virtual PVCommandId Resume(const OsclAny* aContextData = NULL) = 0; 424 425 /** 426 * Stops an authoring session. 427 * 428 * The authoring session will be stopped and pvAuthor Engine will stop receiving source data 429 * from the data sources, and no further encoded data will be sent to the data sinks. 430 * This function is valid only in the PVAE_STATE_RECORDING and PVAE_STATE_PAUSED states. 431 * 432 * Upon completion of this command, pvAuthor Engine will be in PVAE_STATE_INITIALIZED state. 433 * 434 * @param aContextData Optional opaque data to be passed back to user with the command response 435 * @returns A unique command id for asynchronous completion 436 */ 437 virtual PVCommandId Stop(const OsclAny* aContextData = NULL) = 0; 438 439 /** 440 * This function returns the current state of the pvAuthor Engine. 441 * Application may use this info for updating display or determine if the pvAuthor Engine is 442 * ready for the next command. 443 * 444 * @param aState Output parameter to hold state information 445 * @param aContextData Optional opaque data to be passed back to user with the command response 446 * @returns A unique command id for synchronous completion 447 */ 448 virtual PVAEState GetPVAuthorState() = 0; 449 450 /** 451 * Discover the UUIDs of interfaces associated with the specified MIME type and node 452 * 453 * This API is to allow for extensibility of the pvAuthor Engine interface. User can query for 454 * all UUIDs associated with a particular MIME type. The UUIDs will be added to the aUuids 455 * vector provided by the user. 456 * Currently this API is NOT SUPPORTED. 457 * 458 * @param aMimeType The MIME type of the desired interfaces 459 * @param aUuids A vector to hold the discovered UUIDs 460 * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with aMimeType as a base type 461 * @param aContextData Optional opaque data to be passed back to user with the command response 462 * @returns A unique command id for asynchronous completion 463 */ 464 virtual PVCommandId QueryUUID(const PvmfMimeString& aMimeType, 465 Oscl_Vector<PVUuid, OsclMemAllocator>& aUuids, 466 bool aExactUuidsOnly = false, 467 const OsclAny* aContextData = NULL) = 0; 468 469 /** 470 * This API is to allow for extensibility of the pvAuthor engine interface. 471 * It allows a caller to ask for an instance of a particular interface object to be returned. 472 * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with 473 * an interface ID that is a UUID as in DCE and a pointer to the interface object is 474 * returned if it is supported. Otherwise the returned pointer is NULL. 475 * TBD: Define the UIID, InterfacePtr structures 476 * 477 * @param aUuid The UUID of the desired interface 478 * @param aInterfacePtr The output pointer to the desired interface 479 * @param aContextData Optional opaque data to be passed back to user with the command response 480 * @returns A unique command id for asynchronous completion 481 */ 482 virtual PVCommandId QueryInterface(const PVUuid& aUuid, 483 PVInterface*& aInterfacePtr, 484 const OsclAny* aContextData = NULL) = 0; 485 486 /** 487 * Returns information about all modules currently used by the SDK. 488 * Currently this API is NOT SUPPORTED. 489 * 490 * @param aSDKModuleInfo A reference to a PVSDKModuleInfo structure which contains 491 * the number of modules currently used by pvAuthor Engine and the PV UID and description 492 * string for each module. The PV UID and description string for modules will be 493 * returned in one string buffer allocated by the client. If the string buffer is not 494 * large enough to hold the all the module's information, the information will be written 495 * up to the length of the buffer and truncated. 496 * @param aContextData Optional opaque data that will be passed back to the user with the command response 497 * @returns A unique command id for asynchronous completion 498 */ 499 virtual PVCommandId GetSDKModuleInfo(PVSDKModuleInfo& aSDKModuleInfo, const OsclAny* aContextData = NULL) = 0; 500 501 /** 502 * Cancel all pending requests. The current request being processed, if any, will also be aborted. 503 * PVAE_CMD_CANCEL_ALL_COMMANDS will be passed to the command observer on completion. 504 * Currently this API is NOT SUPPORTED. 505 * 506 * @param aContextData Optional opaque data that will be passed back to the user with the command response 507 * @returns A unique command id for asynchronous completion 508 */ 509 virtual PVCommandId CancelAllCommands(const OsclAny* aContextData = NULL) = 0; 510 511 /** 512 * Returns SDK version information about author engine. 513 * 514 * @param aSDKInfo 515 * A reference to a PVSDKInfo structure which contains product name, supported hardware platform, 516 * supported software platform, version, part number, and PV UUID. These fields will contain info 517 * .for the currently instantiated pvPlayer engine when this function returns success. 518 * 519 **/ 520 OSCL_IMPORT_REF static void GetSDKInfo(PVSDKInfo& aSDKInfo); 521 }; 522 523 #endif // PVAUTHORENGINE_H_INCLUDED 524 525 526
