inc/FShellAppWidgetProviderManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file     FShellAppWidgetProviderManager.h
  20  * @brief    This is the header file for the %AppWidgetProviderManager class.
  21  *
  22  * This header file contains the declarations of the %AppWidgetProviderManager class.
  23  */
  24
  25 #ifndef _FSHELL_APPWIDGET_PROVIDER_MANAGER_H_
  26 #define _FSHELL_APPWIDGET_PROVIDER_MANAGER_H_
  27
  28 #include <unique_ptr.h>
  29 #include <FBaseString.h>
  30 #include <FAppTypes.h>
  31
  32 namespace Tizen { namespace Base { namespace Collection { class IList; } } }
  33 namespace Tizen { namespace Shell
  34 {
  35
  36 class IAppWidgetProviderFactory;
  37 class IAppWidgetPopupProviderFactory;
  38
  39 /**
  40  * @class               AppWidgetProviderManager
  41  * @brief               This class manages all the AppWidget providers.
  42  *
  43  * @since       2.1
  44  *
  45  * @final               This class is not intended for extension.
  46  *
  47  * The %AppWidgetProviderManager class manages all the AppWidget providers.
  48  * The AppWidget manager manages static and run time AppWidget information.
  49  */
  50 class _OSP_EXPORT_ AppWidgetProviderManager
  51         : public Tizen::Base::Object
  52 {
  53 public:
  54
  55         /**
  56          * Gets the AppWidget manager instance.
  57          *
  58          * @since       2.1
  59          *
  60          * @return      A pointer to the %AppWidgetProviderManager instance, @n
  61          *                      else @c null if it fails
  62          */
  63         static AppWidgetProviderManager* GetInstance(void);
  64
  65         /**
  66          * Requests AppWidget service to trigger the specified AppWidget update.
  67          *
  68          * @since       2.1
  69          *
  70          * @param[in]   appId                   The appId that provides AppWidget
  71          * @param[in]   providerName    The name of the AppWidget provider
  72          * @param[in]   userInfo                User information for the AppWidget provider @n
  73          *                                                              This parameter will be delivered as parameter of AppWidgetProvider::OnAppWidgetProviderUpdating().
  74          *
  75          * @exception   E_SUCCESS                       The method is successful.
  76          * @exception   E_APP_NOT_INSTALLED     The application is not installed.
  77          * @exception   E_OBJ_NOT_FOUND         The specified AppWidget provider is not found.
  78          * @exception   E_CERTIFICATE_VERIFICATION_FAILED       The application is not permitted to request to update AppWidget of other application package. @n
  79          *                                                                      To get permission, the target application is signed with the same certificate.
  80          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  81          *
  82          * @see                 AppWidgetProvider::OnAppWidgetProviderUpdating()
  83          */
  84         result RequestUpdate(const Tizen::App::AppId& appId, const Tizen::Base::String& providerName, const Tizen::Base::String& userInfo = L"");
  85
  86         /**
  87          * Requests a AppWidget viewer (for example, Home screen, Lock screen) to add the specified AppWidget.
  88          *
  89          * @since       2.1
  90          * @privlevel   public
  91          * @privilege   %http://tizen.org/privilege/appwidgetprovider.install
  92          *
  93          * @param[in]   providerAppId   The ID of the application providing AppWidget
  94          * @param[in]   providerName    The name of AppWidget provider to add
  95          * @param[in]   alternateText   Alternate text displayed in the AppWidgetView while the AppWidgetProvider is initializing or unavailable.
  96          * @param[in]   userInfo                User information for the AppWidget provider
  97          *
  98          * @exception   E_SUCCESS                       The method is successful.
  99          * @exception   E_APP_NOT_INSTALLED     The application is not installed.
 100          * @exception   E_OBJ_NOT_FOUND The specified AppWidget provider is not found.
 101          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 102          * @exception   E_CERTIFICATE_VERIFICATION_FAILED       The application is not permitted to request to add AppWidget of other application package. @n
 103          *                                                                      To get permission, the target application is signed with the same certificate.
 104          * @exception   E_UNSUPPORTED_OPERATION The specified AppWidget provider does not support this operation. @n
 105          *                                                                              To request a AppWidget viewer to add a AppWidget, AppWidget provider should support 1x1 size AppWidget, but the specified AppWidget provider does not support 1x1 size.
 106          * @exception   E_CONNECTION_FAILED     The viewer application does not set a listener to receive this request.
 107          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 108          *
 109          * @remarks     Only AppWidget provider that is packaged with the caller application can be added by this method.
 110          * @see         AppWidgetManager::SetAppWidgetRequestListener()
 111          */
 112         result AddAppWidget(const Tizen::App::AppId& providerAppId, const Tizen::Base::String& providerName, const Tizen::Base::String& alternateText, const Tizen::Base::String& userInfo);
 113
 114         /**
 115          * Sets a AppWidgetProvider factory. @n
 116          * The factory is called when AppWidgetProvider needs to be created.
 117          * The %SetAppWidgetProviderFactory() method should be called in App::OnAppInitializing(), to receive the event correctly.
 118          * Implementing AppWidgetProviderFactory is mandatory to provide AppWidget functionality.
 119          *
 120          * @since       2.1
 121          *
 122          * @return      An error code
 123          * @param[in]   factory         The factory to create concrete AppWidgetProvider
 124          * @exception  E_SUCCESS                        The method is successful.
 125          * @exception  E_INVALID_OPERATION      The application's attribute does not meet the condition to provide AppWidget.
 126          * @exception  E_SYSTEM         The method cannot proceed due to a severe system error.
 127          * @see         IAppWidgetProviderFactory
 128          */
 129         result SetAppWidgetProviderFactory(IAppWidgetProviderFactory& factory);
 130
 131         /**
 132          * Sets a AppWidgetPopupProvider factory. @n
 133          * The factory is called when AppWidgetPopupProvider needs to be created.
 134          * The %SetAppWidgetPopupProviderFactory() method should be called in App::OnAppInitializing(), to receive the event correctly.
 135          * Implementing AppWidgetPopupProviderFactory is mandatory to provide AppWidgetPopup functionality.
 136          *
 137          * @since       2.1
 138          *
 139          * @return      An error code
 140          * @param[in]   factory         The factory to create concrete AppWidgetPopupProvider
 141          * @exception  E_SUCCESS                        The method is successful.
 142          * @exception  E_INVALID_OPERATION      The application's attribute does not meet the condition to provide AppWidget popup.
 143          * @exception  E_SYSTEM         The method cannot proceed due to a severe system error.
 144          * @see         IAppWidgetPopupProviderFactory
 145          */
 146         result SetAppWidgetPopupProviderFactory(IAppWidgetPopupProviderFactory& factory);
 147
 148
 149 private:
 150         //
 151         // This default constructor is intentionally declared as private to implement the %Singleton semantic.
 152         //
 153         // @since       2.1
 154         //
 155         AppWidgetProviderManager(void);
 156
 157         //
 158         // This destructor is intentionally declared as private to implement the %Singleton semantic.
 159         //
 160         // @since       2.1
 161         //
 162         virtual ~AppWidgetProviderManager(void);
 163
 164         /**
 165          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 166          *
 167          * @since       2.1
 168          */
 169         AppWidgetProviderManager& operator =(const AppWidgetProviderManager& rhs);
 170
 171         //
 172         // Constructs the instance of this class.
 173         //
 174         // @since       2.1
 175         //
 176         // @return          An error code
 177         // @exception   E_SUCCESS       The method is successful.
 178         // @exception   E_SYSTEM        A system error has occurred.
 179         //
 180         result Construct(void);
 181
 182
 183         static void InitSingleton(void);
 184         static void DestroySingleton(void);
 185
 186 private:
 187         static AppWidgetProviderManager* __pTheInstance;
 188         class _AppWidgetProviderManagerImpl* __pAppWidgetProviderManagerImpl;
 189         friend struct std::default_delete< AppWidgetProviderManager >;
 190 }; // AppWidgetProviderManager
 191
 192 }} // Tizen::Shell
 193
 194 #endif /* _FSHELL_APPWIDGET_PROVIDER_MANAGER_H_ */