Pepper_31_C++_interfaces
udp_socket.h
Go to the documentation of this file.
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.
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>.
111  char* buffer,
112  int32_t num_bytes,
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_
int32_t SetOption(PP_UDPSocket_Option name, const Var &value, const CompletionCallback &callback)
NetAddress GetBoundAddress()
The NetAddress class represents a network address.
Definition: net_address.h:18
int32_t SendTo(const char *buffer, int32_t num_bytes, const NetAddress &addr, const CompletionCallback &callback)
virtual ~UDPSocket()
The destructor.
PassRef
Definition: pass_ref.h:17
int32_t RecvFrom(char *buffer, int32_t num_bytes, const CompletionCallbackWithOutput< NetAddress > &callback)
A generic type used for passing data types between the module and the page.
Definition: var.h:20
static bool IsAvailable()
int32_t Bind(const NetAddress &addr, const CompletionCallback &callback)
A reference counted module resource.
Definition: resource.h:18
UDPSocket & operator=(const UDPSocket &other)