inc/FNetIpAddress.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                FNetIpAddress.h
  20  * @brief               This is the header file for the %IpAddress class.
  21  *
  22  * This header file contains the declarations of the %IpAddress class.
  23  */
  24 #ifndef _FNET_IP_ADDRESS_H_
  25 #define _FNET_IP_ADDRESS_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FBaseString.h>
  30 #include <FBaseResult.h>
  31 #include <FBaseErrors.h>
  32 #include <FNetSockSocketTypes.h>
  33
  34 namespace Tizen { namespace Net
  35 {
  36 class _IpAddressImpl;
  37 /**
  38  * @class       IpAddress
  39  * @brief       This abstract class encapsulates an Internet Protocol (IP) address and the methods to manipulate it.
  40  *
  41  * @since       2.0
  42  *
  43  *  The %IpAddress class contains the address of a computer on an IP network. Different computers use different conventions for ordering the bytes
  44  *      within multi-byte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the
  45  *      least-significant byte first (known as little-endian order). To work with the computers that use different byte ordering, all integer values sent
  46  *      over the network are sent in network byte order. This class provides methods to change the order. An endpoint includes an IP address
  47  *      and a port.
  48  *
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/net_namespace.htm">Net Guide</a>.
  50  */
  51 class _OSP_EXPORT_ IpAddress
  52         : public Tizen::Base::Object
  53 {
  54 public:
  55         /**
  56          * This destructor overrides Tizen::Base::Object::~Object().
  57          *
  58          * @since       2.0
  59          */
  60         virtual ~IpAddress(void);
  61
  62         /**
  63          * Converts the specified unsigned short address from the host byte order to the network byte order.
  64          *
  65          * @since               2.0
  66          *
  67          * @return              The address as an unsigned @c short value, in the network @c byte order
  68          * @param[in]   host    The IP address to convert, expressed in host @c byte order
  69          *
  70          * @see                 NetworkToHostOrder()
  71          */
  72         static unsigned short HostToNetworkOrder(unsigned short host);
  73
  74         /**
  75          * Converts the specified unsigned long address from the host byte order to the network byte order.
  76          *
  77          * @since               2.0
  78          *
  79          * @return              The address as an unsigned @c long value, in the network @c byte order
  80          * @param[in]   host    The IP address to convert, expressed in the host @c byte order
  81          *
  82          * @see                 NetworkToHostOrder()
  83          */
  84         static unsigned long HostToNetworkOrder(unsigned long host);
  85
  86         /**
  87          * Converts the specified short integer address from network byte order to host byte order.
  88          *
  89          * @since               2.0
  90          *
  91          * @return              The address as an unsigned @c short value, in the host @c byte order
  92          * @param[in]   network         The IP address to convert, expressed in the network @c byte order
  93          *
  94          * @see                 HostToNetworkOrder()
  95          */
  96         static unsigned short NetworkToHostOrder(unsigned short network);
  97
  98         /**
  99          * Converts the specified unsigned long address from the network byte order to the host byte order.
 100          *
 101          * @since               2.0
 102          *
 103          * @return              The address as an unsigned @c long value, in the host @c byte order
 104          * @param[in]   network         The IP address to convert, expressed in the network @c byte order
 105          *
 106          * @see                         HostToNetworkOrder()
 107         */
 108         static unsigned long NetworkToHostOrder(unsigned long network);
 109
 110         /**
 111          * Gets the address family to which the %IpAddress belongs.
 112          *
 113          * @since               2.0
 114          *
 115          * @return              The address family
 116          */
 117         virtual NetAddressFamily GetNetAddressFamily(void) const = 0;
 118
 119         /**
 120          * Gets the raw IP address of the endpoint. @n
 121          * An endpoint includes an IP address and a port.
 122          *
 123          * @since               2.0
 124          *
 125          * @return              An error code
 126          * @param[out]  ipAddr                          A Tizen::Base::ByteBuffer object for getting the raw IP address
 127          * @exception   E_SUCCESS                       The method is successful.
 128          * @exception   E_INVALID_ARG           The specified @c ipAddr is invalid.
 129          * @exception   E_OVERFLOW                      This operation has caused the memory to overflow.
 130          * @remarks             The result @c ipAddr is in the host @c byte order. This method writes the raw address into the buffer parameter, starting from the
 131          *                              current position of the buffer. After the operation, the position of the buffer is incremented by the number of bytes successfully written
 132          *                              even if the operation fails. The new position cannot be larger than the original limit.
 133          */
 134         virtual result GetAddress(Tizen::Base::ByteBuffer& ipAddr) const = 0;
 135
 136         /**
 137          * Gets the IP address of the endpoint as a string. @n
 138          * An endpoint includes an IP address and a port.
 139          *
 140          * @since               2.0
 141          *
 142          * @return              The IP address, @n
 143          *                              else a null string if the address is not set
 144          */
 145         virtual Tizen::Base::String ToString(void) const = 0;
 146
 147         /**
 148          * Creates and returns a copy of this instance.
 149          *
 150          * @since 2.0
 151          *
 152          * @return              The copy of this instance
 153          * @remarks             The GetLastResult() method is used to check whether the %IpAddress instance is copied successfully.
 154          */
 155         virtual IpAddress* CloneN(void) const = 0;
 156
 157 protected:
 158         /**
 159          * This default constructor is intentionally declared as protected because this class cannot be constructed.
 160          *
 161          * @since       2.0
 162          */
 163         IpAddress(void);
 164
 165 protected:
 166         //
 167         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 168         //
 169         // This method is reserved and may change its name at any time without prior notice.
 170         //
 171         // @since 2.0
 172         //
 173         virtual void IpAddress_Reserved1(void) {}
 174
 175         //
 176         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 177         //
 178         // This method is reserved and may change its name at any time without prior notice.
 179         //
 180         // @since 2.0
 181         //
 182         virtual void IpAddress_Reserved2(void) {}
 183
 184         //
 185         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 186         //
 187         // This method is reserved and may change its name at any time without prior notice.
 188         //
 189         // @since 2.0
 190         //
 191         virtual void IpAddress_Reserved3(void) {}
 192
 193         //
 194         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 195         //
 196         // This method is reserved and may change its name at any time without prior notice.
 197         //
 198         // @since 2.0
 199         //
 200         virtual void IpAddress_Reserved4(void) {}
 201
 202         //
 203         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 204         //
 205         // This method is reserved and may change its name at any time without prior notice.
 206         //
 207         // @since 2.0
 208         //
 209         virtual void IpAddress_Reserved5(void) {}
 210
 211 private:
 212         /**
 213          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 214          *
 215          * @param[in]   rhs                     An instance of IpAddress
 216          */
 217         IpAddress(const IpAddress& rhs);
 218
 219         /**
 220          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 221          *
 222          * @param[in]   rhs                             An instance of %IpAddress
 223          */
 224         IpAddress& operator =(const IpAddress& rhs);
 225
 226 protected:
 227         _IpAddressImpl* _pIpAddressImpl;
 228
 229         friend class _IpAddressImpl;
 230 }; // IpAddress
 231
 232 } } //Tizen::Net
 233
 234 #endif // _FNET_IP_ADDRESS_H_