| /* ------------------------------------------------------------------ |
| * 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. |
| * ------------------------------------------------------------------- |
| */ |
| /* |
| * ============================================================================== |
| * Name : pv_2way_interface.h |
| * Part of : |
| * Interface : |
| * Description : Interface class and supporting definitions for the PV2Way SDK |
| * Version : (see RELEASE field in copyright header above) |
| * |
| * ============================================================================== |
| */ |
| |
| #ifndef PV_2WAY_INTERFACE_H_INCLUDED |
| #define PV_2WAY_INTERFACE_H_INCLUDED |
| |
| |
| // INCLUDES |
| #ifndef PV_COMMON_TYPES_H_INCLUDED |
| #include "pv_common_types.h" |
| #endif |
| |
| #ifndef OSCL_VECTOR_H_INCLUDED |
| #include "oscl_vector.h" |
| #endif |
| |
| #ifndef PVT_COMMON_H_INCLUDED |
| #include "pvt_common.h" |
| #endif |
| |
| #ifndef PVMF_NODE_INTERFACE_H_INCLUDED |
| #include "pvmf_node_interface.h" |
| #endif |
| |
| #ifndef PVLOGGER_ACCESSORIES_H_INCLUDED |
| #include "pvlogger_accessories.h" |
| #endif |
| |
| #ifndef PV_ENGINE_TYPES_H_INCLUDED |
| #include "pv_engine_types.h" |
| #endif |
| |
| #ifndef PVT_2WAY_BASIC_TYPES_H_INCLUDED |
| #include "pv_2way_basic_types.h" |
| #endif |
| |
| #ifndef PV_2WAY_H324M_TYPES_H_INCLUDED |
| #include "pv_2way_h324m_types.h" |
| #endif |
| |
| |
| // CONSTANTS |
| |
| // DATA TYPES |
| |
| // CLASS DECLARATION |
| |
| /** |
| * CPV2WayInterface Class |
| * |
| * CPV2WayInterface is the interface to the pv2way SDK, which |
| * allows initialization, control, and termination of a two-way (3g-324m, SIP) terminal. |
| * The application is expected to contain and maintain a pointer to the |
| * CPV2WayInterface instance at all times that a call is active. |
| * The CPV2WayFactory factory class is to be used to create and |
| * delete instances of this class |
| **/ |
| class CPV2WayInterface |
| { |
| public: |
| /** |
| * Object destructor function |
| * Releases Resources prior to destruction |
| **/ |
| virtual ~CPV2WayInterface() {}; |
| |
| /** |
| * Returns version information about the SDK |
| * |
| * @param aSDKInfo |
| * A reference to a PVSDKInfo structure which contains the product label and date |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @leave This method can leave with one of the following error codes |
| * PVMFErrNoMemory if the SDK failed to allocate memory during this operation |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId GetSDKInfo(PVSDKInfo &aSDKInfo, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * Returns information about all modules currently used by the SDK. |
| * |
| * @param aSDKModuleInfo |
| * A reference to a PVSDKModuleInfo structure which contains the number of modules currently used by |
| * pv2way SDK and the PV UID and description string for each module. The PV UID and description string |
| * for modules will be returned in one string buffer allocated by the client. If the string buffer |
| * is not large enough to hold the all the module's information, the information will be written |
| * up to the length of the buffer and truncated. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @leave This method can leave with one of the following error codes |
| * PVMFErrNoMemory if the SDK failed to allocate memory during this operation |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId GetSDKModuleInfo(PVSDKModuleInfo &aSDKModuleInfo, |
| OsclAny* aContextData = NULL) = 0; |
| |
| |
| /** |
| * This function is valid only in the EIdle state. It is a no-op when |
| * invoked in any other state. It causes the pv2way to transition |
| * to the ESetup state. The terminal remains in the EInitializing state during |
| * the transition. |
| * |
| * While initializing, the pv2way tries to allocate system resources needed |
| * for a two-way call. If it fails for some reason, |
| * and the pv2way reverts to the EIdle state. All the resources are de-allocated. |
| * |
| * |
| * @param aInitInfo |
| * A reference to a CPV2WayInitInfo structure which contains the capabilities of the applications sinks |
| * and sources to handle compressed and uncompressed formats. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @leave This method can leave with one of the following error codes |
| * PVMFErrArgument if more tx and rx codecs are set than engine can handle, or the mandatory codecs are not in the list. |
| * PVMFErrNotSupported if the format of the sources/sinks is incomtible with what the SDK can handle |
| * PVMFErrInvalidState if invoked in the incorrect state |
| * PVMFErrNoMemory if the SDK failed to allocate memory during this operation |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId Init(PV2WayInitInfo& aInitInfo, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function is valid only in the ESetup and EInitializing state. It is a |
| * no-op when invoked in the EIdle state and returns PVMFErrInvalidState |
| * if invoked in any other state. |
| * |
| * It causes the pv2way to transition back to the EIdle state. The |
| * terminal remains in the EResetting state during the transition. |
| * |
| * While resetting, the pv2way de-allocates all resources resources that |
| * had been previously allocated. When it completes, ResetComplete is called |
| * and the pv2way reverts to the EIdle state. |
| * |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @leave This method can leave with one of the following error codes |
| * PVMFErrInvalidState if invoked in the incorrect state |
| * PVMFErrNoMemory if the SDK failed to allocate memory during this operation |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId Reset(OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function allows the user to specify the media source for an outgoing track. |
| * Sources should be added after the PVT_INDICATION_OUTGOING_TRACK is received which specifies the format type |
| * and the unique track id. The format type is indicated using the PV2WayTrackInfoInterface extension interface in the |
| * PVAsyncInformationalEvent. |
| * Data sources could be of the following types: |
| * a)raw media sources like camera, microphone etc. |
| * b)sources of compressed data like file, combined capture and encode devices. |
| * |
| * @param aTrackId |
| * The outgoing track id |
| * @param aDataSource |
| * Reference to the data source for this track |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @leave This method can leave with one of the following error codes |
| * PVMFErrNotSupported if the format of the sources/sinks is incomtible with what the SDK can handle |
| * KPVErrInvalidState if invoked in the incorrect state |
| * KErrNoMemory if the SDK failed to allocate memory during this operation |
| * @return A unique command id for asynchronous completion |
| */ |
| OSCL_IMPORT_REF virtual PVCommandId AddDataSource(PVTrackId aTrackId, |
| PVMFNodeInterface& aDataSource, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function unbinds a previously added source. |
| * |
| * @param aDataSource pointer to the media source node |
| * |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId RemoveDataSource(PVMFNodeInterface& aDataSource, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function allows the user to specify the media sink for an incoming track. |
| * AddDataSinkL can be called only for established incoming tracks identified by a unique |
| * track id. |
| * Incoming tracks are initiated by the peer and their establishment is indicated using the |
| * PVT_INDICATION_INCOMING_TRACK notification which provides the media type and a unique track id. |
| * The format type is indicated using the PV2WayTrackInfoInterface extension interface in the |
| * PVAsyncInformationalEvent. |
| * Data sinks could be of the following types: |
| * a)raw media sinks like video display sinks for RGB and YUV formats, audio rendering sinks for PCM. |
| * b)sources of compressed data like file, combined decode and render devices. |
| * |
| * |
| * @param aTrackId |
| * Indicates the unique track id to be associated with this sink. |
| * @param aDataSink The data sink to be added |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @return A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId AddDataSink(PVTrackId aTrackId, |
| PVMFNodeInterface& aDataSink, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function unbinds a previously added sink. |
| * |
| * @param aDataSink pointer to the media sink node |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId RemoveDataSink(PVMFNodeInterface& aDataSink, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function can be invoked only in the ESetup state. The terminal starts connecting with the remote |
| * terminal based on the specified options and capabilities. |
| * Incoming tracks may be opened before ConnectL completes and will be indicated via the |
| * PVT_INDICATION_INCOMING_TRACK event. |
| * |
| * @param aOptions |
| * Optional additional information for call setup. |
| * @param aCommServer |
| * An optional pointer to a comm server to provide comm source and sink end-points. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId Connect(const PV2WayConnectOptions& aOptions, |
| PVMFNodeInterface* aCommServer = NULL, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * The Disconnect call is valid only when invoked in the EConnecting, and |
| * EConnected states. It causes the terminal to transition to the |
| * EDisconnecting state. All the media tracks both incoming and outgoing |
| * will be closed on invoking Disconnect. On completion, the terminal |
| * goes to the ESetup state. The statistics of the previous call shall |
| * still be available until Connect is invoked again. |
| * |
| * It is a no-op when called in any other state. |
| * |
| * The post disconnect option specifies what this terminal wishes to do |
| * after the data call is terminated, whether it wants to disconnect the line |
| * or continue the call as a voice only call. |
| * |
| * This is an asynchronous request. |
| * |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId Disconnect(OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This function returns the current state of the pv2way. |
| * Application may use this info for updating display or determine if the |
| * pv2way is ready for the next request. |
| * |
| * @param aState |
| * Reflects the state of the PV 2Way engine when the command was received. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @returns value indicating the current pv2way state |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId GetState(PV2WayState& aState, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * For an incoming track this function pauses sending media to the sink (output device) and stops the sink. |
| * |
| * For outgoing, it pauses the sending of media from the source and stops the source. |
| * |
| * @param aDirection Specifies the direction of the track - incoming or outgoing |
| * @param aTrackId Specifies which track is to be paused. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId Pause(PV2WayDirection aDirection, |
| PVTrackId aTrackId, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * Resume a previously paused incoming or outgoing track. For incoming, |
| * this function starts resumes playing out the media to the appropriate |
| * sink based on the current settings. For outgoing it resumes encoding |
| * and sending media from the source. |
| * |
| * @param aDirection Specifies the direction of the track - incoming or outgoing |
| * @param aTrackId Specifies which track is to be paused. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId Resume(PV2WayDirection aDirection, |
| PVTrackId aTrackId, |
| OsclAny* aContextData = NULL) = 0; |
| |
| |
| /** |
| * Allows a logging appender to be attached at some point in the |
| * logger tag tree. The location in the tag tree is specified by the |
| * input tag string. A single appender can be attached multiple times in |
| * the tree, but it may result in duplicate copies of log messages if the |
| * appender is not attached in disjoint portions of the tree. |
| * A logging appender is responsible for actually writing the log message |
| * to its final location (e.g., memory, file, network, etc). |
| * This API can be called anytime after creation of the terminal. |
| * |
| * @param aTag Specifies the logger tree tag where the appender should be attached. |
| * @param aAppender The log appender to attach. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @exception memory_error leaves on memory allocation error. |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId SetLogAppender(const char* aTag, |
| OsclSharedPtr<PVLoggerAppender>& aAppender, |
| OsclAny* aContextData = NULL) = 0; |
| |
| |
| /** |
| * Allows a logging appender to be removed from the logger tree at the |
| * point specified by the input tag. The input tag cannot be NULL. |
| * |
| * @param aTag Specifies the logger tree tag where the appender should be removed. |
| * @param aAppender The log appender to remove. Must be a reference to the same object that was set. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @exception memory_error leaves on memory allocation error. |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId RemoveLogAppender(const char* aTag, |
| OsclSharedPtr<PVLoggerAppender>& aAppender, |
| OsclAny* aContextData = NULL) = 0; |
| |
| |
| /** |
| * Allows the logging level to be set for the logging node specified by the |
| * tag. A larger log level will result in more messages being logged. A message |
| * will only be logged if its level is LESS THAN or equal to the current log level. |
| * The set_subtree flag will allow an entire subtree, with the specified tag as the root, |
| * to be reset to the specified value. |
| * |
| * @param aTag Specifies the logger tree tag where the log level should be set. |
| * @param aLevel Specifies the log level to set. |
| * @param aSetSubtree Specifies whether the entire subtree with aTag as the root should |
| * be reset to the log level. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * |
| * @exception memory_error leaves on memory allocation error. |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId SetLogLevel(const char* aTag, |
| int32 aLevel, |
| bool aSetSubtree = false, |
| OsclAny* aContextData = NULL) = 0; |
| |
| |
| /** |
| * Allows the logging level to be queried for a particular logging tag. |
| * A larger log level will result in more messages being logged. |
| * |
| * In the asynchronous response, this should return the log level along with an |
| * indication of where the level was inherited (i.e., the ancestor tag). |
| * |
| * @param aTag Specifies the logger tree tag where the log level should be retrieved. |
| * @param aLogInfo an output parameter which will be filled in with the log level information. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @exception memory_error leaves on memory allocation error. |
| * |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId GetLogLevel(const char* aTag, |
| int32& aLogInfo, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This API is to allow for extensibility of the pv2way interface. |
| * It allows a caller to ask for all UUIDs associated with a particular MIME type. |
| * If interfaces of the requested MIME type are found within the system, they are added |
| * to the UUIDs array. |
| * |
| * Also added to the UUIDs array will be all interfaces which have the requested MIME |
| * type as a base MIME type. This functionality can be turned off. |
| * |
| * @param aMimeType The MIME type of the desired interfaces |
| * @param aUuids An array to hold the discovered UUIDs |
| * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with aMimeType as a base type |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId QueryUUID(const PvmfMimeString& aMimeType, |
| Oscl_Vector<PVUuid, BasicAlloc>& aUuids, |
| bool aExactUuidsOnly = false, |
| OsclAny* aContextData = NULL) = 0; |
| |
| /** |
| * This API is to allow for extensibility of the pv2way interface. |
| * It allows a caller to ask for an instance of a particular interface object to be returned. |
| * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with |
| * an interface ID that is a UUID as in DCE and a pointer to the interface object is |
| * returned if it is supported. Otherwise the returned pointer is NULL. |
| * TBD: Define the UIID, InterfacePtr structures |
| * @param aUuid The UUID of the desired interface |
| * @param aInterfacePtr The output pointer to the desired interface |
| * @exception not_supported |
| * leaves if the specified interface id is not supported. |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId QueryInterface(const PVUuid& aUuid, |
| PVInterface*& aInterfacePtr, |
| OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * This API is to allow the user to cancel all pending requests. The current request being |
| * processed, if any, will also be aborted. |
| * @param aContextData |
| * Optional opaque data that will be passed back to the user with the command response |
| * @returns A unique command id for asynchronous completion |
| **/ |
| OSCL_IMPORT_REF virtual PVCommandId CancelAllCommands(OsclAny* aContextData = NULL) = 0; |
| }; |
| |
| |
| |
| #endif // |
| |
| |
