inc/FMsgMmsManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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  * @file                FMsgMmsManager.h
  19  * @brief               This is the header file for the %MmsManager class.
  20  *
  21  * This header file contains the declarations of the %MmsManager class.
  22  */
  23
  24
  25 #ifndef _FMSG_MMS_MANAGER_H_
  26 #define _FMSG_MMS_MANAGER_H_
  27
  28 // Includes
  29 #include <FBase.h>
  30 #include <FMsgIMmsListener.h>
  31 #include <FMsgMmsMessage.h>
  32 #include <FMsgRecipientList.h>
  33
  34 namespace Tizen { namespace Messaging
  35 {
  36
  37         // forward declaration for class extension
  38         class _MmsManagerImpl;
  39
  40    /**
  41         * @class        MmsManager
  42         * @brief        This class provides methods to use the Multimedia Messaging Service.
  43         *
  44         * @since                2.0
  45         *
  46         * The %MmsManager class is used to send Multimedia Messaging Service.
  47         *
  48         * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/messaging.htm">Messaging Guide</a>.
  49         *
  50         * The following example demonstrates how to use the %MmsManager class.
  51         *
  52         * @code
  53         *
  54         // Creates a listener to override the OnMmsMessageSent() method of IMmsListener
  55         // in order to be notified of a change in the state of the message being sent.
  56
  57         class MmsListener
  58                 : public IMmsListener
  59                 , public Object
  60         {
  61         public:
  62                 void OnMmsMessageSent(result r);
  63         };
  64         void MmsListener::OnMmsMessageSent(result r)
  65         {
  66                 // Do something.
  67         }
  68
  69         class SendMmsMessage
  70                 : public Object
  71         {
  72         public:
  73                 void MmsTest(void);
  74         };
  75
  76         void
  77         SendMmsMessage::MmsTest(void)
  78         {
  79                 result r = E_SUCCESS;
  80
  81                 // Creates an MmsListener instance.
  82                 MmsListener* pListener = new MmsListener();
  83
  84                 // Creates an MMS manager instance with the listener as the callback to check the status of the message being sent.
  85                 MmsManager* pMmsManager = new MmsManager();
  86                 r = pMmsManager->Construct(*pListener);
  87
  88                 // Creates a recipient list instance and add recipients.
  89                 RecipientList recipient;
  90                 r = recipient.Add (RECIPIENT_TYPE_TO, L"01012345678");
  91                 r = recipient.Add (RECIPIENT_TYPE_CC, L"01012345679");
  92                 r = recipient.Add (RECIPIENT_TYPE_BCC, L"01012345670");
  93
  94                 // Creates an MMS message instance.
  95                 MmsMessage mmsMessage;
  96                 r = mmsMessage.SetSubject(L"Subject!!!");
  97                 r = mmsMessage.SetText(L"Hello, World");
  98                 r = mmsMessage.AddAttachment(MMS_IMAGE, L"/opt/usr/media/image.jpg");
  99                 r = mmsMessage.AddAttachment(MMS_AUDIO, L"/opt/usr/media/audio.wav");
 100
 101                 // Sends the message, and set the saveToSentbox parameter to true if the message should be saved in the Sentbox; otherwise, set to false.
 102                 // MmsListener callback is called once the message has been completely sent.
 103                 r = pMmsManager->Send(mmsMessage, recipient, true);
 104         }
 105         *
 106         * @endcode
 107         */
 108         class _OSP_EXPORT_ MmsManager
 109                 : public Tizen::Base::Object
 110         {
 111                 // Life cycle
 112         public:
 113            /**
 114                 *       This is the default constructor for this class.
 115                 *
 116                 * @since                2.0
 117                 */
 118                 MmsManager(void);
 119
 120            /**
 121                 *       This is the destructor for this class.
 122                 *
 123                 * @since                2.0
 124                 */
 125                 virtual ~MmsManager(void);
 126
 127         private:
 128                 MmsManager(const MmsManager& value);
 129                 MmsManager& operator =(const MmsManager& rhs);
 130
 131                 // Operation
 132         public:
 133            /**
 134                 * Initializes this instance of %MmsManager with the specified parameter.
 135                 *
 136                 * @since                2.0
 137                 *
 138                 * @feature              %http://tizen.org/feature/network.telephony.mms
 139                 * @return               An error code
 140                 * @param[in]    listener                                The listener to receive the sent result asynchronously
 141                 * @exception    E_SUCCESS                               The method is successful.
 142                 * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 143                 * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
 144                 *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 145                 * @remarks      Before calling this method, check whether the feature is supported by
 146                 *                       Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 147                 */
 148                 result  Construct(IMmsListener &listener);
 149
 150            /**
 151                 * Sends the specified MMS message.
 152                 *
 153                 * @since                2.0
 154                 * @privlevel    public
 155                 * @privilege    %http://tizen.org/privilege/messaging.write @n
 156                 *                               (%http://tizen.org/privilege/messaging.mms is deprecated.)
 157                 *
 158                 * @return               An error code
 159                 * @param[in]    message                                 The message to send
 160                 * @param[in]    recipientList                   The list of recipients
 161                 * @param[in]    saveToSentbox                   Set to @c true to save the message in the Sentbox, @n
 162                 *                                                                               else @c false
 163                 * @exception    E_SUCCESS                               The method is successful.
 164                 * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
 165                 * @exception    E_ON_INITIALIZING               The mailbox is not completely loaded as yet.
 166                 * @exception    E_STORAGE_FULL                  The storage is full.
 167                 * @exception    E_DEVICE_UNAVAILABLE    The device is unavailable.
 168                 * @exception    E_NETWORK_UNAVAILABLE   The network is unavailable.
 169                 * @exception    E_INVALID_CONDITION             The profile is not set.
 170                 * @exception    E_INVALID_ADDRESS               The address is invalid.
 171                 * @exception    E_FDN_MODE                              The FDN mode has been activated.
 172                 * @exception    E_INVALID_ARG                   Either of the following conditions has occurred:
 173                 *                                                                       - The number of recipients is @c 0.
 174                 *                                                                       - The message is empty.
 175                 * @exception    E_MAX_EXCEEDED                  The number of recipients has crossed the maximum limit (Maximum 10).
 176                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 177                 * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 178                 * @remarks
 179                 *                       - Some service providers may not support sending MMS messages with an empty subject or body. @n
 180                 *                       In this case, the result of the status report is the @c E_FAILURE exception.
 181                 *                       - The CC and BCC recipients in the @c recipientList are merged with the TO recipients when sending an MMS message.
 182                 * @see          IMmsListener::OnMmsMessageSent()
 183                 */
 184                 result Send(const MmsMessage& message, const RecipientList& recipientList, bool saveToSentbox);
 185
 186         private:
 187                 _MmsManagerImpl* __pImpl;
 188
 189         // friend class
 190         friend class _MmsManagerImpl;
 191         }; // MmsManager
 192 } } // Tizen::Messaging
 193 #endif // _FMSG_MMS_MANAGER_H_