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 the two types, represented by the GetHostByAddress()
  44  * and GetHostByName() methods. The %GetHostByAddress() method represents a request for the DNS information of a host, while the %GetHostByName()
  45  * method represents a request for the DNS host information of an IP address. Both requests can be made in the 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. @n
 135         * For full construction, the Construct() method must be called right after calling this constructor.
 136         *
 137         * @since                2.0
 138         */
 139         Dns(void);
 140
 141    /**
 142         * This destructor overrides Tizen::Base::Object::~Object().
 143         *
 144         * @since                        2.0
 145         */
 146         virtual ~Dns(void);
 147
 148    /**
 149         * Initializes this instance of %Dns with the specified parameters.
 150         *
 151         * @since                2.0
 152         *
 153         * @return               An error code
 154         * @param[in]    netConnection                   The NetConnection on which the DNS request executes
 155         * @param[in]    listener                                A reference to IDnsEventListener
 156         * @exception    E_SUCCESS                               The method is successful.
 157         * @exception    E_INVALID_ARG                   The specified @c netConnection contains an invalid value.
 158         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 159         * @exception    E_SYSTEM                                An internal error has occurred.
 160         * @exception    E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 161         *                                                                               because the caller thread is a worker thread.
 162         */
 163         result Construct(const NetConnection& netConnection, IDnsEventListener& listener);
 164
 165    /**
 166         * Initializes this instance of %Dns with the specified @c listener.
 167         *
 168     * @since            2.0
 169         *
 170         * @return               An error code
 171         * @param[in]    listener                                A reference to IDnsEventListener
 172         * @exception    E_SUCCESS                               The method is successful.
 173         * @exception    E_INVALID_CONNECTION    The network connection is invalid.
 174         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 175         * @exception    E_SYSTEM                                An internal error has occurred.
 176         * @exception    E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 177         *                                                                               because the caller thread is a worker thread.
 178         */
 179         result Construct(IDnsEventListener& listener);
 180
 181 public:
 182    /**
 183         * Requests for a DNS lookup by the host name. @n
 184         * The %GetHostByName() method is asynchronous.
 185         *
 186         * @since                2.0
 187         *
 188         * @privlevel    public
 189         * @privilege    %http://tizen.org/privilege/dns
 190         *
 191         * @return               An error code
 192         * @param[in]    hostName                                The DNS name of the host
 193         * @exception    E_SUCCESS                               The method is successful.
 194         * @exception    E_INVALID_ARG                   The specified input parameter is invalid.
 195         * @exception    E_INVALID_CONNECTION    The network connection is invalid.
 196         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 197         * @exception    E_NETWORK_UNAVAILABLE   The network is unavailable.
 198         * @exception    E_CONNECTION_FAILED             The network connection has failed.
 199         * @exception    E_OPERATION_FAILED              An error has been received while waiting for the response.
 200         * @exception    E_SYSTEM                                An internal 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 has blocked the application from calling this method. @b Since: @b 2.1
 203         * @remarks              Only one query is processed at a time in this instance.
 204         *               Multiple queries may be discarded.
 205         */
 206         result GetHostByName(const Tizen::Base::String& hostName);
 207    /**
 208         * Requests for a DNS lookup by the IP address. @n
 209         * The %GetHostByAddress() method is asynchronous.
 210         *
 211         * @since                2.0
 212         *
 213         * @privlevel    public
 214         * @privilege    %http://tizen.org/privilege/dns
 215         *
 216         * @return               An error code
 217         * @param[in]    ipAddress                               The IP address
 218         * @exception    E_SUCCESS                               The method is successful.
 219         * @exception    E_INVALID_ARG                   The specified input parameter is invalid.
 220         * @exception    E_INVALID_CONNECTION    The network connection is invalid.
 221         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 222         * @exception    E_NETWORK_UNAVAILABLE   The network is unavailable.
 223         * @exception    E_CONNECTION_FAILED             The network connection has failed.
 224         * @exception    E_OPERATION_FAILED              An error has been received while waiting for the response.
 225         * @exception    E_SYSTEM                                An internal error has occurred.
 226         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 227         * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 228         * @remarks              Only one query is processed at a time in this instance.
 229         *               Multiple queries may be discarded.
 230         */
 231         result GetHostByAddress(const IpAddress& ipAddress);
 232
 233 private:
 234         /*
 235          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 236          *
 237          * @param[in]   rhs                     An instance of %Dns
 238          */
 239         Dns(const Dns& rhs);
 240
 241         /*
 242          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 243          *
 244          * @param[in]   rhs                     An instance of %Dns
 245          */
 246         Dns& operator =(const Dns& rhs);
 247
 248 private:
 249         _DnsImpl* __pDnsImpl;
 250
 251         friend class _DnsImpl;
 252 }; // Dns
 253
 254 } } //Tizen::Net
 255
 256 #endif // _FNET_DNS_H_