1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CCP ECOM interface main class.

    15 *

    16 */

    17 

    18 

    19 #ifndef CCONVERGEDCALLPROVIDER_H

    20 #define CCONVERGEDCALLPROVIDER_H

    21 

    22 //  INCLUDES

    23 #include <ecom/ecom.h>

    24 #include <e32base.h>

    25 #include <e32std.h>

    26 #include <e32def.h>

    27 #include <badesca.h>

    28 

    29 #include <ccpdefs.h>

    30 #include <mccpcall.h>

    31 

    32 // FORWARD DECLARATIONS

    33 class MCCPCallObserver;

    34 class MCCPObserver;

    35 class MCCPSsObserver;

    36 

    37 class MCCPEmergencyCall;

    38 class MCCPConferenceCall;

    39 class MCCPConferenceCallObserver;

    40 

    41 class MCCPDTMFProvider;

    42 class MCCPDTMFObserver;

    43 

    44 class MCCPExtensionProvider;

    45 class MCCPExtensionObserver;

    46 

    47 /**

    48 * Converged Call Provider API - main header.

    49 * Main class in CCP. Used e.g. to create calls, access provider classes.

    50 * MCCPObserver class is used for notifying error, state etc information.

    51 *

    52 *  @since S60 3.2

    53 */

    54 class CConvergedCallProvider : public CBase

    55     {

    56 public: 

    57     /**

    58     * Returns CCP API plug-in implementation identified by given UID.

    59     * @since S60 3.2

    60     * @param aImplementationUid CCP API interface implementation UID

    61     * @return Plug-in implementation pointer returned by ECOM framework.

    62     * @leave KErrNotFound If ECOM plug-in implementation is not found.

    63     * @leave KErrNoPermission If ECOM plug-in does not have required capabilities.

    64     * @leave Any other symbian ECOM leave code.

    65     */

    66     static CConvergedCallProvider* NewL(const TUid& aImplementationUid);

    67 

    68     /**

    69     * Destructor. Destroys the plug-in via ecom framework using iDtor_ID_Key

    70     * @since S60 3.2

    71     * @param None

    72     * @return None

    73     */

    74     virtual ~CConvergedCallProvider();

    75 

    76     /**

    77     * Lists all implementations for this interface.

    78     * @since S60 3.2

    79     * @param aImplementations Array containing pointers to all implementations

    80     * for this interface

    81     * @return None

    82     */

    83     static void ListImplementationsL(RImplInfoPtrArray& aImplementations);

    84 

    85 protected:

    86     /**

    87     * @since S60 3.2

    88     * @param None

    89     * @return None

    90     */

    91     inline CConvergedCallProvider();

    92 

    93  

    94 public: // API functions

    95     

    96     /**

    97     * Initialize CConvergedCallProvider after it is created with NewL.

    98     * @since S60 3.2

    99     * @param aServiceId service id used by convergedcallprovider

   100     * @param aObserver Observer class.

   101     * @param aSsObserver Supplementary services observer class.

   102     * @leave KErrAlreadyExists If this method has already been called.

   103     */

   104     virtual void InitializeL( const TUint32 aServiceId,

   105                               const MCCPObserver& aObserver, 

   106     						  const MCCPSsObserver& aSsObserver );

   107 

   108     /**

   109     * Initialize CConvergedCallProvider after it is created with NewL.

   110     * @since S60 3.2

   111     * @param aObserver Observer class.

   112     * @param aSsObserver Supplementary services observer class.

   113     * @leave KErrAlreadyExists If this method has already been called.

   114     */

   115     virtual void InitializeL( const MCCPObserver& aObserver, 

   116     						  const MCCPSsObserver& aSsObserver ) = 0;

   117 

   118     /**

   119     * Creates a new call.

   120     * @since S60 3.2

   121     * @param aParameters Call paramaters such as servive-id used and call type.

   122     * @param aRecipient Recipients address/number.

   123     * @param aObserver Observer for the created call.

   124     * @return MCCPCall Always returns a call pointer if no error occurs.

   125     * @leave KErrAlreadyExists Call already exists.

   126     * @leave KErrNotReady Temporarily not able to create the requested call. E.g. maximum 

   127     * supported number of calls already exists (CCE will not call this if the global limit 

   128     * of calls is reached, this refers to plug-in own call count limit). 

   129     * @leave KErrNoMemory Memory error.

   130     * @leave KErrNotSupported Call not supported.

   131     * @leave KErrArgument Invalid recipient address or service id.

   132     * @leave Other general system error.

   133     * @pre Initialize has been called.

   134     */ 

   135     virtual MCCPCall* NewCallL( const CCCPCallParameters& aParameters,

   136 								const TDesC& aRecipient,

   137 								const MCCPCallObserver& aObserver ) = 0;

   138     /**

   139     * Releases all bindings to call and deletes it. 

   140     * This will be called by CCE to free all the resources reserved for the call.

   141     * After this call CCE will not access the call object anymore and observer 

   142     * for the class must not be used in plug-in.

   143     * This operation must always succeed. If plug-in decides to pre-allocate the 

   144     * call object it can choose to do so, but plug-in has to make sure call is 

   145     * returned to the state it was before calling CConvergedCallProvider::NewCallL.

   146     * @param aCalltoRemove Call to remove.

   147     * @return KErrNone if succesfull.

   148     * @return KErrNotFound if removed call is not found.

   149     * @pre None, can always be called.

   150     * @post Plug-in must quarantee all resources for the call will be cleaned up 

   151     * and plug-in must not call observer after this call!

   152     * @since S60 3.2

   153     */

   154     virtual TInt ReleaseCall( MCCPCall& aCalltoRemove ) = 0;

   155 

   156     /**

   157     * Creates a new emergency call.

   158     * @since S60 3.2

   159     * @param aServiceId Service-Id (this might get removed)

   160     * @param aAddress Address where emergency call is to be made

   161     * Can be KNullDesC. Plug-in will use the given address and/or use its own information.

   162     * @param aObserver Observer for the emergency call.

   163     * @return MCCPEmergencyCall Created emergency call.

   164 	* @leave plug-in does not support emergency calls.

   165 	* @leave In case of failure system error code.

   166     * @pre Emergency call object is created.

   167     */

   168     virtual MCCPEmergencyCall* NewEmergencyCallL( const TUint32 aServiceId, 

   169                                                   const TDesC& aAddress,

   170                                                   const MCCPCallObserver& aObserver ) = 0;

   171     /**

   172     * Releases all bindings to call and deletes it. 

   173     * This must be called to free all the resources reserved for the call.

   174     * After this call CCE must not be access the call object anymore and observer 

   175     * for the class must not be used in plug-in.

   176     * This operation mustways succeed. If plug-in decides to pre-allocate the 

   177     * call object it can choose to do so, but client has to be sure call is 

   178     * cleared from the plug-in and all resuorces are returned to the state before calling 

   179     * CConvergedCallProvider::NewEmergencyCallL.

   180     * @param aCalltoRemove Call to remove.

   181     * @return KErrNone if succesfull.

   182     * @return KErrNotFound if removed call is not found.

   183     * @pre None, can always be called.

   184     * @post Plug-in must quarantee all resources for the call will be cleaned up. Call must not 

   185     * be referenced anymore from CCE and plug-in must not call observer after this call!

   186     * @since S60 3.2

   187     */

   188     virtual TInt ReleaseEmergencyCall( MCCPEmergencyCall& aCalltoRemove ) = 0;

   189 

   190     /**

   191     * Creates a new conference call.

   192     * @since S60 3.2

   193     * @param aServiceId Servive id used.

   194     * @param aObserver Conference call observer.

   195     * @return MCCPConferenceCall object.

   196     * @leave KErrNotReady Temporarily not able to create the requested conference.

   197     * @leave KErrNoMemory Memory error.

   198     * @leave KErrArgument Invalid service id.

   199 	* @leave plug-in does not support conference calls.

   200     * @pre Initialize has been called.

   201     */

   202     virtual MCCPConferenceCall* NewConferenceL( const TUint32 aServiceId,

   203 								                const MCCPConferenceCallObserver& aObserver ) = 0;

   204 

   205     /**

   206     * Releases all bindings to conference call. CCE will call this after receiving 

   207     * MCCPConferenceCallObserver::ECCPConferenceIdle from plug-in or when it itself 

   208     * wants to release the call. In normal sequence called from CCE after HangUp is completed.

   209     * @param aCalltoRemove Call to remove.

   210     * @return KErrNone if succesfull.

   211     * @return KErrNotFound if removed call is not found.

   212     * @pre None, can always be called.

   213     * @post Plug-in must quarantee all resources for the call will be cleaned up. Call must not 

   214     * be referenced anymore from CCE and plug-in must not call observer after this call!

   215     * @since S60 3.2

   216     */

   217     virtual TInt ReleaseConferenceCall( MCCPConferenceCall& aCalltoRemove ) = 0;

   218 

   219     /**

   220     * Returns the plug-in UID.

   221     * @since S60 3.2

   222     * @param None.

   223     * @return Plug-in UID.

   224     */

   225     virtual const TUid& Uid() const = 0;

   226 

   227     /**

   228     * Get plug-in capabilities.

   229     * @since Series 60 3.2

   230     * @param None

   231     * @return On return contains the capability flags of plug-In.

   232     */

   233     virtual TUint32 Caps() const = 0;

   234 

   235     /**

   236 	* Request DTMF provider for dtmf functionality extension. Only one instance exist. Must return the 

   237 	* already created object if called again after initial creation.

   238     * @since Series 60 3.2

   239     * @param aObserver Observer for DTMF events.

   240 	* @return Pointer to MCCPDTMFProvider if plug-in support dtmf, returns NULL if not supported.

   241 	* In not supported return NULL but do not leave.

   242     * @pre Initialize has been called.

   243     * @leave KErrNoMemory Memory allocation error.

   244     * @leave Other general system error.

   245 	*/

   246 	virtual MCCPDTMFProvider* DTMFProviderL( const MCCPDTMFObserver& aObserver ) = 0;

   247 

   248 	/**

   249 	* Request extension provider for custom command handling features. Must return the 

   250 	* already created object if called again after initial creation.

   251 	* @since Series 60 3.2

   252     * @param aObserver observer for extension(custom) events.

   253 	* @return Pointer to MCCPExtensionProvider if plug-in support extensions, returns NULL if not supported.

   254 	* In not supported return NULL but do not leave.

   255     * @pre Initialize has been called.

   256     * @leave KErrNoMemory Memory allocation error.

   257     * @leave Other general system error.

   258 	*/

   259 	virtual MCCPExtensionProvider* ExtensionProviderL( const MCCPExtensionObserver& aObserver ) = 0;

   260 

   261 	/**

   262 	* This method gets the lifetime of the MS. The lifetime information 

   263 	* includes the manufacturing date of the MS and the total amount of airtime use, 

   264 	* from the manufacturing date until the call to this method. Calling this method 

   265 	* does not reset any data. This is used only CS, other plug-ins may ignore this method.

   266 	* @since S60 3.2

   267 	* @param aLifeTimeInfo Life time information

   268 	* @return Get succeeded or not.  Default if not implemeted return false. 

   269 	*/

   270 	virtual TBool GetLifeTime( TDes8& /*aLifeTimeInfo*/ ) { return EFalse; };

   271 

   272 	/**

   273 	* This method gets cs specific information from cs-plugin. This is used only CS, 

   274 	* other plug-ins may ignore this method.

   275 	* @since S60 3.2

   276 	* @param aCSInfo CS specific information from cs-plugin.

   277 	* @return Get succeeded or not. Default if not implemeted return false.

   278 	*/

   279 	virtual TBool GetCSInfo( CSInfo& /*aCSInfo*/ )  {  return EFalse; };

   280 

   281 private: // Data

   282 

   283     // ECom indentifier key.

   284     TUid iDtor_ID_Key;

   285     };

   286 

   287 #include <cconvergedcallprovider.inl>

   288 

   289 #endif // CCONVERGEDCALLPROVIDER_H

   290 

   291 // End of File