ppapi/cpp/udp_socket.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_UDP_SOCKET_H_
   6 #define PPAPI_CPP_UDP_SOCKET_H_
   7
   8 #include "ppapi/c/ppb_udp_socket.h"
   9 #include "ppapi/cpp/net_address.h"
  10 #include "ppapi/cpp/pass_ref.h"
  11 #include "ppapi/cpp/resource.h"
  12
  13 namespace pp {
  14
  15 class CompletionCallback;
  16 class InstanceHandle;
  17 class Var;
  18
  19 template <typename T> class CompletionCallbackWithOutput;
  20
  21 /// The <code>UDPSocket</code> class provides UDP socket operations.
  22 ///
  23 /// Permissions: Apps permission <code>socket</code> with subrule
  24 /// <code>udp-bind</code> is required for <code>Bind()</code>; subrule
  25 /// <code>udp-send-to</code> is required for <code>SendTo()</code>.
  26 /// For more details about network communication permissions, please see:
  27 /// http://developer.chrome.com/apps/app_network.html
  28 class UDPSocket : public Resource {
  29  public:
  30   /// Default constructor for creating an is_null() <code>UDPSocket</code>
  31   /// object.
  32   UDPSocket();
  33
  34   /// A constructor used to create a <code>UDPSocket</code> object.
  35   ///
  36   /// @param[in] instance The instance with which this resource will be
  37   /// associated.
  38   explicit UDPSocket(const InstanceHandle& instance);
  39
  40   /// A constructor used when you have received a <code>PP_Resource</code> as a
  41   /// return value that has had 1 ref added for you.
  42   ///
  43   /// @param[in] resource A <code>PPB_UDPSocket</code> resource.
  44   UDPSocket(PassRef, PP_Resource resource);
  45
  46   /// The copy constructor for <code>UDPSocket</code>.
  47   ///
  48   /// @param[in] other A reference to another <code>UDPSocket</code>.
  49   UDPSocket(const UDPSocket& other);
  50
  51   /// The destructor.
  52   virtual ~UDPSocket();
  53
  54   /// The assignment operator for <code>UDPSocket</code>.
  55   ///
  56   /// @param[in] other A reference to another <code>UDPSocket</code>.
  57   ///
  58   /// @return A reference to this <code>UDPSocket</code> object.
  59   UDPSocket& operator=(const UDPSocket& other);
  60
  61   /// Static function for determining whether the browser supports the
  62   /// <code>PPB_UDPSocket</code> interface.
  63   ///
  64   /// @return true if the interface is available, false otherwise.
  65   static bool IsAvailable();
  66
  67   /// Binds the socket to the given address.
  68   ///
  69   /// @param[in] addr A <code>NetAddress</code> object.
  70   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  71   /// completion.
  72   ///
  73   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
  74   /// <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
  75   /// required permissions. <code>PP_ERROR_ADDRESS_IN_USE</code> will be
  76   /// returned if the address is already in use.
  77   int32_t Bind(const NetAddress& addr,
  78                const CompletionCallback& callback);
  79
  80   /// Get the address that the socket is bound to. The socket must be bound.
  81   ///
  82   /// @return A <code>NetAddress</code> object. The object will be null
  83   /// (i.e., is_null() returns true) on failure.
  84   NetAddress GetBoundAddress();
  85
  86   /// Receives data from the socket and stores the source address. The socket
  87   /// must be bound.
  88   ///
  89   /// <strong>Caveat:</strong> You should be careful about the lifetime of
  90   /// <code>buffer</code>. Typically you will use a
  91   /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime
  92   /// of your class. When your class goes out of scope, the callback factory
  93   /// will not actually cancel the operation, but will rather just skip issuing
  94   /// the callback on your class. This means that if the underlying
  95   /// <code>PPB_UDPSocket</code> resource outlives your class, the browser
  96   /// will still try to write into your buffer when the operation completes.
  97   /// The buffer must be kept valid until then to avoid memory corruption.
  98   /// If you want to release the buffer while the <code>RecvFrom()</code> call
  99   /// is still pending, you should call <code>Close()</code> to ensure that the
 100   /// buffer won't be accessed in the future.
 101   ///
 102   /// @param[out] buffer The buffer to store the received data on success. It
 103   /// must be at least as large as <code>num_bytes</code>.
 104   /// @param[in] num_bytes The number of bytes to receive.
 105   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 106   /// called upon completion.
 107   ///
 108   /// @return A non-negative number on success to indicate how many bytes have
 109   /// been received; otherwise, an error code from <code>pp_errors.h</code>.
 110   int32_t RecvFrom(
 111       char* buffer,
 112       int32_t num_bytes,
 113       const CompletionCallbackWithOutput<NetAddress>& callback);
 114
 115   /// Sends data to a specific destination. The socket must be bound.
 116   ///
 117   /// @param[in] buffer The buffer containing the data to send.
 118   /// @param[in] num_bytes The number of bytes to send.
 119   /// @param[in] addr A <code>NetAddress</code> object holding the destination
 120   /// address.
 121   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 122   /// completion.
 123   ///
 124   /// @return A non-negative number on success to indicate how many bytes have
 125   /// been sent; otherwise, an error code from <code>pp_errors.h</code>.
 126   /// <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
 127   /// required permissions.
 128   /// <code>PP_ERROR_INPROGRESS</code> will be returned if the socket is busy
 129   /// sending. The caller should wait until a pending send completes before
 130   /// retrying.
 131   int32_t SendTo(const char* buffer,
 132                  int32_t num_bytes,
 133                  const NetAddress& addr,
 134                  const CompletionCallback& callback);
 135
 136   /// Cancels all pending reads and writes, and closes the socket. Any pending
 137   /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if
 138   /// pending IO was interrupted. After a call to this method, no output
 139   /// paramters passed into previous <code>RecvFrom()</code> calls will be
 140   /// accessed. It is not valid to call <code>Bind()</code> again.
 141   ///
 142   /// The socket is implicitly closed if it is destroyed, so you are not
 143   /// required to call this method.
 144   void Close();
 145
 146   /// Sets a socket option on the UDP socket.
 147   /// Please see the <code>PP_UDPSocket_Option</code> description for option
 148   /// names, value types and allowed values.
 149   ///
 150   /// @param[in] name The option to set.
 151   /// @param[in] value The option value to set.
 152   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 153   /// completion.
 154   ///
 155   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 156   int32_t SetOption(PP_UDPSocket_Option name,
 157                     const Var& value,
 158                     const CompletionCallback& callback);
 159
 160   /// Joins the multicast group with address specified by <code>group</code>
 161   /// parameter, which is expected to be a <code>NetAddress</code> object.
 162   ///
 163   /// @param[in] group A <code>NetAddress</code> corresponding to the network
 164   /// address of the multicast group.
 165   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 166   /// completion.
 167   ///
 168   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 169   int32_t JoinGroup(const NetAddress& group,
 170                     const CompletionCallback callback);
 171
 172   /// Leaves the multicast group with address specified by <code>group</code>
 173   /// parameter, which is expected to be a <code>NetAddress</code> object.
 174   ///
 175   /// @param[in] group A <code>NetAddress</code> corresponding to the network
 176   /// address of the multicast group.
 177   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 178   /// completion.
 179   ///
 180   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 181   int32_t LeaveGroup(const NetAddress& group,
 182                      const CompletionCallback callback);
 183 };
 184
 185 }  // namespace pp
 186
 187 #endif  // PPAPI_CPP_UDP_SOCKET_H_