inc/FNetIp4Address.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                FNetIp4Address.h
  20  * @brief               This is the header file for the %Ip4Address class.
  21  *
  22  * @since               2.0
  23  *
  24  * This header file contains the declarations of the %Ip4Address class.
  25  */
  26 #ifndef _FNET_IP4_ADDRESS_H_
  27 #define _FNET_IP4_ADDRESS_H_
  28
  29 #include <FBaseResult.h>
  30 #include <FBaseObject.h>
  31 #include <FNetIpAddress.h>
  32 #include <FNetSockSocketTypes.h>
  33
  34 namespace Tizen { namespace Net
  35 {
  36 class _Ip4AddressImpl;
  37 /**
  38  * @class       Ip4Address
  39  * @brief       This class represents an Internet Protocol version 4 (IPv4) address.
  40  *
  41  * @since       2.0
  42  *
  43  *  The %Ip4Address class specifies the IPv4 address.
  44  *
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/net_namespace.htm">Net Guide</a>. @n
  46  *
  47  * The following example demonstrates how to use the %Ip4Address class.
  48  *
  49  * @code
  50  *      using namespace Tizen::Base;
  51  *      using namespace Tizen::Net;
  52  *
  53  *      result
  54  *      MyClass::SomeMethod(void)
  55  *      {
  56  *              result r = E_SUCCESS;
  57  *
  58  *              Tizen::Base::String ip4String(L"192.168.0.1");
  59  *              Ip4Address* pIp4Address = new Ip4Address(ip4String);
  60  *
  61  *              // Gets the raw IP address.
  62  *              int sizeOfIp4Address = 4;
  63  *              ByteBuffer bb;
  64  *              r = bb.Construct(sizeOfIp4Address);
  65  *              r = pIp4Address->GetAddress(bb);
  66  *
  67  *              // Success
  68  *              return (r);
  69  *      }
  70  * @endcode
  71  */
  72 class _OSP_EXPORT_ Ip4Address
  73         : public IpAddress
  74 {
  75 public:
  76         /**
  77          * Initializes this instance of %Ip4Address with the address specified as a string.
  78          *
  79          * @since               2.0
  80          *
  81          * @param[in]   ipAddr                  The IP Address as a string @n
  82          *                                                              This string represents the IP address in dot-decimal notation (for example, 165.213.173.7)  .
  83          * @exception   E_SUCCESS               The instance is created successfully.
  84          * @exception   E_INVALID_ARG   The specified @c ipAddr is invalid.
  85          * @remarks             The GetLastResult() method is used to check whether the %Ip4Address instance is created successfully.
  86          */
  87         Ip4Address(const Tizen::Base::String& ipAddr);
  88
  89         /**
  90          * Initializes this instance of %Ip4Address with the address specified as an integer.
  91          *
  92          * @since               2.0
  93          *
  94          * @param[in]   ipAddr                  A unsigned @c long number containing the raw IP address @n
  95          *                                                              This is a 32-bit unsigned number. It should be in host byte order.
  96          * @exception   E_SUCCESS               The instance is created successfully.
  97          * @exception   E_INVALID_ARG   The specified @c ipAddr is invalid.
  98          * @remarks             The GetLastResult() method is used to check whether the %Ip4Address instance is created successfully.
  99          * @see                 IpAddress::NetworkToHostOrder()
 100          * @see                 IpAddress::HostToNetworkOrder()
 101          */
 102         Ip4Address(unsigned long ipAddr);
 103
 104         /**
 105          * Copying of objects using this copy constructor is allowed.
 106          *
 107          * @since                       2.0
 108          *
 109          * @param[in]   rhs                     An instance of %Ip4Address
 110          * @remarks             The GetLastResult() method is used to check whether the %Ip4Address instance is created successfully.
 111          */
 112         Ip4Address(const Ip4Address& rhs);
 113
 114         /**
 115          * This destructor overrides Tizen::Base::Object::~Object().
 116          *
 117          * @since               2.0
 118          */
 119         virtual ~Ip4Address(void);
 120
 121 public:
 122         /**
 123          * Gets the address family to which the %Ip4Address belongs.
 124          *
 125          * @since               2.0
 126          *
 127          * @return              NET_AF_IPV4
 128          */
 129         NetAddressFamily GetNetAddressFamily(void) const;
 130
 131         /**
 132          * Gets the raw IP address.
 133          *
 134          * @since               2.0
 135          *
 136          * @return              An error code
 137          * @param[out]  ipAddr                  A ByteBuffer object containing the raw IP address
 138          * @exception   E_SUCCESS               The method is successful.
 139          * @exception   E_OVERFLOW              The length of the remaining bytes of @c ipAddr is less than @c 4.
 140          * @remarks             This method returns the raw IP address of the %Ip4Address object. The result is in host byte order. This method writes the raw address
 141          *                              in the buffer parameter, starting from the current position. After the operation, the position of the buffer is incremented by the number
 142          *                              of bytes successfully written even if the operation fails. The new position cannot be larger than the original limit.
 143          */
 144         result GetAddress(Tizen::Base::ByteBuffer& ipAddr) const;
 145
 146         /**
 147          * Gets the raw IP address as an integer. @n
 148          * The result is in host byte order.
 149          *
 150          * @since               2.0
 151          *
 152          * @return              An error code
 153          * @param[out]  ipAddr                          An unsigned @c long integer containing the raw IP address
 154          * @exception   E_SUCCESS                       The method is successful.
 155          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 156          * @see                 IpAddress::NetworkToHostOrder()
 157          * @see                 IpAddress::HostToNetworkOrder()
 158          */
 159         result GetAddress(unsigned long& ipAddr) const;
 160
 161         /**
 162          * Gets the IP address of the endpoint in textual presentation. @n
 163          * An endpoint consists of an IP address and a port.
 164          *
 165          * @since               2.0
 166          *
 167          * @return              The %Ip4Address, @n
 168          *                              else a null string if the address is not set
 169          * @remarks             %Ip4Address is in the standard dot-decimal notation.
 170          */
 171         Tizen::Base::String ToString(void) const;
 172
 173         /**
 174          * Creates and returns a copy of this instance.
 175          *
 176          * @since 2.0
 177          *
 178          * @return              The copy of this instance
 179          * @remarks             The GetLastResult() method is used to check whether the %IpAddress instance is copied successfully.
 180          */
 181         virtual IpAddress* CloneN(void) const;
 182
 183         /**
 184          * Copying of objects using this copy assignment operator is allowed.
 185          *
 186          * @since 2.0
 187          *
 188          * @return              The reference of this instance
 189          * @param[in]   rhs An instance of %Ip4Address
 190          */
 191         Ip4Address& operator =(const Ip4Address& rhs);
 192
 193         /**
 194          * Compares the specified instance of %Ip4Address with the calling instance.
 195          *
 196          * @since               2.0
 197          *
 198          * @return              @c true if the values match, @n
 199          *                              else @c false
 200          * @param[in]   rhs     The other Object to be compared
 201          * @see                 Object::Equals()
 202          */
 203         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 204
 205         /**
 206          * Gets the hash value of the current instance.
 207          *
 208          * @since               2.0
 209          *
 210          * @return      The current instance's hash value
 211          */
 212         virtual int GetHashCode(void) const;
 213
 214 private:
 215         /**
 216          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 217          */
 218         Ip4Address(void);
 219
 220 private:
 221         _Ip4AddressImpl* __pIp4AddressImpl;
 222
 223         friend class _Ip4AddressImpl;
 224 }; // Ip4Address
 225
 226 } } //Tizen::Net
 227
 228 #endif // _FNET_IP4_ADDRESS_H_