inc/FMsgSmsMessage.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                FMsgSmsMessage.h
  19  * @brief               This is the header file for the %SmsMessage class.
  20  *
  21  * This header file contains the declarations of the %SmsMessage class.
  22  */
  23
  24 #ifndef _FMSG_SMS_MESSAGE_H_
  25 #define _FMSG_SMS_MESSAGE_H_
  26
  27 namespace Tizen { namespace Base
  28 {
  29 class String;
  30 class DateTime;
  31 } }
  32
  33 #include <FBaseObject.h>
  34 #include <FMsgTypes.h>
  35
  36 namespace Tizen { namespace Messaging
  37 {
  38         // forward declaration for class extension
  39         class _SmsMessageImpl;
  40         class RecipientList;
  41
  42         /**
  43         * @class        SmsMessage
  44         * @brief        This class provides methods for handling an SMS message.
  45         *
  46         * @since                2.0
  47         *
  48         * The %SmsMessage class provides methods for handling SMS messages. It allows you to set and get the body text of an SMS message.
  49         *
  50         * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/messaging.htm">Messaging Guide</a>.
  51         */
  52         class _OSP_EXPORT_ SmsMessage
  53                 : public Tizen::Base::Object
  54         {
  55                 // Life cycle
  56         public:
  57                 /**
  58                 * This is the default constructor for this class.
  59                 *
  60                 * @since                2.0
  61                 */
  62                 SmsMessage(void);
  63
  64                 /**
  65                 *       This is the destructor for this class.
  66                 *
  67                 * @since                2.0
  68                 */
  69                 virtual ~SmsMessage(void);
  70
  71                 /**
  72                 * This is the copy constructor for the %SmsMessage class.
  73                 *
  74                 * @since                2.0
  75                 *
  76                 * @param[in]    value   An instance of %SmsMessage
  77                 */
  78                 SmsMessage(const SmsMessage& value);
  79
  80         public:
  81
  82                 /**
  83                 * This assignment operator copies an SMS message from the specified instance of %SmsMessage to the calling instance of %SmsMessage.
  84                 *
  85                 * @since                2.0
  86                 *
  87                 * @return                       A reference to the %SmsMessage instance
  88                 * @param[in]    rhs             A reference to the %SmsMessage instance to copy
  89                 */
  90                 SmsMessage& operator =(const SmsMessage& rhs);
  91
  92                 /**
  93                 * Compares the calling instance with the specified instance.
  94                 *
  95                 * @since                2.0
  96                 *
  97                 * @return                       @c true if the specified instance of Tizen::Base::Object is equal to the calling %SmsMessage instance, @n
  98                 *                                               else @c false
  99                 * @param[in]            obj             The object to compare
 100                 */
 101                 virtual bool Equals(const Tizen::Base::Object& obj) const;
 102
 103                 /**
 104                 * Gets the hash value of the current instance.
 105                 *
 106                 * @since                2.0
 107                 *
 108                 * @return                       The hash value of the current instance
 109                 */
 110                 virtual int GetHashCode(void) const;
 111
 112                 // Operation
 113         public:
 114                 /**
 115                 * Sets the body of the SMS message.
 116                 *
 117                 * @since                2.0
 118                 *
 119                 * @return                       An error code
 120                 * @param[in]    text                            The body of the SMS message
 121                 * @exception    E_SUCCESS                       The method is successful.
 122                 * @exception    E_MAX_EXCEEDED          The body length of the message exceeds the maximum limit (Maximum 80 characters).
 123                 * @see                  GetText()
 124                 */
 125                 result SetText(const Tizen::Base::String& text);
 126
 127                 /**
 128                 * Gets the body of the SMS message.
 129                 *
 130                 * @since                2.0
 131                 *
 132                 * @return               The body of the SMS message
 133                 * @remarks              If the message is from the Inbox, Sentbox, or Outbox, it may contain only @c 160 bytes for the body text. @n
 134                 *                               To check whether the message contains more than @c 160 bytes for the body text, use the HasMoreText() method. @n
 135                 *                               To get the full body text, use the SmsManager::GetFullText() method with its message ID.
 136                 * @see                  SetText()
 137         * @see                  HasMoreText()
 138         * @see                  GetId()
 139         * @see                  SmsManager::GetFullText()
 140                 */
 141                 Tizen::Base::String GetText(void) const;
 142
 143
 144                 /**
 145                 * Gets the sender address of the SMS message.
 146                 *
 147                 * @since                2.0
 148                 *
 149                 * @privlevel    public
 150                 * @privilege    %http://tizen.org/privilege/messaging.read
 151                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 152                 *
 153                 * @return                       The sender address of the SMS message
 154                 * @exception    E_SUCCESS                               The method is successful.
 155                 * @exception    E_INVALID_OPERATION             This operation is only allowed to the incoming message or the message from the Inbox.
 156                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 157                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 158                 * @remarks              The specific error code can be accessed using the GetLastResult() method.
 159                 */
 160                 Tizen::Base::String GetSenderAddress(void) const;
 161
 162                 /**
 163                 * Gets the received time of the SMS message.
 164                 *
 165                 * @since                2.0
 166                 *
 167                 * @privlevel    public
 168                 * @privilege    %http://tizen.org/privilege/messaging.read
 169                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 170                 *
 171                 * @return                       The received time of the SMS message
 172                 * @exception    E_SUCCESS                               The method is successful.
 173                 * @exception    E_INVALID_OPERATION             This operation is only allowed to the incoming message or the message from the Inbox.
 174                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 175                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 176                 * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 177                 *                               In case of an error, this method returns the instance denoting 00:00:00, January 1, 1.
 178                 */
 179                 Tizen::Base::DateTime GetReceivedTime(void) const;
 180
 181                 /**
 182                 * Gets the unique ID of the SMS message.
 183                 *
 184                 * @since                2.0
 185                 *
 186                 * @privlevel    public
 187                 * @privilege    %http://tizen.org/privilege/messaging.read
 188                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 189                 *
 190                 * @return               The unique ID of the SMS message
 191                 * @exception    E_SUCCESS                               The method is successful.
 192                 * @exception    E_INVALID_OPERATION             This operation is allowed only when the message is from the Inbox, Sentbox, or Outbox.
 193                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 194                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 195                 * @remarks              In case of an error, this method returns the negative value. For example, @c -1. @n
 196                 *                               The specific error code can be accessed using the GetLastResult() method.
 197                 */
 198                 int GetId(void) const;
 199
 200                 /**
 201                 * Gets the sent time of the SMS message.
 202                 *
 203                 * @since                2.0
 204                 *
 205                 * @privlevel    public
 206                 * @privilege    %http://tizen.org/privilege/messaging.read
 207                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 208                 *
 209                 * @return               The sent time of the SMS message
 210                 * @exception    E_SUCCESS                               The method is successful.
 211                 * @exception    E_INVALID_OPERATION             This operation is allowed only when the message is from the Sentbox or Outbox.
 212                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 213                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 214                 * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 215                 *                               In case of an error, this method returns the instance denoting 00:00:00, January 1, 1.
 216                 */
 217                 Tizen::Base::DateTime GetSentTime(void) const;
 218
 219                 /**
 220                 * Gets the type of the SMS message box.
 221                 *
 222                 * @since                2.0
 223                 *
 224                 * @privlevel    public
 225                 * @privilege    %http://tizen.org/privilege/messaging.read
 226                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 227                 *
 228                 * @return               The type of the SMS message box
 229                 * @exception    E_SUCCESS                               The method is successful.
 230                 * @exception    E_INVALID_OPERATION             This operation is allowed only when the message is from the Inbox, Sentbox, or Outbox.
 231                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 232                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 233                 * @remarks              In case of an error, this method returns the SMS_MESSAGE_BOX_TYPE_NONE value. @n
 234                 *                               The specific error code can be accessed using the GetLastResult() method.
 235                 */
 236                 SmsMessageBoxType GetMessageBoxType(void) const;
 237
 238                 /**
 239                 * Gets the list of the recipients.
 240                 *
 241                 * @since                2.0
 242                 *
 243                 * @privlevel    public
 244                 * @privilege    %http://tizen.org/privilege/messaging.read
 245                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 246                 *
 247                 * @return               The list of the recipient
 248                 * @exception    E_SUCCESS                               The method is successful.
 249                 * @exception    E_INVALID_OPERATION             This operation is allowed only when the message is from the Sentbox or Outbox.
 250                 * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 251                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 252                 * @remarks              The specific error code can be accessed using the GetLastResult() method.
 253                 */
 254                 RecipientList GetRecipientList(void) const;
 255
 256                 /**
 257                 * Checks whether the SMS message contains more than @c 160 bytes for the body text.
 258                 *
 259                 * @since                2.0
 260                 *
 261                 * @privlevel    public
 262                 * @privilege    %http://tizen.org/privilege/messaging.read
 263                 *                               (%http://tizen.org/privilege/messaging.sms is deprecated.)
 264                 *
 265                 * @return               @c true if this SMS message contains more than @c 160 bytes for the body text, @n
 266                 *                               else @c false
 267                 * @exception    E_SUCCESS                               The method is successful.
 268                 * @exception    E_INVALID_OPERATION             This operation is allowed only when the message is from the Inbox, Sentbox, or Outbox.
 269                 * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 270                 * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 271                 * @remarks              If the return value is @c true, the SMS message contains more than @c 160 bytes for the body text. @n
 272                 *                               To get the full body text, use SmsManager::GetFullText(). @n
 273                 *                               The specific error code can be accessed using the GetLastResult() method.
 274                 */
 275                 bool HasMoreText(void) const;
 276
 277         private:
 278                 _SmsMessageImpl* __pImpl;
 279
 280                 // friend class
 281                 friend class _SmsMessageImpl;
 282         }; // SmsMessage
 283 } } // Tizen::Messaging
 284
 285 #endif // _FMSG_SMS_MESSAGE_H_