inc/FTelCallManager.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  FTelCallManager.h
  19  * @brief This is the header file for the %CallManager class.
  20  *
  21  * This header file contains the declarations of the %CallManager class.
  22  */
  23 #ifndef _FTEL_CALL_MANAGER_H_
  24 #define _FTEL_CALL_MANAGER_H_
  25
  26
  27 #include <FBase.h>
  28 #include <FTelTypes.h>
  29 #include <FTelCallInfo.h>
  30 #include <FTelITelephonyCallEventListener.h>
  31 #include <FTelITelephonyCallForwardListener.h>
  32
  33
  34 namespace Tizen { namespace Telephony
  35 {
  36 class _CallManagerImpl;
  37
  38 /**
  39  * @class       CallManager
  40  * @brief       This class provides methods to obtain information about the current call.
  41  *
  42  * @since       2.0
  43  *
  44  * The %CallManager class provides methods to obtain information about the current call type and its status.
  45  *
  46  * The following example demonstrates how to use the %CallManager class to obtain information about a call.
  47  *
  48  * @code
  49  *
  50  *  #include <FBase.h>
  51  *  #include <FTelephony.h>
  52  *
  53  *   using namespace Tizen::Base;
  54  *   using namespace Tizen::Telephony;
  55  *
  56  *   class MyClass
  57  *       : public Object
  58  *       , public ITelephonyCallEventListener
  59  *   {
  60  *   public:
  61  *       MyClass(void) {}
  62  *       ~MyClass(void) {}
  63  *
  64  *       // ITelephonyCallEventListener
  65  *       void OnTelephonyCallStatusChangedN(CallStatus callStatus, CallInfo* pCallInfo);
  66  *
  67  *       void GetCallInfo(void);
  68  *   };
  69  *
  70  *   void
  71  *   MyClass::OnTelephonyCallStatusChangedN(CallStatus callStatus, CallInfo* pCallInfo)
  72  *   {
  73  *       CallType callType;
  74  *       String number;
  75  *
  76  *       if (callStatus == CALL_STATUS_RINGING)
  77  *       {
  78  *               callType  = pCallInfo->GetCallType();
  79  *               number = pCallInfo->GetNumber();
  80  *       }
  81  *
  82  *       delete pCallInfo;
  83  *   }
  84  *
  85  *   void
  86  *   MyClass::GetCallInfo(void)
  87  *   {
  88  *       CallType callType = TYPE_UNDEFINED_CALL;
  89  *       CallStatus callStatus = CALL_STATUS_UNDEFINED;
  90  *
  91  *       CallManager* pCallManager = new (std::nothrow) CallManager();
  92  *
  93  *       result r = pCallManager->Construct(*this);
  94  *       if (IsFailed(r))
  95  *       {
  96  *         delete pCallManager;
  97  *         return;
  98  *       }
  99  *
 100  *       callStatus = pCallManager->GetCurrentCallStatus();
 101  *       if (callStatus == CALL_STATUS_COMMUNICATING)
 102  *       {
 103  *               callType = pCallManager->GetCurrentCallType();
 104  *       }
 105  *
 106  *       delete pCallManager;
 107  *   }
 108  *
 109  *
 110  *
 111  * @endcode
 112  */
 113 class _OSP_EXPORT_ CallManager
 114         : public Tizen::Base::Object
 115 {
 116 public:
 117         /**
 118      * The object is not fully constructed after this constructor is called.
 119          * For full construction, the Construct() method must be called right after calling this constructor.
 120      *
 121      * @since   2.0
 122      */
 123         CallManager(void);
 124
 125         /**
 126      * This destructor overrides Tizen::Base::Object::~Object().
 127      *
 128      * @since   2.0
 129      */
 130         virtual ~CallManager(void);
 131
 132         /**
 133      * Initializes a new instance of %CallManager. @n
 134      * This is a two phase construction.
 135      *
 136      * @since           2.0
 137          * @feature     %http://tizen.org/feature/network.telephony
 138      * @return          An error code
 139      * @exception   E_SUCCESS                            The method is successful.
 140      * @exception   E_SYSTEM                             A system error has occurred.
 141          * @exception   E_UNSUPPORTED_OPERATION  The Emulator or target device does not support the required feature. @b Since: @b 2.1
 142          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 143          * @remarks     Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 144      */
 145         result Construct(void);
 146
 147         /**
 148      * Initializes a new instance of %CallManager. @n
 149      * This is a two phase construction.
 150      *
 151      * @since           2.0
 152          * @feature     %http://tizen.org/feature/network.telephony
 153      * @return          An error code
 154      * @param[in]   listener                             The listener for the change in the call status
 155      * @exception   E_SUCCESS                            The method is successful.
 156      * @exception   E_SYSTEM                             A system error has occurred.
 157          * @exception   E_UNSUPPORTED_OPERATION  The Emulator or target device does not support the required feature. @b Since: @b 2.1
 158          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 159          * @remarks     Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 160      */
 161         result Construct(ITelephonyCallEventListener& listener);
 162
 163         /**
 164      * Sets the listener that listens to the call forwarding request.
 165      *
 166      * @since   2.0
 167          *
 168      * @privlevel       platform
 169      * @privilege   %http://tizen.org/privilege/callforward
 170      *
 171      * @return          An error code
 172      * @param[in]   pListener           An ITelephonyCallForwardListener instance @n
 173      *                                  The parameter can be set to @c null to remove the listener.
 174      * @exception   E_SUCCESS           The method is successful.
 175      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 176      * @exception   E_SYSTEM            A system error has occurred.
 177      */
 178         result SetCallForwardListener(ITelephonyCallForwardListener* pListener);
 179
 180         /**
 181      * Requests call forwarding to the specified number. @n
 182      * The %RequestCallForward() method sends a request to the network, and receives the response asynchronously.
 183      *
 184      * @since   2.0
 185          *
 186      * @privlevel       platform
 187      * @privilege   %http://tizen.org/privilege/callforward
 188      *
 189      * @return          An error code
 190      * @param[in]   phoneNumber                         The phone number for call forwarding
 191      * @exception   E_SUCCESS               The method is successful.
 192      * @exception   E_INVALID_STATE         This instance is in an invalid state.
 193      * @exception   E_INVALID_FORMAT        The specified @c phoneNumber is in an invalid format.
 194      * @exception   E_IN_PROGRESS           The previous request is in progress.
 195      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 196      * @exception   E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 197      * @exception   E_SERVICE_UNAVAILABLE   The operation has failed because the device is either out of the coverage area or in the emergency mode.
 198      * @exception   E_SYSTEM                A system error has occurred.
 199      * @remarks
 200      *                          - This method forwards the call unconditionally and supports only voice call. @n
 201      *                  - The phone number must start with a plus(+) sign and the remaining part must be the number.
 202      * @see ITelephonyCallForwardListener::OnTelephonyCallForwardResponseReceived()
 203      */
 204         result RequestCallForward(const Tizen::Base::String& phoneNumber);
 205
 206     /**
 207      * Stops call forwarding.
 208      *
 209      * @since   2.0
 210          *
 211      * @privlevel       platform
 212      * @privilege   %http://tizen.org/privilege/callforward
 213      *
 214      * @return          An error code
 215      * @exception       E_SUCCESS               The method is successful.
 216      * @exception       E_INVALID_STATE         This instance is in an invalid state.
 217      * @exception       E_IN_PROGRESS           The previous request is in progress.
 218      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 219      * @exception       E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 220      * @exception       E_SERVICE_UNAVAILABLE   The operation has failed because the device is either out of the coverage area or in the emergency mode.
 221      * @exception       E_SYSTEM                A system error has occurred.
 222      * @see ITelephonyCallForwardListener::OnTelephonyCallForwardStopped()
 223      */
 224         result StopCallForward(void);
 225
 226         /**
 227      * Gets the phone number to which the call is forwarded.
 228      *
 229      * @since           2.0
 230          *
 231      * @privlevel       platform
 232      * @privilege   %http://tizen.org/privilege/callforward
 233      *
 234      * @return          An error code
 235      * @exception   E_SUCCESS               The method is successful.
 236      * @exception   E_IN_PROGRESS           The previous request is in progress.
 237      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 238      * @exception   E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 239      * @exception   E_SERVICE_UNAVAILABLE   The operation has failed because the device is either out of the coverage area or in the emergency mode.
 240      * @exception   E_SYSTEM                A system error has occurred.
 241      * @see ITelephonyCallForwardListener::OnTelephonyCallForwardNumberReceived()
 242      */
 243         result GetCallForwardNumber(void) const;
 244
 245         /**
 246      * Gets the current call type.
 247      *
 248      * @since                   2.0
 249          *
 250      * @return      The current call type, @n
 251      *              else @c TYPE_UNDEFINED_CALL if the method fails
 252      */
 253         CallType GetCurrentCallType(void) const;
 254
 255         /**
 256      * Gets the current call status.
 257      *
 258      * @since                   2.0
 259          *
 260      * @return      The current call status, @n
 261      *              else @c CALL_STATUS_UNDEFINED if the method fails
 262      */
 263         CallStatus GetCurrentCallStatus(void) const;
 264
 265 private:
 266         /**
 267      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 268      *
 269      * @param[in]       rhs     An instance of %CallManager
 270      */
 271         CallManager(const CallManager& rhs);
 272
 273         /**
 274      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 275      *
 276      * @param[in]       rhs     An instance of %CallManager
 277      */
 278         CallManager& operator =(const CallManager& rhs);
 279
 280 private:
 281         _CallManagerImpl* __pCallManagerImpl;
 282
 283         friend class _CallManagerImpl;
 284 }; // CallManager
 285
 286 } } // Tizen::Telephony
 287 #endif // _FTEL_CALL_MANAGER_H_