inc/FNetSockSocketLingerOption.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 /**
  20 * @file         FNetSockSocketLingerOption.h
  21 * @brief        This is the header file for the %LingerOption class.
  22 *
  23 * This header file contains the declarations of the %LingerOption class.
  24 */
  25
  26 #ifndef _FNET_SOCK_SOCKET_LINGER_OPTION_H_
  27 #define _FNET_SOCK_SOCKET_LINGER_OPTION_H_
  28
  29 #include <FBaseObject.h>
  30
  31 namespace Tizen { namespace Net { namespace Sockets
  32 {
  33
  34 class _LingerOptionImpl;
  35
  36 /**
  37 * @class        LingerOption
  38 * @brief        This class specifies whether a socket remains connected after the Socket::Close() method is called.
  39 *                       It also specifies the amount of time for which it remains connected, if the data is not sent.
  40 *
  41 * @since        2.0
  42 *
  43 * The %LingerOption class specifies whether a socket remains connected after the Socket::Close() method is called.
  44 *                       It also specifies the amount of time for which it remains connected, if the data is not sent.
  45 *
  46 *For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/sockets.htm">Sockets Guide</a>.
  47 *
  48 * @see          Tizen::Net::Sockets::Socket::SetSockOpt(NetSocketOptLevel, NetSocketOptName, const LingerOption&)
  49 *
  50 * The following example demonstrates how to use the %LingerOption class.
  51 *
  52 *       @code
  53 *       using namespace Tizen::Base;
  54 *       using namespace Tizen::Net::Sockets;
  55 *
  56 *       void
  57 *       MyClass::SomeMethod(void)
  58 *       {
  59 *               // Constructs a LingerOption object.
  60 *               LingerOption socketLinger(true, 10);
  61 *
  62 *               // Gets information on a LingerOption object.
  63 *               if (socketLinger.IsEnabled())
  64 *               {
  65 *                       ushort time = socketLinger.GetLingerTime();
  66 *               }
  67 *       }
  68 *       @endcode
  69 */
  70 class _OSP_EXPORT_ LingerOption
  71         : public Tizen::Base::Object
  72 {
  73
  74 public:
  75         /**
  76         * Initializes this instance of %LingerOption class with the specified parameters.
  77         *
  78         * @since                2.0
  79         *
  80         * @param[in]    enable          Set to @c true to remain connected after the Socket::Close() method is called, @n
  81         *                                                       else @c false
  82         * @param[in]    seconds         The number of seconds to remain connected after the Socket::Close() method is called
  83         * @remarks      Data may still be available in the outgoing network buffer after the socket is closed.
  84         *                               If you want to specify the amount of time the socket attempts to transmit unsent data after being closed,
  85         *                               create a %LingerOption with the @c enable parameter set to @c true, and the @c seconds parameter set to the desired
  86         *                               amount of time. The @c seconds parameter is used to indicate how long the socket remains connected
  87         *                               before getting timed out. If the socket is not required to stay connected for any amount of time after being closed,
  88         *                               create a %LingerOption with the enabled parameter set to @c false. In this case, the socket closes immediately
  89         *                               and any unsent data is lost. Once created, pass the %LingerOption to the Socket::SetSoLinger() method.
  90         *
  91         */
  92         LingerOption(bool enable, int seconds);
  93
  94         /**
  95         * This destructor overrides Tizen::Base::Object::~Object().
  96         *
  97         * @since                2.0
  98         */
  99         virtual ~LingerOption(void);
 100
 101         /**
 102         * Copying of objects using this copy constructor is allowed.
 103         *
 104         * @since                2.0
 105         *
 106         * @param[in]    rhs             An instance of %LingerOption
 107         */
 108         LingerOption(const LingerOption& rhs);
 109
 110         /**
 111         * Copying of objects using this copy assignment operator is allowed.
 112         *
 113         * @since                2.0
 114         *
 115         * @return               A reference to this instance
 116         * @param[in]    rhs                     An instance of %LingerOption
 117         */
 118         LingerOption& operator =(const LingerOption& rhs);
 119
 120         /**
 121          * Compares the specified instance of %LingerOption with the calling instance.
 122          *
 123          * @since               2.0
 124          *
 125          * @return              @c true if the values match, @n
 126          *                      else @c false
 127          * @param[in]   obj     The other Tizen::Base::Object to compare
 128          * @see                 Tizen::Base::Object::Equals()
 129          */
 130         virtual bool Equals(const Tizen::Base::Object& obj) const;
 131
 132         /**
 133          * Gets the hash value of the current instance.
 134          *
 135          * @since               2.0
 136          * @return      The hash value of the current instance
 137          */
 138         virtual int GetHashCode(void) const;
 139
 140 public:
 141         /**
 142         * Sets a value indicating whether the socket should linger after being closed.
 143         *
 144         * @since                2.0
 145         *
 146         * @param[in]    on                      Set to @c true if the socket should linger after Socket::Close() is called, @n
 147         *                                                       else @c false
 148         */
 149         void SetEnabled(bool on);
 150
 151         /**
 152         * Sets the linger time. @n
 153         * This is the amount of time to remain connected after calling the Socket::Close() method if data remains to be sent.
 154         *
 155         * @since                2.0
 156         *
 157         * @param[in]    seconds         The amount of time, in seconds, to remain connected after calling Socket::Close()
 158         * @remarks              Use this method to determine how long a closed socket attempts transferring unsent data before getting timed out. The value can
 159         *                               also be set to the desired time-out period in seconds. If the Enabled property is set to @c true, and LingerTime is set to @c 0, the
 160         *                               socket attempts to send the data until there is no data left in the outgoing network buffer.
 161         * @see                  Socket::SetSockOpt()
 162         */
 163         void SetLingerTime(int seconds);
 164
 165         /**
 166         * Gets the linger time. @n
 167         * This is the amount of time to remain connected after calling the Socket::Close() method if data still remains to be sent.
 168         *
 169         * @since                2.0
 170         *
 171         * @return               The amount of time in seconds to remain connected after calling Socket::Close()
 172         */
 173         int GetLingerTime(void) const;
 174
 175         /**
 176          * Checks whether the linger option is enabled.
 177          *
 178          * @since               2.0
 179          *
 180          * @return              @c true if the socket lingers after Socket::Close() is called, @n
 181          *                              else @c false
 182          */
 183         bool IsEnabled(void) const;
 184
 185 private:
 186         /**
 187         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 188         */
 189         LingerOption(void);
 190
 191 private:
 192         _LingerOptionImpl* __pLingerOptionImpl;
 193
 194         friend class _LingerOptionImpl;
 195 };
 196
 197 } } }   // Tizen::Net::Sockets
 198
 199
 200 #endif // _FNET_SOCK_SOCKET_LINGER_OPTION_H_