inc/FNetBtBluetoothSppInitiator.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 /**
  19  * @file    FNetBtBluetoothSppInitiator.h
  20  * @brief   This is the header file for the %BluetoothSppInitiator class.
  21  *
  22  * This header file contains the declarations of the %BluetoothSppInitiator class.
  23  */
  24 #ifndef _FNET_BT_BLUETOOTH_SPP_INITIATOR_H_
  25 #define _FNET_BT_BLUETOOTH_SPP_INITIATOR_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseResult.h>
  29 #include <FBaseUuId.h>
  30 #include <FNetBtBluetoothTypes.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34 class ByteBuffer;
  35 } }
  36
  37 namespace Tizen { namespace Net { namespace Bluetooth
  38 {
  39
  40 // forward declarations
  41 class BluetoothDevice;
  42 class IBluetoothSppInitiatorEventListener;
  43 class _BluetoothSppInitiatorImpl;
  44
  45 /**
  46  * @class   BluetoothSppInitiator
  47  * @brief   This class provides the methods to handle the %Bluetooth Serial Port Profile (SPP) initiator, such as the
  48  *          outgoing connection requests.
  49  * @since   2.0
  50  *
  51  * The %BluetoothSppInitiator class provides the methods to handle the %Bluetooth Serial Port Profile (SPP) initiator, such as
  52  * the outgoing connection requests.
  53  *
  54  * For more information on the class features, see
  55  * <a href="../org.tizen.native.appprogramming/html/guide/net/bluetooth_namespace.htm">Bluetooth Guide</a>.
  56  */
  57 class _OSP_EXPORT_ BluetoothSppInitiator
  58         : public Tizen::Base::Object
  59 {
  60 public:
  61         /**
  62          * The object is not fully constructed after this constructor is called. For full construction, the Construct()
  63          * method must be called right after calling this constructor.
  64          *
  65          * @since       2.0
  66          */
  67         BluetoothSppInitiator(void);
  68
  69         /**
  70          * This destructor overrides Tizen::Base::Object::~Object().
  71          *
  72          * @since       2.0
  73          */
  74         virtual ~BluetoothSppInitiator(void);
  75
  76         /**
  77          * Constructs and initializes this instance of %BluetoothSppInitiator with the specified listener.
  78          *
  79          * @since       2.0
  80          * @feature     %http://tizen.org/feature/network.bluetooth
  81          *
  82          * @return      An error code
  83          * @param[in]   listener                The event listener for the SPP initiator
  84          * @exception   E_SUCCESS               The method is successful.
  85          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  86          * @exception   E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature.
  87          *                                      For more information, see
  88          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
  89          *                                      Application Filtering</a>.
  90          * @exception   E_SYSTEM                A system error has occurred.
  91          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue()
  92          *              methods.
  93          */
  94         result Construct(IBluetoothSppInitiatorEventListener& listener);
  95
  96         /**
  97          * Connects to a remote SPP acceptor with the default service UUID - BT_SVC_UUID_SPP. @n
  98          * The %Connect() method establishes a connection after the SPP acceptor accepts the request.
  99          *
 100          * @since       2.0
 101          * @privlevel   public
 102          * @privilege   %http://tizen.org/privilege/bluetooth.spp
 103          *
 104          * @return      An error code
 105          * @param[in]   remoteDevice                The remote device to connect
 106          * @exception   E_SUCCESS                   The method is successful.
 107          * @exception   E_INVALID_STATE             This instance is in an invalid state. @n
 108          *                                          For example, this instance has not been constructed as yet or
 109          *                                          %Bluetooth is not activated.
 110          * @exception   E_IN_PROGRESS               The connection process is in progress.
 111          * @exception   E_ALREADY_CONNECTED         The connection with an SPP acceptor has already been established.
 112          * @exception   E_PRIVILEGE_DENIED          The application does not have the privilege to call this method.
 113          * @exception   E_USER_NOT_CONSENTED        The user blocks an application from calling this method. @b Since: @b 2.1
 114          * @exception   E_SERVICE_UNAVAILABLE       The SPP connection is unavailable.
 115          * @exception   E_REMOTE_DEVICE_NOT_FOUND   The input device is not found. @n
 116          *                                          This exception is currently not in use.
 117          * @exception   E_FAILURE                   The method has failed.
 118          * @remarks     If the local device is not paired with the specified target device, the pairing process starts
 119          *              internally before the connect request is sent.
 120          * @see         IBluetoothSppAcceptorEventListener::OnSppConnectionRequested()
 121          */
 122         result Connect(const BluetoothDevice& remoteDevice);
 123
 124         /**
 125          * Connects to a remote SPP acceptor with the specified service UUID. @n
 126          * The %Connect() method establishes a connection after the SPP acceptor accepts the request.
 127          *
 128          * @since 2.0
 129          * @privlevel   public
 130          * @privilege   %http://tizen.org/privilege/bluetooth.spp
 131          *
 132          * @return      An error code
 133          * @param[in]   remoteDevice                The remote device to connect
 134          * @param[in]   serviceUuid                 The UUID of SPP service to connect
 135          * @exception   E_SUCCESS                   The method is successful.
 136          * @exception   E_INVALID_STATE             This instance is in an invalid state. @n
 137          *                                          For example, this instance has not been constructed as yet or
 138          *                                          %Bluetooth is not activated.
 139          * @exception   E_INVALID_ARG               A specified input parameter is invalid.
 140          * @exception   E_IN_PROGRESS               The connection process is in progress.
 141          * @exception   E_ALREADY_CONNECTED         The connection with an SPP acceptor has already been established.
 142          * @exception   E_PRIVILEGE_DENIED          The application does not have the privilege to call this method.
 143          * @exception   E_USER_NOT_CONSENTED        The user blocks an application from calling this method. @b Since: @b 2.1
 144          * @exception   E_SERVICE_UNAVAILABLE       The SPP connection is unavailable.
 145          * @exception   E_REMOTE_DEVICE_NOT_FOUND   The input device is not found. @n
 146          *                                          This exception is currently not in use.
 147          * @exception   E_FAILURE                   The method has failed.
 148          * @remarks     If the local device is not paired with the specified target device, the pairing process starts
 149          *              internally before the connect request is sent.
 150          * @see         IBluetoothSppAcceptorEventListener::OnSppConnectionRequested()
 151          */
 152         result Connect(const BluetoothDevice& remoteDevice, const Tizen::Base::UuId& serviceUuid);
 153
 154         /**
 155          * Disconnects the current connection. @n
 156          * If the %Disconnect() method is called before the SPP acceptor accepts the connection request, the
 157          * IBluetoothSppInitiatorEventListener::OnSppConnectionResponded() method and its result @c E_SYSTEM is thrown. @n
 158          * If this method is called on connection, the IBluetoothSppInitiatorEventListener::OnSppDisconnected() method and
 159          * its result @c E_SUCCESS is thrown.
 160          *
 161          * @since       2.0
 162          * @privlevel   public
 163          * @privilege   %http://tizen.org/privilege/bluetooth.spp
 164          *
 165          * @return      An error code
 166          * @exception   E_SUCCESS               The method is successful.
 167          * @exception   E_INVALID_STATE         This instance is in an invalid state. @n
 168          *                                      For example, this instance has not been constructed as yet or %Bluetooth is
 169          *                                      not activated.
 170          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 171          *                                      operation. @n
 172          *                                      For example, the connection request is not sent or a connection with a
 173          *                                      remote device is not established yet.
 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          * @exception   E_FAILURE               The method has failed.
 177          * @see         IBluetoothSppAcceptorEventListener::OnSppDisconnected()
 178          */
 179         result Disconnect(void);
 180
 181         /**
 182          * Sends the specified data.
 183          *
 184          * @since       2.0
 185          * @privlevel   public
 186          * @privilege   %http://tizen.org/privilege/bluetooth.spp
 187          *
 188          * @return      An error code
 189          * @param[in]   buffer                  The data to send @n
 190          *                                      The size of the buffer should not exceed @c 1000 bytes.
 191          * @exception   E_SUCCESS               The method is successful.
 192          * @exception   E_INVALID_STATE         This instance is in an invalid state. @n
 193          *                                      For example, this instance has not been constructed as yet or %Bluetooth is
 194          *                                      not activated.
 195          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified
 196          *                                      operation. @n
 197          *                                      For example, the connection request is not sent or a connection with a
 198          *                                      remote device is not established yet.
 199          * @exception   E_INVALID_ARG           The argument has no data.
 200          * @exception   E_SYSTEM                A system error has occurred.
 201          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 202          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 203          * @exception   E_FAILURE               The method has failed.
 204          * @see         IBluetoothSppAcceptorEventListener::OnSppDataReceived()
 205          */
 206         result SendData(const Tizen::Base::ByteBuffer& buffer);
 207
 208 private:
 209         //
 210         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying
 211         // of objects.
 212         //
 213         BluetoothSppInitiator(const BluetoothSppInitiator& value);
 214
 215         //
 216         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit
 217         // copying of objects.
 218         //
 219         BluetoothSppInitiator& operator =(const BluetoothSppInitiator& value);
 220
 221 private:
 222         _BluetoothSppInitiatorImpl* __pImpl;
 223
 224 }; // BluetoothSppInitiator
 225
 226 } } }
 227 #endif // _FNET_BT_BLUETOOTH_SPP_INITIATOR_H_