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          * @feature        %http://tizen.org/feature/shell.appwidget\r
  61          *
  62          * @return         A pointer to the %AppWidgetProviderManager instance, @n
  63          *                                 else @c null if it fails
  64          * @exception      E_SUCCESS       The method is successful.\r
  65          * @exception      E_SYSTEM        The method cannot proceed due to a severe system error.
  66          * @exception      E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature.\r
  67          *                 For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.\r
  68          *
  69          * @remarks      - The specific error code can be accessed using the GetLastResult() method.
  70          *               - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.\r
  71          */
  72         static AppWidgetProviderManager* GetInstance(void);
  73
  74         /**
  75          * Requests AppWidget service to trigger the specified AppWidget update.
  76          *
  77          * @since       2.1
  78          *
  79          * @param[in]   appId                   The appId that provides AppWidget
  80          * @param[in]   providerName    The name of the AppWidget provider
  81          * @param[in]   userInfo                User information for the AppWidget provider @n
  82          *                                                              This parameter will be delivered as parameter of AppWidgetProvider::OnAppWidgetProviderUpdating().
  83          *
  84          * @exception   E_SUCCESS                       The method is successful.
  85          * @exception   E_APP_NOT_INSTALLED     The application is not installed.
  86          * @exception   E_OBJ_NOT_FOUND         The specified AppWidget provider is not found.
  87          * @exception   E_CERTIFICATE_VERIFICATION_FAILED       The application is not permitted to request to update AppWidget of other application package. @n
  88          *                                                                      To get permission, the target application is signed with the same certificate.
  89          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  90          *
  91          * @see                 AppWidgetProvider::OnAppWidgetProviderUpdating()
  92          */
  93         result RequestUpdate(const Tizen::App::AppId& appId, const Tizen::Base::String& providerName, const Tizen::Base::String& argument = L"");
  94
  95         /**
  96          * Requests a AppWidget viewer (for example, Home screen, Lock screen) to add the specified AppWidget.
  97          *
  98          * @since       2.1
  99          * @privlevel   public
 100          * @privilege   %http://tizen.org/privilege/appwidgetprovider.install
 101          *
 102          * @param[in]   providerAppId   The ID of the application providing AppWidget
 103          * @param[in]   providerName    The name of AppWidget provider to add
 104          * @param[in]   alternateText   Alternate text displayed in the AppWidgetView while the AppWidgetProvider is initializing or unavailable.
 105          * @param[in]   userInfo                User information for the AppWidget provider
 106          *
 107          * @exception   E_SUCCESS                       The method is successful.
 108          * @exception   E_APP_NOT_INSTALLED     The application is not installed.
 109          * @exception   E_OBJ_NOT_FOUND The specified AppWidget provider is not found.
 110          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 111          * @exception   E_CERTIFICATE_VERIFICATION_FAILED       The application is not permitted to request to add AppWidget of other application package. @n
 112          *                                                                      To get permission, the target application is signed with the same certificate.
 113          * @exception   E_UNSUPPORTED_OPERATION The specified AppWidget provider does not support this operation. @n
 114          *                                                                              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.
 115          * @exception   E_CONNECTION_FAILED     The viewer application does not set a listener to receive this request.
 116          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 117          *
 118          * @remarks     Only AppWidget provider that is packaged with the caller application can be added by this method.
 119          * @see         AppWidgetManager::SetAppWidgetRequestListener()
 120          */
 121         result AddAppWidget(const Tizen::App::AppId& providerAppId, const Tizen::Base::String& providerName, const Tizen::Base::String& alternateText, const Tizen::Base::String& userInfo);
 122
 123         /**
 124          * Sets a AppWidgetProvider factory. @n
 125          * The factory is called when AppWidgetProvider needs to be created.
 126          * The %SetAppWidgetProviderFactory() method should be called in App::OnAppInitializing(), to receive the event correctly.
 127          * Implementing AppWidgetProviderFactory is mandatory to provide AppWidget functionality.
 128          *
 129          * @since       2.1
 130          *
 131          * @return      An error code
 132          * @param[in]   factory         The factory to create concrete AppWidgetProvider
 133          * @exception  E_SUCCESS                        The method is successful.
 134          * @exception  E_INVALID_OPERATION      The application's attribute does not meet the condition to provide AppWidget.
 135          * @exception  E_SYSTEM         The method cannot proceed due to a severe system error.
 136          * @see         IAppWidgetProviderFactory
 137          */
 138         result SetAppWidgetProviderFactory(IAppWidgetProviderFactory& factory);
 139
 140         /**
 141          * Sets a AppWidgetPopupProvider factory. @n
 142          * The factory is called when AppWidgetPopupProvider needs to be created.
 143          * The %SetAppWidgetPopupProviderFactory() method should be called in App::OnAppInitializing(), to receive the event correctly.
 144          * Implementing AppWidgetPopupProviderFactory is mandatory to provide AppWidgetPopup functionality.
 145          *
 146          * @since       2.1
 147          *
 148          * @return      An error code
 149          * @param[in]   factory         The factory to create concrete AppWidgetPopupProvider
 150          * @exception  E_SUCCESS                        The method is successful.
 151          * @exception  E_INVALID_OPERATION      The application's attribute does not meet the condition to provide AppWidget popup.
 152          * @exception  E_SYSTEM         The method cannot proceed due to a severe system error.
 153          * @see         IAppWidgetPopupProviderFactory
 154          */
 155         result SetAppWidgetPopupProviderFactory(IAppWidgetPopupProviderFactory& factory);
 156
 157
 158 private:
 159         //
 160         // This default constructor is intentionally declared as private to implement the %Singleton semantic.
 161         //
 162         // @since       2.1
 163         //
 164         AppWidgetProviderManager(void);
 165
 166         //
 167         // This destructor is intentionally declared as private to implement the %Singleton semantic.
 168         //
 169         // @since       2.1
 170         //
 171         virtual ~AppWidgetProviderManager(void);
 172
 173         /**
 174          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 175          *
 176          * @since       2.1
 177          */
 178         AppWidgetProviderManager& operator =(const AppWidgetProviderManager& rhs);
 179
 180         //
 181         // Constructs the instance of this class.
 182         //
 183         // @since       2.1
 184         //
 185         // @return          An error code
 186         // @exception   E_SUCCESS       The method is successful.
 187         // @exception   E_SYSTEM        A system error has occurred.
 188         //
 189         result Construct(void);
 190
 191
 192         static void InitSingleton(void);
 193         static void DestroySingleton(void);
 194
 195 private:
 196         static AppWidgetProviderManager* __pTheInstance;
 197         class _AppWidgetProviderManagerImpl* __pAppWidgetProviderManagerImpl;
 198         friend struct std::default_delete< AppWidgetProviderManager >;
 199 }; // AppWidgetProviderManager
 200
 201 }} // Tizen::Shell
 202
 203 #endif /* _FSHELL_APPWIDGET_PROVIDER_MANAGER_H_ */