inc/FNetDns.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                FNetDns.h
  20  * @brief               This is the header file for the %Dns class.
  21  *
  22  * This header file contains the declarations of the %Dns class.
  23  */
  24 #ifndef _FNET_DNS_H_
  25 #define _FNET_DNS_H_
  26
  27 #include <FBaseResult.h>
  28 #include <FNetIpAddress.h>
  29 #include <FNetIpHostEntry.h>
  30 #include <FNetNetConnection.h>
  31 #include <FNetIDnsEventListener.h>
  32
  33 namespace Tizen { namespace Net
  34 {
  35 class _DnsImpl;
  36
  37 /**
  38  * @class       Dns
  39  * @brief       This class provides a way to access the resolver of the Domain Name %System.
  40  *
  41  * @since       2.0
  42  *
  43  * The %Dns class represents a request for information from a DNS server. A DNS request can be one of two types, represented by the GetHostByAddress()
  44  *                      and GetHostByName() methods. The %GetHostByAddress() method represents a request for the DNS information about a host, while the %GetHostByName()
  45  *                      method represents a request for the DNS host information for an IP address. Both requests can be made in an asynchronous mode.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/domain_name_system_access.htm">Domain Name System Access</a>.
  48  *
  49  * The following example demonstrates how to use the %Dns class.
  50  *
  51  * @code
  52  *
  53  *      #include <FBase.h>
  54  *      #include <FNet.h>
  55  *
  56  *      using namespace Tizen::Base;
  57  *      using namespace Tizen::Base::Collection;
  58  *      using namespace Tizen::Net;
  59  *
  60  *      class MyClass
  61  *        : public Object
  62  *        , public IDnsEventListener
  63  *      {
  64  *         public:
  65  *                MyClass(void) {}
  66  *                ~MyClass(void) {}
  67  *
  68  *                // IDnsEventListener
  69  *                void OnDnsResolutionCompletedN(IpHostEntry* pIpHostEntry, result r);
  70  *
  71  *                void GetHostByName(void);
  72  *      };
  73  *
  74  *      void
  75  *      MyClass::OnDnsResolutionCompletedN(IpHostEntry* pIpHostEntry, result r)
  76  *      {
  77  *              if (pIpHostEntry == null)
  78  *              {
  79  *                      return;
  80  *              }
  81  *
  82  *              IList* pAddressList = pIpHostEntry->GetAddressList();
  83  *              if (pAddressList != null)
  84  *              {
  85  *                      int count = pAddressList->GetCount();
  86  *
  87  *                      for (int i = 0; i<count; i++)
  88  *                      {
  89  *                              IpAddress* pIpAddress = (IpAddress*)(pAddressList->GetAt(i));
  90  *                              AppLog("IpAddress no.%d = [%ls]\n", i, pIpAddress->ToString().GetPointer());
  91  *                      }
  92  *              }
  93  *
  94  *              IList* pAliasList = pIpHostEntry->GetAliasList();
  95  *              if (pAliasList != null)
  96  *              {
  97  *                      int count = pAliasList->GetCount();
  98  *
  99  *                      for (int i = 0; i<count; i++)
 100  *                      {
 101  *                              String* pAlias = (String*)(pAliasList->GetAt(i));
 102  *                              AppLog("Alias no.%d = [%ls]\n", i, pAlias->GetPointer());
 103  *                      }
 104  *              }
 105  *
 106  *              delete pIpHostEntry;
 107  *      }
 108  *
 109  *      void
 110  *      MyClass::GetHostByName(void)
 111  *      {
 112  *              Dns* pDns = new Dns();
 113  *              result r = pDns->Construct(*this);
 114  *              if (IsFailed(r))
 115  *              {
 116  *                      delete pDns;
 117  *                      return;
 118  *              }
 119  *
 120  *              r = pDns->GetHostByName(L"www.tizen.org");
 121  *
 122  *              // Wait OnDnsResolutionCompletedN() event
 123  *
 124  *              delete pDns;
 125  *      }
 126  *
 127  * @endcode
 128  */
 129 class _OSP_EXPORT_ Dns
 130         : public Tizen::Base::Object
 131 {
 132 public:
 133         /**
 134          * 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.
 135          *
 136          * @since               2.0
 137          *
 138          * @remarks             After creating an instance of this class, one of the Construct() methods must be called explicitly to initialize this instance.
 139          */
 140         Dns(void);
 141
 142         /**
 143          * This destructor overrides Tizen::Base::Object::~Object().
 144          *
 145          * @since                       2.0
 146          */
 147         virtual ~Dns(void);
 148
 149         /**
 150          * Initializes this instance of %Dns with the specified parameters.
 151          *
 152          * @since               2.0
 153          *
 154          * @return              An error code
 155          * @param[in]   netConnection                   A NetConnection on which the DNS request executes
 156          * @param[in]   listener                                A reference to IDnsEventListener
 157          * @exception   E_SUCCESS                               The method is successful.
 158          * @exception   E_INVALID_ARG                   The specified @c netConnection contains an invalid value.
 159          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 160          * @exception   E_SYSTEM                                An internal error has occurred.
 161          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 162          *                                                                              because the caller thread is a worker thread.
 163          */
 164         result Construct(const NetConnection& netConnection, IDnsEventListener& listener);
 165
 166         /**
 167          * Initializes this instance of %Dns with the specified @c listener.
 168          *
 169      * @since           2.0
 170          *
 171          * @return              An error code
 172          * @param[in]   listener                                A reference to IDnsEventListener
 173          * @exception   E_SUCCESS                               The method is successful.
 174          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 175          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 176          * @exception   E_SYSTEM                                An internal error has occurred.
 177          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 178          *                                                                              because the caller thread is a worker thread.
 179          */
 180         result Construct(IDnsEventListener& listener);
 181
 182 public:
 183         /**
 184          * Requests a DNS lookup by host name. @n
 185          * The %GetHostByName() method is asynchronous.
 186          *
 187          * @since               2.0
 188          *
 189          * @privlevel   public
 190          * @privilege   %http://tizen.org/privilege/dns
 191          *
 192          * @return              An error code
 193          * @param[in]   hostName                                The DNS name of the host
 194          * @exception   E_SUCCESS                               The method is successful.
 195          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 196          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 197          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 198          * @exception   E_NETWORK_UNAVAILABLE   The network is unavailable.
 199          * @exception   E_CONNECTION_FAILED             The network connection has failed.
 200          * @exception   E_OPERATION_FAILED              Requested but an error is received while waiting for the response.
 201          * @exception   E_SYSTEM                                An internal error has occurred.
 202          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 203          *
 204          * @remarks             Only one query is processed at a time in this instance.
 205          *              Multiple queries may be discarded.
 206          */
 207         result GetHostByName(const Tizen::Base::String& hostName);
 208
 209         /**
 210          * Requests a DNS lookup by IP address. @n
 211          * The %GetHostByAddress() method is asynchronous.
 212          *
 213          * @since               2.0
 214          *
 215          * @privlevel   public
 216          * @privilege   %http://tizen.org/privilege/dns
 217          *
 218          * @return              An error code
 219          * @param[in]   ipAddress                               An IP address
 220          * @exception   E_SUCCESS                               The method is successful.
 221          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 222          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 223          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 224          * @exception   E_NETWORK_UNAVAILABLE   The network is unavailable.
 225          * @exception   E_CONNECTION_FAILED             The network connection has failed.
 226          * @exception   E_OPERATION_FAILED              Requested but an error is received while waiting for the response.
 227          * @exception   E_SYSTEM                                An internal error has occurred.
 228          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 229          * @remarks             Only one query is processed at a time in this instance.
 230          *              Multiple queries may be discarded.
 231          */
 232         result GetHostByAddress(const IpAddress& ipAddress);
 233
 234 private:
 235         /*
 236          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 237          *
 238          * @param[in]   rhs                     An instance of %Dns
 239          */
 240         Dns(const Dns& rhs);
 241
 242         /*
 243          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 244          *
 245          * @param[in]   rhs                     An instance of %Dns
 246          */
 247         Dns& operator =(const Dns& rhs);
 248
 249 private:
 250         _DnsImpl* __pDnsImpl;
 251
 252         friend class _DnsImpl;
 253 }; // Dns
 254
 255 } } //Tizen::Net
 256
 257 #endif // _FNET_DNS_H_