contacts_plat/phonebook_2_contact_related_icon_customization_api/inc/CContactCustomIconPluginBase.h
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contacts_plat/phonebook_2_contact_related_icon_customization_api/inc/CContactCustomIconPluginBase.h Mon Mar 15 12:39:26 2010 +0200
@@ -0,0 +1,296 @@
+/*
+* Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Defines an ECOM interface for third parties to customize
+* contact related icons in certain platform applications.
+*/
+
+#ifndef CCONTACTICONCUSTOMPLUGINBASE_H
+#define CCONTACTICONCUSTOMPLUGINBASE_H
+
+// INCLUDES
+#include <e32base.h>
+#include <ecom\ecom.h>
+#include <ContactCustomIconPluginDefs.h>
+
+// FORWARD DECLARATIONS
+class CGulIcon;
+class CCustomIconIdMap;
+class CCustomIconDecisionData;
+class MCustomIconChangeObserver;
+
+// CONSTANTS
+
+/**
+* Interface UID for ECOM plug-ins, which inherit from this interface.
+* This is used in plug-in registration resource file (interface_uid). Example:
+*
+* RESOURCE REGISTRY_INFO cs_ecom_reg_info
+* {
+* dll_uid = <UID_OF_ECOM_DLL>;
+* interfaces =
+* {
+* INTERFACE_INFO
+* {
+* // Make sure to use KContactIconCustomizationInterfaceUidValue
+* interface_uid = 0x2001E2DA;
+*
+* implementations =
+* {
+* IMPLEMENTATION_INFO
+* {
+* implementation_uid = <...>; // maps to IMPLEMENTATION_PROXY_ENTRY in CPP exporting plugin factory functions
+* version_no = 1;
+* display_name = "CMyContactIconCustomizationPlugin";
+* default_data = "";
+* opaque_data = "";
+* }
+* };
+* }
+* };
+* }
+*/
+const TInt KContactIconCustomizationInterfaceUidValue = 0x2001E2DA;
+const TUid KContactIconCustomizationInterfaceUid =
+ { KContactIconCustomizationInterfaceUidValue };
+
+
+// CLASS DECLARATION
+
+/**
+* Base class for contact related icon customization ECOM plugins.
+*
+* This API allows customizing contact related icons of certain
+* applications at runtime.
+*
+* The API defines two roles:
+* - Customizable entity is typically an application supporting icon
+* customization. It is a caller of this API.
+* - Customizer is an entity implementing ecom plug-in, a callee.
+*
+* As a concrete example, Logs application has 'Dialled calls' view
+* where it by default shows in each listbox row a call specific icon.
+* Plugin can change each of the icons by implementing this API.
+*
+* The customizer needs only one plug-in implementation, which affects
+* multiple applications at a same time. This means the API cannot define
+* application specific info.
+*
+* Note that customizable entity - typically an application - has to provide
+* a connection to Font and Bitmap server. The plug-in may fail to provide
+* the icon (KErrCouldNotConnect), if the connection does not exist.
+*/
+class CContactCustomIconPluginBase : public CBase
+ {
+ public: // API to be implemented by ECOM plug-in
+
+ /**
+ * An icon size hint from application to plug-in. Plug-in
+ * may use this to load icons of appropriate size.
+ * @see IconsL
+ */
+ enum TIconSizeHint
+ {
+ EReallySmall,
+ ESmall,
+ EMedium,
+ EMediumLarge,
+ ELarge
+ };
+
+ /**
+ * Calling application uses this method to register itself as an observer
+ * for the plug-in state change notifications.
+ *
+ * Plug-in uses observer interface for notifying calling application
+ * about icon related changes.
+ *
+ * @param aObserver Observer interface, implemented by calling client
+ * code. Ownership of the object is not transferred.
+ */
+ virtual void AddObserverL(
+ MCustomIconChangeObserver* aObserver ) = 0;
+
+ /**
+ * Calling application uses this method to deregister itself as an observer
+ * from the plug-in state change notifications.
+ *
+ * @param aObserver Observer interface, implemented by calling client
+ * code. Ownership of the object is not transferred.
+ */
+ virtual void RemoveObserver(
+ MCustomIconChangeObserver* aObserver ) = 0;
+
+ /**
+ * Gets an array of custom icons from the plug-in.
+ *
+ * Application calls this method typically in its initialization phase
+ * to prepare for replacing its default icons. When it is time to show
+ * the icons, calling application may call IconChoiceL.
+ *
+ * ECOM plug-in implementation should fill in the potential icons
+ * and give each icon an identifier, which it can use later to refer
+ * to a certain icon it wants to use as replacement for application's
+ * default icon.
+ *
+ * @see CCustomIconIdMap.h
+ * @param aContext Context of the function call. For more information
+ * about context semantics see CCustomIconDecisionData
+ * documentation.
+ * @param aSizeHint Hint for plug-in to load icons of appropriate size.
+ * @return Icon-to-id map.
+ * @leave On typical leave level problems. Application should handle
+ * this by ignoring ECOM plug-in functionality and continue
+ * using its default icons.
+ */
+ virtual CCustomIconIdMap* IconsL(
+ TUid aContext,
+ TIconSizeHint aSizeHint ) = 0;
+
+ /**
+ * Application uses this method to make a choice of the icon to be
+ * displayed in certain UI condition.
+ *
+ * Note that application should have always had called the IconsL
+ * function before this gets called.
+ *
+ * ECOM plug-in implementation should use aHint parameter to make a decision
+ * which icon it wants to use.
+ *
+ * @param aHint Hint from the application to the plug-in, which tells
+ * what kind of icon is being replaced. For example, the
+ * plug-in may want to choose the icon based on the
+ * phonenumber. For more details see
+ * CCustomIconDecisionData.h.
+ * Plug-in must not take ownership of the object's
+ * members. The instance and its members are guaranteed to
+ * be valid only during the method call.
+ *
+ * Caller must fill at least one of the members, otherwise
+ * plug-in can and should leave with KErrArgument.
+ *
+ * @param aIdResult Icon reference value filled by the ECOM plug-in. The id
+ * should be one of the ids, which were used to build the
+ * CCustomIconIdMap object in IconsL function. If the
+ * calling application cannot find an icon by aIdResult
+ * from the map, it should use application's default icon.
+ *
+ * @return Return value indicating if the decision could be made.
+ * ETrue, if the icon choice decision could be made.
+ * EFalse, if the icon choice could not be made.
+ * This is an indication from plug-in to application that
+ * application should use its default icon.
+ *
+ * @leave On typical leave level problems like database access failure
+ * or condition where application may not be able to provide the
+ * requested functionality. It is up to application how it
+ * handles leave from the plug-in. Recommendation is that it
+ * ignores plug-in's functionality and uses default icons.
+ */
+ virtual TBool IconChoiceL(
+ const CCustomIconDecisionData& aHint,
+ TCustomIconId& aIdResult ) = 0;
+
+ /**
+ * Application uses this method when it dynamically needs to replace
+ * its default icon. This can typically happen at any time of the
+ * application runtime.
+ *
+ * Application should favor using the IconsL/IconChoiceL pair, if it
+ * is likely to use multiple icons and several times. This function is
+ * useful if the application needs only couple of icons only couple
+ * of times. This is discouraged for use in frequent draw requests.
+ *
+ * The plug-in implementation should use the aHint to make a decision
+ * which icon it wants to use.
+ *
+ * @param aHint Hint from application to plug-in, which tells what
+ * kind of icon is being replaced. For example, the
+ * plug-in may want to choose the icon based on the
+ * phonenumber. For more details see
+ * CCustomIconDecisionData.h
+ * Plug-in must not take ownership of the object or its
+ * members. The instance and its members are guaranteed to
+ * be valid only during the method call.
+ * Caller must fill at least one of the members, otherwise
+ * plug-in can and should leave with KErrArgument.
+ *
+ * @param aSizeHint Hint for plug-in to load icon of appropriate size.
+ *
+ * @return Icon instance. NULL, if plug-in wants to indicate it is
+ * not willing to replace caller's default icon.
+ */
+ virtual CGulIcon* IconL(
+ const CCustomIconDecisionData& aHint,
+ TIconSizeHint aSizeHint ) = 0;
+
+ /**
+ * Application uses this method when it dynamically needs to update
+ * previously loaded custom icon. Typically this happens after
+ * application has received update notification from plug-in.
+ *
+ * @param aContext Context of the function call. While this override
+ * provides known icon id rather than
+ * CCustomIconDecisionData, the context is given here
+ * separately. For more information about context
+ * semantics see CCustomIconDecisionData
+ * documentation.
+ *
+ * @param aIconId Specifies the icon for the client to provide. This is
+ * valid when a known custom icon has changed and is
+ * being replaced.
+ *
+ * @param aSizeHint Hint for plug-in to load icon of appropriate size.
+ *
+ * @return Icon instance. NULL, if plug-in wants to indicate it is
+ * not willing to replace application's default icon.
+ */
+ virtual CGulIcon* IconL(
+ TUid aContext,
+ TCustomIconId aIconId,
+ TIconSizeHint aSizeHint ) = 0;
+
+ /**
+ * Factory function for getting access to extended API functionality.
+ * Uid defines the extension interface being used.
+ *
+ * @param aExtensionUid Identifier for extension API class.
+ * @return Extension API class, casted to one of M-interfaces defined
+ * by this API (later). Ownership of the object is not transferred.
+ */
+ virtual TAny* ContactCustomIconExtension( TUid /*aExtensionUid*/ )
+ {
+ return NULL;
+ }
+
+ public:
+
+ /**
+ * ~CContactIconCustomPluginBase
+ *
+ * Cleans up resources, specifically notify ECOM server that this
+ * instance is being deleted.
+ */
+ inline virtual ~CContactCustomIconPluginBase()
+ {
+ REComSession::DestroyedImplementation( iDtorKey );
+ }
+
+ public:
+ /// Own: Key UID
+ TUid iDtorKey;
+ };
+
+#endif // CCONTACTICONCUSTOMPLUGINBASE_H
+
+// End of File