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* ============================================================================== 20* Name : pv_2way_interface.h 21* Part of : 22* Interface : 23* Description : Interface class and supporting definitions for the PV2Way SDK 24* Version : (see RELEASE field in copyright header above) 25* 26* ============================================================================== 27*/ 28 29#ifndef PV_2WAY_INTERFACE_H_INCLUDED 30#define PV_2WAY_INTERFACE_H_INCLUDED 31 32 33// INCLUDES 34#ifndef PV_COMMON_TYPES_H_INCLUDED 35#include "pv_common_types.h" 36#endif 37 38#ifndef OSCL_VECTOR_H_INCLUDED 39#include "oscl_vector.h" 40#endif 41 42#ifndef PVT_COMMON_H_INCLUDED 43#include "pvt_common.h" 44#endif 45 46#ifndef PVMF_NODE_INTERFACE_H_INCLUDED 47#include "pvmf_node_interface.h" 48#endif 49 50#ifndef PVLOGGER_ACCESSORIES_H_INCLUDED 51#include "pvlogger_accessories.h" 52#endif 53 54#ifndef PV_ENGINE_TYPES_H_INCLUDED 55#include "pv_engine_types.h" 56#endif 57 58#ifndef PVT_2WAY_BASIC_TYPES_H_INCLUDED 59#include "pv_2way_basic_types.h" 60#endif 61 62#ifndef PV_2WAY_H324M_TYPES_H_INCLUDED 63#include "pv_2way_h324m_types.h" 64#endif 65 66 67// CONSTANTS 68 69// DATA TYPES 70 71// CLASS DECLARATION 72 73/** 74 * CPV2WayInterface Class 75 * 76 * CPV2WayInterface is the interface to the pv2way SDK, which 77 * allows initialization, control, and termination of a two-way (3g-324m, SIP) terminal. 78 * The application is expected to contain and maintain a pointer to the 79 * CPV2WayInterface instance at all times that a call is active. 80 * The CPV2WayFactory factory class is to be used to create and 81 * delete instances of this class 82 **/ 83class CPV2WayInterface 84{ 85 public: 86 /** 87 * Object destructor function 88 * Releases Resources prior to destruction 89 **/ 90 virtual ~CPV2WayInterface() {}; 91 92 /** 93 * Returns version information about the SDK 94 * 95 * @param aSDKInfo 96 * A reference to a PVSDKInfo structure which contains the product label and date 97 * @param aContextData 98 * Optional opaque data that will be passed back to the user with the command response 99 * @leave This method can leave with one of the following error codes 100 * PVMFErrNoMemory if the SDK failed to allocate memory during this operation 101 * @returns A unique command id for asynchronous completion 102 **/ 103 OSCL_IMPORT_REF virtual PVCommandId GetSDKInfo(PVSDKInfo &aSDKInfo, 104 OsclAny* aContextData = NULL) = 0; 105 106 /** 107 * Returns information about all modules currently used by the SDK. 108 * 109 * @param aSDKModuleInfo 110 * A reference to a PVSDKModuleInfo structure which contains the number of modules currently used by 111 * pv2way SDK and the PV UID and description string for each module. The PV UID and description string 112 * for modules will be returned in one string buffer allocated by the client. If the string buffer 113 * is not large enough to hold the all the module's information, the information will be written 114 * up to the length of the buffer and truncated. 115 * @param aContextData 116 * Optional opaque data that will be passed back to the user with the command response 117 * @leave This method can leave with one of the following error codes 118 * PVMFErrNoMemory if the SDK failed to allocate memory during this operation 119 * @returns A unique command id for asynchronous completion 120 **/ 121 OSCL_IMPORT_REF virtual PVCommandId GetSDKModuleInfo(PVSDKModuleInfo &aSDKModuleInfo, 122 OsclAny* aContextData = NULL) = 0; 123 124 125 /** 126 * This function is valid only in the EIdle state. It is a no-op when 127 * invoked in any other state. It causes the pv2way to transition 128 * to the ESetup state. The terminal remains in the EInitializing state during 129 * the transition. 130 * 131 * While initializing, the pv2way tries to allocate system resources needed 132 * for a two-way call. If it fails for some reason, 133 * and the pv2way reverts to the EIdle state. All the resources are de-allocated. 134 * 135 * 136 * @param aInitInfo 137 * A reference to a CPV2WayInitInfo structure which contains the capabilities of the applications sinks 138 * and sources to handle compressed and uncompressed formats. 139 * @param aContextData 140 * Optional opaque data that will be passed back to the user with the command response 141 * @leave This method can leave with one of the following error codes 142 * PVMFErrArgument if more tx and rx codecs are set than engine can handle, or the mandatory codecs are not in the list. 143 * PVMFErrNotSupported if the format of the sources/sinks is incomtible with what the SDK can handle 144 * PVMFErrInvalidState if invoked in the incorrect state 145 * PVMFErrNoMemory if the SDK failed to allocate memory during this operation 146 * @returns A unique command id for asynchronous completion 147 **/ 148 OSCL_IMPORT_REF virtual PVCommandId Init(PV2WayInitInfo& aInitInfo, 149 OsclAny* aContextData = NULL) = 0; 150 151 /** 152 * This function is valid only in the ESetup and EInitializing state. It is a 153 * no-op when invoked in the EIdle state and returns PVMFErrInvalidState 154 * if invoked in any other state. 155 * 156 * It causes the pv2way to transition back to the EIdle state. The 157 * terminal remains in the EResetting state during the transition. 158 * 159 * While resetting, the pv2way de-allocates all resources resources that 160 * had been previously allocated. When it completes, ResetComplete is called 161 * and the pv2way reverts to the EIdle state. 162 * 163 * @param aContextData 164 * Optional opaque data that will be passed back to the user with the command response 165 * @leave This method can leave with one of the following error codes 166 * PVMFErrInvalidState if invoked in the incorrect state 167 * PVMFErrNoMemory if the SDK failed to allocate memory during this operation 168 * @returns A unique command id for asynchronous completion 169 **/ 170 OSCL_IMPORT_REF virtual PVCommandId Reset(OsclAny* aContextData = NULL) = 0; 171 172 /** 173 * This function allows the user to specify the media source for an outgoing track. 174 * Sources should be added after the PVT_INDICATION_OUTGOING_TRACK is received which specifies the format type 175 * and the unique track id. The format type is indicated using the PV2WayTrackInfoInterface extension interface in the 176 * PVAsyncInformationalEvent. 177 * Data sources could be of the following types: 178 * a)raw media sources like camera, microphone etc. 179 * b)sources of compressed data like file, combined capture and encode devices. 180 * 181 * @param aTrackId 182 * The outgoing track id 183 * @param aDataSource 184 * Reference to the data source for this track 185 * @param aContextData 186 * Optional opaque data that will be passed back to the user with the command response 187 * @leave This method can leave with one of the following error codes 188 * PVMFErrNotSupported if the format of the sources/sinks is incomtible with what the SDK can handle 189 * KPVErrInvalidState if invoked in the incorrect state 190 * KErrNoMemory if the SDK failed to allocate memory during this operation 191 * @return A unique command id for asynchronous completion 192 */ 193 OSCL_IMPORT_REF virtual PVCommandId AddDataSource(PVTrackId aTrackId, 194 PVMFNodeInterface& aDataSource, 195 OsclAny* aContextData = NULL) = 0; 196 197 /** 198 * This function unbinds a previously added source. 199 * 200 * @param aDataSource pointer to the media source node 201 * 202 * @param aContextData 203 * Optional opaque data that will be passed back to the user with the command response 204 * @returns A unique command id for asynchronous completion 205 **/ 206 OSCL_IMPORT_REF virtual PVCommandId RemoveDataSource(PVMFNodeInterface& aDataSource, 207 OsclAny* aContextData = NULL) = 0; 208 209 /** 210 * This function allows the user to specify the media sink for an incoming track. 211 * AddDataSinkL can be called only for established incoming tracks identified by a unique 212 * track id. 213 * Incoming tracks are initiated by the peer and their establishment is indicated using the 214 * PVT_INDICATION_INCOMING_TRACK notification which provides the media type and a unique track id. 215 * The format type is indicated using the PV2WayTrackInfoInterface extension interface in the 216 * PVAsyncInformationalEvent. 217 * Data sinks could be of the following types: 218 * a)raw media sinks like video display sinks for RGB and YUV formats, audio rendering sinks for PCM. 219 * b)sources of compressed data like file, combined decode and render devices. 220 * 221 * 222 * @param aTrackId 223 * Indicates the unique track id to be associated with this sink. 224 * @param aDataSink The data sink to be added 225 * @param aContextData 226 * Optional opaque data that will be passed back to the user with the command response 227 * 228 * @return A unique command id for asynchronous completion 229 **/ 230 OSCL_IMPORT_REF virtual PVCommandId AddDataSink(PVTrackId aTrackId, 231 PVMFNodeInterface& aDataSink, 232 OsclAny* aContextData = NULL) = 0; 233 234 /** 235 * This function unbinds a previously added sink. 236 * 237 * @param aDataSink pointer to the media sink node 238 * @param aContextData 239 * Optional opaque data that will be passed back to the user with the command response 240 * 241 * @returns A unique command id for asynchronous completion 242 **/ 243 OSCL_IMPORT_REF virtual PVCommandId RemoveDataSink(PVMFNodeInterface& aDataSink, 244 OsclAny* aContextData = NULL) = 0; 245 246 /** 247 * This function can be invoked only in the ESetup state. The terminal starts connecting with the remote 248 * terminal based on the specified options and capabilities. 249 * Incoming tracks may be opened before ConnectL completes and will be indicated via the 250 * PVT_INDICATION_INCOMING_TRACK event. 251 * 252 * @param aOptions 253 * Optional additional information for call setup. 254 * @param aCommServer 255 * An optional pointer to a comm server to provide comm source and sink end-points. 256 * @param aContextData 257 * Optional opaque data that will be passed back to the user with the command response 258 * 259 * @returns A unique command id for asynchronous completion 260 **/ 261 OSCL_IMPORT_REF virtual PVCommandId Connect(const PV2WayConnectOptions& aOptions, 262 PVMFNodeInterface* aCommServer = NULL, 263 OsclAny* aContextData = NULL) = 0; 264 265 /** 266 * The Disconnect call is valid only when invoked in the EConnecting, and 267 * EConnected states. It causes the terminal to transition to the 268 * EDisconnecting state. All the media tracks both incoming and outgoing 269 * will be closed on invoking Disconnect. On completion, the terminal 270 * goes to the ESetup state. The statistics of the previous call shall 271 * still be available until Connect is invoked again. 272 * 273 * It is a no-op when called in any other state. 274 * 275 * The post disconnect option specifies what this terminal wishes to do 276 * after the data call is terminated, whether it wants to disconnect the line 277 * or continue the call as a voice only call. 278 * 279 * This is an asynchronous request. 280 * 281 * @param aContextData 282 * Optional opaque data that will be passed back to the user with the command response 283 * 284 * @returns A unique command id for asynchronous completion 285 **/ 286 OSCL_IMPORT_REF virtual PVCommandId Disconnect(OsclAny* aContextData = NULL) = 0; 287 288 /** 289 * This function returns the current state of the pv2way. 290 * Application may use this info for updating display or determine if the 291 * pv2way is ready for the next request. 292 * 293 * @param aState 294 * Reflects the state of the PV 2Way engine when the command was received. 295 * @param aContextData 296 * Optional opaque data that will be passed back to the user with the command response 297 * @returns value indicating the current pv2way state 298 **/ 299 OSCL_IMPORT_REF virtual PVCommandId GetState(PV2WayState& aState, 300 OsclAny* aContextData = NULL) = 0; 301 302 /** 303 * For an incoming track this function pauses sending media to the sink (output device) and stops the sink. 304 * 305 * For outgoing, it pauses the sending of media from the source and stops the source. 306 * 307 * @param aDirection Specifies the direction of the track - incoming or outgoing 308 * @param aTrackId Specifies which track is to be paused. 309 * @param aContextData 310 * Optional opaque data that will be passed back to the user with the command response 311 * 312 * @returns A unique command id for asynchronous completion 313 **/ 314 OSCL_IMPORT_REF virtual PVCommandId Pause(PV2WayDirection aDirection, 315 PVTrackId aTrackId, 316 OsclAny* aContextData = NULL) = 0; 317 318 /** 319 * Resume a previously paused incoming or outgoing track. For incoming, 320 * this function starts resumes playing out the media to the appropriate 321 * sink based on the current settings. For outgoing it resumes encoding 322 * and sending media from the source. 323 * 324 * @param aDirection Specifies the direction of the track - incoming or outgoing 325 * @param aTrackId Specifies which track is to be paused. 326 * @param aContextData 327 * Optional opaque data that will be passed back to the user with the command response 328 * 329 * @returns A unique command id for asynchronous completion 330 **/ 331 OSCL_IMPORT_REF virtual PVCommandId Resume(PV2WayDirection aDirection, 332 PVTrackId aTrackId, 333 OsclAny* aContextData = NULL) = 0; 334 335 336 /** 337 * Allows a logging appender to be attached at some point in the 338 * logger tag tree. The location in the tag tree is specified by the 339 * input tag string. A single appender can be attached multiple times in 340 * the tree, but it may result in duplicate copies of log messages if the 341 * appender is not attached in disjoint portions of the tree. 342 * A logging appender is responsible for actually writing the log message 343 * to its final location (e.g., memory, file, network, etc). 344 * This API can be called anytime after creation of the terminal. 345 * 346 * @param aTag Specifies the logger tree tag where the appender should be attached. 347 * @param aAppender The log appender to attach. 348 * @param aContextData 349 * Optional opaque data that will be passed back to the user with the command response 350 * 351 * @exception memory_error leaves on memory allocation error. 352 * 353 * @returns A unique command id for asynchronous completion 354 **/ 355 OSCL_IMPORT_REF virtual PVCommandId SetLogAppender(const char* aTag, 356 OsclSharedPtr<PVLoggerAppender>& aAppender, 357 OsclAny* aContextData = NULL) = 0; 358 359 360 /** 361 * Allows a logging appender to be removed from the logger tree at the 362 * point specified by the input tag. The input tag cannot be NULL. 363 * 364 * @param aTag Specifies the logger tree tag where the appender should be removed. 365 * @param aAppender The log appender to remove. Must be a reference to the same object that was set. 366 * @param aContextData 367 * Optional opaque data that will be passed back to the user with the command response 368 * 369 * @exception memory_error leaves on memory allocation error. 370 * 371 * @returns A unique command id for asynchronous completion 372 **/ 373 OSCL_IMPORT_REF virtual PVCommandId RemoveLogAppender(const char* aTag, 374 OsclSharedPtr<PVLoggerAppender>& aAppender, 375 OsclAny* aContextData = NULL) = 0; 376 377 378 /** 379 * Allows the logging level to be set for the logging node specified by the 380 * tag. A larger log level will result in more messages being logged. A message 381 * will only be logged if its level is LESS THAN or equal to the current log level. 382 * The set_subtree flag will allow an entire subtree, with the specified tag as the root, 383 * to be reset to the specified value. 384 * 385 * @param aTag Specifies the logger tree tag where the log level should be set. 386 * @param aLevel Specifies the log level to set. 387 * @param aSetSubtree Specifies whether the entire subtree with aTag as the root should 388 * be reset to the log level. 389 * @param aContextData 390 * Optional opaque data that will be passed back to the user with the command response 391 * 392 * @exception memory_error leaves on memory allocation error. 393 * 394 * @returns A unique command id for asynchronous completion 395 **/ 396 OSCL_IMPORT_REF virtual PVCommandId SetLogLevel(const char* aTag, 397 int32 aLevel, 398 bool aSetSubtree = false, 399 OsclAny* aContextData = NULL) = 0; 400 401 402 /** 403 * Allows the logging level to be queried for a particular logging tag. 404 * A larger log level will result in more messages being logged. 405 * 406 * In the asynchronous response, this should return the log level along with an 407 * indication of where the level was inherited (i.e., the ancestor tag). 408 * 409 * @param aTag Specifies the logger tree tag where the log level should be retrieved. 410 * @param aLogInfo an output parameter which will be filled in with the log level information. 411 * @param aContextData 412 * Optional opaque data that will be passed back to the user with the command response 413 * @exception memory_error leaves on memory allocation error. 414 * 415 * @returns A unique command id for asynchronous completion 416 **/ 417 OSCL_IMPORT_REF virtual PVCommandId GetLogLevel(const char* aTag, 418 int32& aLogInfo, 419 OsclAny* aContextData = NULL) = 0; 420 421 /** 422 * This API is to allow for extensibility of the pv2way interface. 423 * It allows a caller to ask for all UUIDs associated with a particular MIME type. 424 * If interfaces of the requested MIME type are found within the system, they are added 425 * to the UUIDs array. 426 * 427 * Also added to the UUIDs array will be all interfaces which have the requested MIME 428 * type as a base MIME type. This functionality can be turned off. 429 * 430 * @param aMimeType The MIME type of the desired interfaces 431 * @param aUuids An array to hold the discovered UUIDs 432 * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with aMimeType as a base type 433 * @param aContextData 434 * Optional opaque data that will be passed back to the user with the command response 435 **/ 436 OSCL_IMPORT_REF virtual PVCommandId QueryUUID(const PvmfMimeString& aMimeType, 437 Oscl_Vector<PVUuid, BasicAlloc>& aUuids, 438 bool aExactUuidsOnly = false, 439 OsclAny* aContextData = NULL) = 0; 440 441 /** 442 * This API is to allow for extensibility of the pv2way interface. 443 * It allows a caller to ask for an instance of a particular interface object to be returned. 444 * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with 445 * an interface ID that is a UUID as in DCE and a pointer to the interface object is 446 * returned if it is supported. Otherwise the returned pointer is NULL. 447 * TBD: Define the UIID, InterfacePtr structures 448 * @param aUuid The UUID of the desired interface 449 * @param aInterfacePtr The output pointer to the desired interface 450 * @exception not_supported 451 * leaves if the specified interface id is not supported. 452 **/ 453 OSCL_IMPORT_REF virtual PVCommandId QueryInterface(const PVUuid& aUuid, 454 PVInterface*& aInterfacePtr, 455 OsclAny* aContext = NULL) = 0; 456 457 /** 458 * This API is to allow the user to cancel all pending requests. The current request being 459 * processed, if any, will also be aborted. 460 * @param aContextData 461 * Optional opaque data that will be passed back to the user with the command response 462 * @returns A unique command id for asynchronous completion 463 **/ 464 OSCL_IMPORT_REF virtual PVCommandId CancelAllCommands(OsclAny* aContextData = NULL) = 0; 465}; 466 467 468 469#endif // 470 471 472