ppapi/cpp/host_resolver.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_HOST_RESOLVER_H_
   6 #define PPAPI_CPP_HOST_RESOLVER_H_
   7
   8 #include "ppapi/c/pp_stdint.h"
   9 #include "ppapi/c/ppb_host_resolver.h"
  10 #include "ppapi/cpp/net_address.h"
  11 #include "ppapi/cpp/pass_ref.h"
  12 #include "ppapi/cpp/resource.h"
  13 #include "ppapi/cpp/var.h"
  14
  15 namespace pp {
  16
  17 class CompletionCallback;
  18 class InstanceHandle;
  19
  20 /// The <code>HostResolver</code> class supports host name resolution.
  21 ///
  22 /// Permissions: In order to run <code>Resolve()</code>, apps permission
  23 /// <code>socket</code> with subrule <code>resolve-host</code> is required.
  24 /// For more details about network communication permissions, please see:
  25 /// http://developer.chrome.com/apps/app_network.html
  26 class HostResolver : public Resource {
  27  public:
  28   /// Default constructor for creating an is_null() <code>HostResolver</code>
  29   /// object.
  30   HostResolver();
  31
  32   /// A constructor used to create a <code>HostResolver</code> object.
  33   ///
  34   /// @param[in] instance The instance with which this resource will be
  35   /// associated.
  36   explicit HostResolver(const InstanceHandle& instance);
  37
  38   /// A constructor used when you have received a <code>PP_Resource</code> as a
  39   /// return value that has had 1 ref added for you.
  40   ///
  41   /// @param[in] resource A <code>PPB_HostResolver</code> resource.
  42   HostResolver(PassRef, PP_Resource resource);
  43
  44   /// The copy constructor for <code>HostResolver</code>.
  45   ///
  46   /// @param[in] other A reference to another <code>HostResolver</code>.
  47   HostResolver(const HostResolver& other);
  48
  49   /// The destructor.
  50   virtual ~HostResolver();
  51
  52   /// The assignment operator for <code>HostResolver</code>.
  53   ///
  54   /// @param[in] other A reference to another <code>HostResolver</code>.
  55   ///
  56   /// @return A reference to this <code>HostResolver</code> object.
  57   HostResolver& operator=(const HostResolver& other);
  58
  59   /// Static function for determining whether the browser supports the
  60   /// <code>PPB_HostResolver</code> interface.
  61   ///
  62   /// @return true if the interface is available, false otherwise.
  63   static bool IsAvailable();
  64
  65   /// Requests resolution of a host name. If the call completes successully, the
  66   /// results can be retrieved by <code>GetCanonicalName()</code>,
  67   /// <code>GetNetAddressCount()</code> and <code>GetNetAddress()</code>.
  68   ///
  69   /// @param[in] host The host name (or IP address literal) to resolve.
  70   /// @param[in] port The port number to be set in the resulting network
  71   /// addresses.
  72   /// @param[in] hint A <code>PP_HostResolver_Hint</code> structure
  73   /// providing hints for host resolution.
  74   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  75   /// completion.
  76   ///
  77   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
  78   /// <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
  79   /// required permissions. <code>PP_ERROR_NAME_NOT_RESOLVED</code> will be
  80   /// returned if the host name couldn't be resolved.
  81   int32_t Resolve(const char* host,
  82                   uint16_t port,
  83                   const PP_HostResolver_Hint& hint,
  84                   const CompletionCallback& callback);
  85
  86   /// Gets the canonical name of the host.
  87   ///
  88   /// @return A string <code>Var</code> on success, which is an empty string
  89   /// if <code>PP_HOSTRESOLVER_FLAG_CANONNAME</code> is not set in the hint
  90   /// flags when calling <code>Resolve()</code>; an undefined <code>Var</code>
  91   /// if there is a pending <code>Resolve()</code> call or the previous
  92   /// <code>Resolve()</code> call failed.
  93   Var GetCanonicalName() const;
  94
  95   /// Gets the number of network addresses.
  96   ///
  97   /// @return The number of available network addresses on success; 0 if there
  98   /// is a pending <code>Resolve()</code> call or the previous
  99   /// <code>Resolve()</code> call failed.
 100   uint32_t GetNetAddressCount() const;
 101
 102   /// Gets a network address.
 103   ///
 104   /// @param[in] index An index indicating which address to return.
 105   ///
 106   /// @return A <code>NetAddress</code> object. The object will be null
 107   /// (i.e., is_null() returns true) if there is a pending
 108   /// <code>Resolve()</code> call or the previous <code>Resolve()</code> call
 109   /// failed, or the specified index is out of range.
 110   NetAddress GetNetAddress(uint32_t index) const;
 111 };
 112
 113 }  // namespace pp
 114
 115 #endif  // PPAPI_CPP_HOST_RESOLVER_H_