1 /*

     2 * Copyright (c) 2004 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:  Camera Application Engine interface for extensions

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CAEENGINEEXTINTERFACE_H

    21 #define CAEENGINEEXTINTERFACE_H

    22 

    23 //  INCLUDES

    24 

    25 #include <e32std.h>

    26 #include <fbs.h>

    27 #include <ecom/ecom.h>

    28 

    29 #include "CaeEngineExtInterface.hrh"

    30 

    31 // CONSTANTS

    32 

    33 // Common UID that identifies all Cae extensions

    34 const TUid KExtensionInterfaceUid = {KExtensionInterfaceUidValue};

    35 

    36 // Common string that identifies all Cae extensions

    37 _LIT8( KExtensionTypeStringDesc, KExtensionTypeString);

    38 

    39 // Global flags for extension handling. Affect how the engine handles extensions. 

    40 enum TCaeExtFlags

    41         {

    42         ECaeExtFlagRequireFullColorSnapInputImage =        0x00000001

    43         /* \todo Not yet implemented

    44         ECaeExtFlagRequireStillImageAsBitmap =             0x00000002,

    45         ECaeExtFlagRequireImageFormatHeader =              0x00000004

    46         */

    47         };

    48 

    49 

    50 // FORWARD DECLARATIONS

    51 

    52 class MExtensionCallbackInterface;

    53 class MExtension;

    54 

    55 

    56 // CLASS DECLARATIONS

    57 

    58 /**

    59 * Main extension interface class.	

    60 */

    61 

    62 class MExtension

    63 	{

    64 	public:

    65         /**

    66         * Create the extension. Create the object, get pointers to callback interfaces

    67 		* and possibly add extension interfaces to the engine.

    68         * @since 2.8

    69         * @param aImplementationUid The uid for ECom to find the correct dll that implements this extension

    70         * @param aEngine Pointer to the callback interface in the engine. Delivered to the extension.

    71         * @return MExtension Pointer to the extension. Returned to the engine.

    72         */

    73  		static MExtension* NewExtensionL( TUid aImplementationUid, MExtensionCallbackInterface* aEngine );

    74 

    75         /**

    76         * Virtual destructor. 

    77         * @since 2.8

    78         */

    79 		virtual ~MExtension() { REComSession::DestroyedImplementation (iDtor_ID_Key); };

    80 

    81 	private:

    82 

    83 		// The ID used by ECom for destroying this dll

    84 		TUid	iDtor_ID_Key;

    85 	};

    86 

    87 

    88 /**

    89 * Main callback interface implemented in the engine. The extension uses this

    90 * interface to add to and remove own interface implementations from the engine 

    91 * lists. Also, pointers to the callback interfaces implemented in the engine, 

    92 * can be fetched.  The extension usually calls this interface during creation. 

    93 */

    94 

    95 class MExtensionCallbackInterface

    96 	{

    97 	public:

    98         /**

    99         * Check that the interface is supported by the engine. 

   100         * @since 2.8

   101         * @param aInterfaceUid Uid for the interface.

   102         * @return TBool Whether the interface is supported.

   103         */

   104 		virtual TBool IsInterfaceSupported( TUid aInterfaceUid ) = 0;

   105 

   106         /**

   107         * Add an extension implemented interface to the list in engine. 

   108 		* The engine starts to call this interface.

   109         * @since 2.8

   110         * @param aInterfaceUid Uid for the interface.

   111         * @param aExtensionUid Uid for the extension that implements the interface.

   112         * @param aInterfacePtr Pointer to the interface implementation.

   113         * @param aPriority Priority of the interface. Interfaces with bigger priority value are called first.

   114         * @return TInt Error code.

   115         */

   116 		virtual TInt AddExtensionInterface( TUid aInterfaceUid, TUid aExtensionUid, TAny* aImplementationPtr, TInt aInitialPriority = 0 ) = 0;

   117 

   118         /**

   119         * Remove an extension implemented interface from the list in engine. 

   120 		* The engine stops calling this interface.

   121         * @since 2.8

   122         * @param aInterfaceUid Uid for the interface.

   123         * @param aInterfacePtr Pointer to the interface implementation.

   124         * @return TInt Error code.

   125         */

   126 		virtual TInt RemoveExtensionInterface( TUid aInterfaceUid, TAny* aImplementationPtr ) = 0;

   127 

   128         /**

   129         * Add an extension implemented custom interface to the list in engine. 

   130 		* The custom interface is not called by the engine. It is called by the application.

   131 		* The engine gives the pointer to the application when requested.

   132 		* Note that there is no remove method for a custom interface because there is not 

   133 		* specified a way to tell to the application when the interface had been removed.

   134         * @since 2.8

   135         * @param aInterfaceUid Specific uid for the interface.

   136         * @param aInterfacePtr Pointer to the interface implementation.

   137         * @return TInt Error code.

   138         */

   139 		virtual TInt AddCustomInterface( TUid aInterfaceUid, TAny* aImplementationPtr ) = 0;

   140 

   141         /**

   142         * Get an engine implemented callback interface. An extension can call this interface. 

   143         * @since 2.8

   144         * @param aInterfaceUid Specific uid for the interface.

   145         * @return TAny* Pointer to the callback interface.

   146         */

   147 		virtual TAny* GetCallbackInterface( TUid aInterfaceUid ) = 0;

   148 

   149         /**

   150         * Register flags which affect general extension handling in the engine. 

   151         * Flags must be deregisterd when no longer needed as they can affect

   152         * to the engine performance. Each registered flag must be deregistered, 

   153         * and only once. All the flags that are in registered state when 

   154         * the class is deleted, must be deregistered in the class destructor

   155         * method. 

   156         * @since 2.8

   157         * @param aFlags Flags to register.

   158         * @return void.

   159         */

   160 		virtual void RegisterFlags( TUint32 aFlags ) = 0;

   161 

   162         /**

   163         * Deregister flags which have been registered before. It is not allowed

   164         * to deregister flags that have not been registered earlier.  

   165         * @since 2.8

   166         * @param aFlags Flags to deregister.

   167         * @return void.

   168         */

   169 		virtual void DeregisterFlags( TUint32 aFlags ) = 0;

   170 	};

   171 

   172 

   173 /**

   174 * Image processing interface. The engine calls this interface when it gets 

   175 * a new view finder or captured image from the camera. The extension that 

   176 * implements this can manipulate the image before it is given to the 

   177 * application. 

   178 */

   179 

   180 const TInt KCaeExtProcessImageInterfaceUidValue = 0x101F856A;

   181 const TUid KCaeExtProcessImageInterfaceUid = { KCaeExtProcessImageInterfaceUidValue };

   182 

   183 class MCaeExtProcessImageInterface

   184 	{

   185 	public:

   186         /**

   187         * Process the view finder bitmap. 

   188         * @since 2.8

   189         * @param aFrame The VF frame bitmap.

   190         * @param aError Error code

   191         */

   192 		virtual void ProcessViewFinderFrame( CFbsBitmap& aFrame, TInt& aError ) = 0;

   193 

   194         /**

   195         * Process the captured image from the camera. The function can be synchronous or 

   196 		* asynchronous.

   197         * @since 2.8

   198         * @param aCaeStatus The status of the finished operation.

   199         * @param aBitmap The captured image, if it is a bitmap.

   200         * @param aImageData The captured image, if it is a formatted image.

   201         * @param aImageHeader The header of the captured image (e.g. Exif header).

   202         * @return TBool Whether the operation is asynchronous.

   203         */

   204 		virtual TBool ProcessCapturedImage( TRequestStatus& aCaeStatus, CFbsBitmap*& aBitmap, HBufC8*& aImageData, HBufC8*& aImageHeader ) = 0;

   205 		

   206         /**

   207         * Process the snap image. The function can be synchronous or asynchronous.

   208         * Modifications should be done on aSnapBitmap. If it is null the extension 

   209         * can create it using aStillBitmap as a source.

   210         * @since 2.8

   211         * @param aCaeStatus The status of the finished operation.

   212         * @param aBitmap The still image as a bitmap. Image can be NULL.

   213         * @param aSnapBitmap Returned snap bitmap. Image can be NULL.

   214         * @return TBool Whether the operation is asynchronous.

   215         */

   216 		virtual TBool ProcessSnapImage( TRequestStatus& aCaeStatus, CFbsBitmap*& aStillBitmap, CFbsBitmap*& aSnapBitmap ) = 0;

   217 		

   218         /**

   219         * Process the still image. The function can be synchronous or asynchronous.

   220         * @since 2.8

   221         * @param aCaeStatus The status of the finished operation.

   222         * @param aBitmap The still image, if it is a bitmap.

   223         * @param aImageData The still image, if it is a formatted image.

   224         * @param aImageHeader The header of the captured image (e.g. Exif header).

   225         * @return TBool Whether the operation is asynchronous.

   226         */

   227 		virtual TBool ProcessStillImage( TRequestStatus& aCaeStatus, CFbsBitmap*& aBitmap, HBufC8*& aImageData, HBufC8*& aImageHeader ) = 0;

   228 		

   229         /**

   230         * Cancel the asynchronous operation. 

   231         * @since 2.8

   232         */

   233 		virtual void CaeExtensionCancel() = 0;

   234 	};

   235 

   236 

   237 /**

   238 * Settings interface. The engine calls this when settings should be saved or 

   239 * restored. Note that not all settings type of exttensions need to implement this

   240 * interface.

   241 */

   242 

   243 const TInt KCaeExtSettingsInterfaceUidValue = 0x101F8569;

   244 const TUid KCaeExtSettingsInterfaceUid = { KCaeExtSettingsInterfaceUidValue };

   245 

   246 class MCaeExtSettingsInterface

   247 	{

   248 	public:

   249 

   250         /**

   251         * Restore previously saved settings.

   252         * @since 2.8

   253         */

   254 		virtual void ResetToPreviousSettingsL() = 0;				

   255 

   256         /**

   257         * Restore default settings.

   258         * @since 2.8

   259         */

   260 		virtual void ResetToDefaultsL() = 0;

   261 	};

   262 

   263 

   264 /**

   265 * Engine info interface. Implemented by the engine. The extension can get info 

   266 * about the current engine state.

   267 */

   268 

   269 const TInt KCaeExtEngineInfoCallbackInterfaceUidValue = 0x101F856B;

   270 const TUid KCaeExtEngineInfoCallbackInterfaceUid = { KCaeExtEngineInfoCallbackInterfaceUidValue };

   271 

   272 class MCaeExtEngineInfoCallbackInterface

   273     {

   274     public: 

   275         /**

   276         * Get current still image size. 

   277         * @since 2.8

   278         * @return TSize Still image size in pixels.

   279         */

   280 		virtual TSize McaeExtStillImageSize() = 0;

   281 

   282         /**

   283         * Get current snap image size. 

   284         * @since 2.8

   285         * @return TSize Snap image size in pixels.

   286         */

   287 		virtual TSize McaeExtSnapImageSize() = 0;

   288 

   289         /**

   290         * Get current view finder size. 

   291         * @since 2.8

   292         * @return TSize View finder size in pixels.

   293         */

   294 		virtual TSize McaeExtViewFinderSize() = 0;

   295 

   296         /**

   297         * Checks that the camera power is on. If it is not, the function leaves with 

   298 		* KErrNotReady.

   299         * @since 2.8

   300         * return void.

   301         */

   302 		virtual void McaeExtCheckPowerL() = 0;

   303 

   304         /**

   305         * Get display index. 

   306         * @since 2.8

   307         * @return TInt Display index.

   308         */

   309 		virtual TInt McaeExtDisplayIndex() = 0;

   310     };

   311 

   312 

   313 #endif // CAEENGINEEXTINTERFACE_H