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 MMS messaging service.
  43         *
  44         * @since                2.0
  45         *
  46         * The %MmsManager class is used to send MMS messages.
  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() function 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"/Home/Res/image.jpg");
  99                 r = mmsMessage.AddAttachment(MMS_IMAGE, L"/Home/Res/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                 * @return                       An error code
 139                 * @param[in]    listener                The listener to receive a send result asynchronously
 140                 * @exception    E_SUCCESS               The method is successful.
 141                 * @exception    E_OUT_OF_MEMORY The memory is insufficient.
 142                 */
 143                 result                  Construct(IMmsListener &listener);
 144
 145                 /**
 146                 * Sends the MMS message.
 147                 *
 148                 * @since                2.0
 149                 * @privlevel    public
 150                 * @privilege    http://tizen.org/privilege/messaging.mms
 151                 *
 152                 * @return               An error code
 153                 * @param[in]    message                                 The message to be sent
 154                 * @param[in]    recipientList                   The list of recipients
 155                 * @param[in]    saveToSentbox                   Set to @c true to save the message in the Sentbox, @n
 156                 *                                                                               else @c false
 157                 * @exception    E_SUCCESS                               The method is successful.
 158                 * @exception    E_ON_INITIALIZING               The mailbox is not completely loaded as yet.
 159                 * @exception    E_STORAGE_FULL                  The storage is full.
 160                 * @exception    E_DEVICE_UNAVAILABLE    The device is unavailable.
 161                 * @exception    E_NETWORK_UNAVAILABLE   The network is unavailable.
 162                 * @exception    E_INVALID_CONDITION             The profile is not set.
 163                 * @exception    E_INVALID_ADDRESS               The address is invalid.
 164                 * @exception    E_FDN_MODE                              The FDN mode has been activated.
 165                 * @exception    E_INVALID_ARG                   The number of recipients is @c 0 or the message is empty.
 166                 * @exception    E_MAX_EXCEEDED                  The number of recipients has crossed the maximum limit (Maximum 10).
 167                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 168                 * @remarks              Some service providers may not support sending MMS messages with an empty subject or body. @n
 169                 *                               In this case, the result of the status report will be the E_FAILURE exception. @n
 170                 *                               The CC and BCC recipients in the @c recipientList are merged with the TO recipients when sending an MMS message.
 171                 * @see                  IMmsListener::OnMmsMessageSent()
 172                 */
 173                 result Send(const MmsMessage& message, const RecipientList& recipientList, bool saveToSentbox);
 174
 175         private:
 176                 _MmsManagerImpl* __pImpl;
 177
 178         // friend class
 179         friend class _MmsManagerImpl;
 180         }; // MmsManager
 181 } } // Tizen::Messaging
 182 #endif // _FMSG_MMS_MANAGER_H_