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. For full construction, the Construct() method must be called right after calling this constructor.
 119      *
 120      * @since   2.0
 121      */
 122         CallManager(void);
 123
 124         /**
 125      * This destructor overrides Tizen::Base::Object::~Object().
 126      *
 127      * @since   2.0
 128      */
 129         virtual ~CallManager(void);
 130
 131         /**
 132      * Initializes a new instance of this class. @n
 133      * This is the two phase construction.
 134      *
 135      * @since   2.0
 136          * @feature %http://tizen.org/feature/network.telephony
 137      * @return  An error code
 138      * @exception   E_SUCCESS           The method is successful.
 139      * @exception   E_SYSTEM            A system error has occurred.
 140          * @exception  E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature. @b Since: @b 2.1
 141          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 142          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 143      */
 144         result Construct(void);
 145
 146         /**
 147      * Initializes a new instance of this class. @n
 148      * This is the two phase construction.
 149      *
 150      * @since   2.0
 151          * @feature %http://tizen.org/feature/network.telephony
 152      * @return  An error code
 153      * @param[in]   listener  The listener for change in status of a call
 154      * @exception   E_SUCCESS The method is successful.
 155      * @exception   E_SYSTEM  A system error has occurred.
 156          * @exception   E_UNSUPPORTED_OPERATION  The Emulator or target device does not support the required feature. @b Since: @b 2.1
 157          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 158          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 159      */
 160         result Construct(ITelephonyCallEventListener& listener);
 161
 162         /**
 163      * Sets the listener that listens to the call forwarding request.
 164      *
 165      * @since   2.0
 166          *
 167      * @privlevel       platform
 168      * @privilege   %http://tizen.org/privilege/callforward
 169      *
 170      * @return  An error code
 171      * @param[in]   pListener           An ITelephonyCallForwardListener instance @n
 172      *                                  The parameter can be set to @c null to remove listener.
 173      * @exception   E_SUCCESS           The method is successful.
 174      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 175      * @exception   E_SYSTEM            A system error has occurred.
 176      */
 177         result SetCallForwardListener(ITelephonyCallForwardListener* pListener);
 178
 179         /**
 180      * Requests call forwarding with the specified number. @n
 181      * The %RequestCallForward() method sends the request to the network, and receives the response asynchronously.
 182      *
 183      * @since   2.0
 184          *
 185      * @privlevel       platform
 186      * @privilege   %http://tizen.org/privilege/callforward
 187      *
 188      * @return  An error code
 189      * @param[in]   phoneNumber The phone number for call forwarding
 190      * @exception   E_SUCCESS               The method is successful.
 191      * @exception   E_INVALID_STATE         This instance is in an invalid state.
 192      * @exception   E_INVALID_FORMAT        The specified phone number is in an invalid format.
 193      * @exception   E_IN_PROGRESS           The previous request is in progress.
 194      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 195      * @exception   E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 196      * @exception   E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 197      * @exception   E_SYSTEM                A system error has occurred.
 198      * @remarks The call will be forwarded unconditionally. Voice call only. @n
 199      *          The phone number can start with plus(+) and the remaining part must be number.
 200      * @see ITelephonyCallForwardListener::OnTelephonyCallForwardResponseReceived()
 201      */
 202         result RequestCallForward(const Tizen::Base::String& phoneNumber);
 203
 204     /**
 205      * Stops call forwarding.
 206      *
 207      * @since   2.0
 208          *
 209      * @privlevel       platform
 210      * @privilege   %http://tizen.org/privilege/callforward
 211      *
 212      * @return  An error code
 213      * @exception       E_SUCCESS               The method is successful.
 214      * @exception       E_INVALID_STATE         This instance is in an invalid state.
 215      * @exception       E_IN_PROGRESS           The previous request is in progress.
 216      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 217      * @exception       E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 218      * @exception       E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 219      * @exception       E_SYSTEM                A system error has occurred.
 220      * @see ITelephonyCallForwardListener::OnTelephonyCallForwardStopped()
 221      */
 222         result StopCallForward(void);
 223
 224         /**
 225      * Gets the phone number to which the call must be forwarded.
 226      *
 227      * @since   2.0
 228          *
 229      * @privlevel       platform
 230      * @privilege   %http://tizen.org/privilege/callforward
 231      *
 232      * @return  An error code
 233      * @exception   E_SUCCESS               The method is successful.
 234      * @exception   E_IN_PROGRESS           The previous request is in progress.
 235      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 236      * @exception   E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 237      * @exception   E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 238      * @exception   E_SYSTEM                A system error has occurred.
 239      * @see ITelephonyCallForwardListener::OnTelephonyCallForwardNumberReceived
 240      */
 241         result GetCallForwardNumber(void) const;
 242
 243         /**
 244      * Gets the call type of the current call.
 245      *
 246      * @since                   2.0
 247          *
 248      * @return      The current call type, @n
 249      *              else @c TYPE_UNDEFINED_CALL if the method fails
 250      */
 251         CallType GetCurrentCallType(void) const;
 252
 253         /**
 254      * Gets the call status of the current call.
 255      *
 256      * @since                   2.0
 257          *
 258      * @return      The current call status, @n
 259      *              else @c CALL_STATUS_UNDEFINED if the method fails
 260      */
 261         CallStatus GetCurrentCallStatus(void) const;
 262
 263 private:
 264         /**
 265      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 266      *
 267      * @param[in]       rhs     An instance of %CallManager
 268      */
 269         CallManager(const CallManager& rhs);
 270
 271         /**
 272      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 273      *
 274      * @param[in]       rhs     An instance of %CallManager
 275      */
 276         CallManager& operator =(const CallManager& rhs);
 277
 278 private:
 279         _CallManagerImpl* __pCallManagerImpl;
 280
 281         friend class _CallManagerImpl;
 282 }; // CallManager
 283
 284 } } // Tizen::Telephony
 285 #endif // _FTEL_CALL_MANAGER_H_