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 int32_t SendTo(const char* buffer, 129 int32_t num_bytes, 130 const NetAddress& addr, 131 const CompletionCallback& callback); 132 133 /// Cancels all pending reads and writes, and closes the socket. Any pending 134 /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if 135 /// pending IO was interrupted. After a call to this method, no output 136 /// paramters passed into previous <code>RecvFrom()</code> calls will be 137 /// accessed. It is not valid to call <code>Bind()</code> again. 138 /// 139 /// The socket is implicitly closed if it is destroyed, so you are not 140 /// required to call this method. 141 void Close(); 142 143 /// Sets a socket option on the UDP socket. 144 /// Please see the <code>PP_UDPSocket_Option</code> description for option 145 /// names, value types and allowed values. 146 /// 147 /// @param[in] name The option to set. 148 /// @param[in] value The option value to set. 149 /// @param[in] callback A <code>CompletionCallback</code> to be called upon 150 /// completion. 151 /// 152 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 153 int32_t SetOption(PP_UDPSocket_Option name, 154 const Var& value, 155 const CompletionCallback& callback); 156 }; 157 158 } // namespace pp 159 160 #endif // PPAPI_CPP_UDP_SOCKET_H_ 161