Pepper_47_C++_interfaces
tcp_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_TCP_SOCKET_H_
6 #define PPAPI_CPP_TCP_SOCKET_H_
7 
8 #include "ppapi/c/ppb_tcp_socket.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 
18 template <typename T> class CompletionCallbackWithOutput;
19 
20 /// The <code>TCPSocket</code> class provides TCP socket operations.
21 ///
22 /// Permissions: Apps permission <code>socket</code> with subrule
23 /// <code>tcp-connect</code> is required for <code>Connect()</code>; subrule
24 /// <code>tcp-listen</code> is required for <code>Listen()</code>.
25 /// For more details about network communication permissions, please see:
26 /// http://developer.chrome.com/apps/app_network.html
27 class TCPSocket : public Resource {
28  public:
29  /// Default constructor for creating an is_null() <code>TCPSocket</code>
30  /// object.
31  TCPSocket();
32 
33  /// A constructor used to create a <code>TCPSocket</code> object.
34  ///
35  /// @param[in] instance The instance with which this resource will be
36  /// associated.
37  explicit TCPSocket(const InstanceHandle& instance);
38 
39  /// A constructor used when you have received a <code>PP_Resource</code> as a
40  /// return value that has had 1 ref added for you.
41  ///
42  /// @param[in] resource A <code>PPB_TCPSocket</code> resource.
43  TCPSocket(PassRef, PP_Resource resource);
44 
45  /// The copy constructor for <code>TCPSocket</code>.
46  ///
47  /// @param[in] other A reference to another <code>TCPSocket</code>.
48  TCPSocket(const TCPSocket& other);
49 
50  /// The destructor.
51  virtual ~TCPSocket();
52 
53  /// The assignment operator for <code>TCPSocket</code>.
54  ///
55  /// @param[in] other A reference to another <code>TCPSocket</code>.
56  ///
57  /// @return A reference to this <code>TCPSocket</code> object.
58  TCPSocket& operator=(const TCPSocket& other);
59 
60  /// Static function for determining whether the browser supports the
61  /// <code>PPB_TCPSocket</code> interface.
62  ///
63  /// @return true if the interface is available, false otherwise.
64  static bool IsAvailable();
65 
66  /// Binds the socket to the given address. The socket must not be bound.
67  ///
68  /// @param[in] addr A <code>NetAddress</code> object.
69  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
70  /// completion.
71  ///
72  /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
73  /// including (but not limited to):
74  /// - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use.
75  /// - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid.
76  int32_t Bind(const NetAddress& addr, const CompletionCallback& callback);
77 
78  /// Connects the socket to the given address. The socket must not be
79  /// listening. Binding the socket beforehand is optional.
80  ///
81  /// @param[in] addr A <code>NetAddress</code> object.
82  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
83  /// completion.
84  ///
85  /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
86  /// including (but not limited to):
87  /// - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
88  /// permissions.
89  /// - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
90  /// unreachable.
91  /// - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
92  /// refused.
93  /// - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
94  /// - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
95  /// out.
96  ///
97  /// Since version 1.1, if the socket is listening/connected or has a pending
98  /// listen/connect request, <code>Connect()</code> will fail without starting
99  /// a connection attempt. Otherwise, any failure during the connection attempt
100  /// will cause the socket to be closed.
101  int32_t Connect(const NetAddress& addr, const CompletionCallback& callback);
102 
103  /// Gets the local address of the socket, if it is bound.
104  ///
105  /// @return A <code>NetAddress</code> object. The object will be null
106  /// (i.e., is_null() returns true) on failure.
107  NetAddress GetLocalAddress() const;
108 
109  /// Gets the remote address of the socket, if it is connected.
110  ///
111  /// @return A <code>NetAddress</code> object. The object will be null
112  /// (i.e., is_null() returns true) on failure.
114 
115  /// Reads data from the socket. The socket must be connected. It may perform a
116  /// partial read.
117  ///
118  /// <strong>Caveat:</strong> You should be careful about the lifetime of
119  /// <code>buffer</code>. Typically you will use a
120  /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime
121  /// of your class. When your class goes out of scope, the callback factory
122  /// will not actually cancel the operation, but will rather just skip issuing
123  /// the callback on your class. This means that if the underlying
124  /// <code>PPB_TCPSocket</code> resource outlives your class, the browser
125  /// will still try to write into your buffer when the operation completes.
126  /// The buffer must be kept valid until then to avoid memory corruption.
127  /// If you want to release the buffer while the <code>Read()</code> call is
128  /// still pending, you should call <code>Close()</code> to ensure that the
129  /// buffer won't be accessed in the future.
130  ///
131  /// @param[out] buffer The buffer to store the received data on success. It
132  /// must be at least as large as <code>bytes_to_read</code>.
133  /// @param[in] bytes_to_read The number of bytes to read.
134  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
135  /// completion.
136  ///
137  /// @return A non-negative number on success to indicate how many bytes have
138  /// been read, 0 means that end-of-file was reached; otherwise, an error code
139  /// from <code>pp_errors.h</code>.
140  int32_t Read(char* buffer,
141  int32_t bytes_to_read,
142  const CompletionCallback& callback);
143 
144  /// Writes data to the socket. The socket must be connected. It may perform a
145  /// partial write.
146  ///
147  /// @param[in] buffer The buffer containing the data to write.
148  /// @param[in] bytes_to_write The number of bytes to write.
149  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
150  /// completion.
151  ///
152  /// @return A non-negative number on success to indicate how many bytes have
153  /// been written; otherwise, an error code from <code>pp_errors.h</code>.
154  int32_t Write(const char* buffer,
155  int32_t bytes_to_write,
156  const CompletionCallback& callback);
157 
158  /// Starts listening. The socket must be bound and not connected.
159  ///
160  /// @param[in] backlog A hint to determine the maximum length to which the
161  /// queue of pending connections may grow.
162  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
163  /// completion.
164  ///
165  /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
166  /// including (but not limited to):
167  /// - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
168  /// permissions.
169  /// - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already
170  /// listening on the same port.
171  int32_t Listen(int32_t backlog,
172  const CompletionCallback& callback);
173 
174  /// Accepts a connection. The socket must be listening.
175  ///
176  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
177  /// called upon completion.
178  ///
179  /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
180  /// including (but not limited to):
181  /// - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted.
183 
184  /// Cancels all pending operations and closes the socket. Any pending
185  /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if
186  /// pending IO was interrupted. After a call to this method, no output buffer
187  /// pointers passed into previous <code>Read()</code> or <code>Accept()</code>
188  /// calls will be accessed. It is not valid to call <code>Connect()</code> or
189  /// <code>Listen()</code> again.
190  ///
191  /// The socket is implicitly closed if it is destroyed, so you are not
192  /// required to call this method.
193  void Close();
194 
195  /// Sets a socket option on the TCP socket.
196  /// Please see the <code>PP_TCPSocket_Option</code> description for option
197  /// names, value types and allowed values.
198  ///
199  /// @param[in] name The option to set.
200  /// @param[in] value The option value to set.
201  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
202  /// completion.
203  ///
204  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
205  int32_t SetOption(PP_TCPSocket_Option name,
206  const Var& value,
207  const CompletionCallback& callback);
208 };
209 
210 } // namespace pp
211 
212 #endif // PPAPI_CPP_TCP_SOCKET_H_
int32_t Listen(int32_t backlog, const CompletionCallback &callback)
Definition: tcp_socket.cc:178
int32_t SetOption(PP_TCPSocket_Option name, const Var &value, const CompletionCallback &callback)
Definition: tcp_socket.cc:214
NetAddress GetLocalAddress() const
Definition: tcp_socket.cc:98
int32_t Bind(const NetAddress &addr, const CompletionCallback &callback)
Definition: tcp_socket.cc:68
int32_t Accept(const CompletionCallbackWithOutput< TCPSocket > &callback)
Definition: tcp_socket.cc:191
int32_t Read(char *buffer, int32_t bytes_to_read, const CompletionCallback &callback)
Definition: tcp_socket.cc:136
static bool IsAvailable()
Definition: tcp_socket.cc:62
int32_t Connect(const NetAddress &addr, const CompletionCallback &callback)
Definition: tcp_socket.cc:81
The NetAddress class represents a network address.
Definition: net_address.h:18
PassRef
Definition: pass_ref.h:17
TCPSocket & operator=(const TCPSocket &other)
Definition: tcp_socket.cc:56
int32_t Write(const char *buffer, int32_t bytes_to_write, const CompletionCallback &callback)
Definition: tcp_socket.cc:157
NetAddress GetRemoteAddress() const
Definition: tcp_socket.cc:117
virtual ~TCPSocket()
The destructor.
Definition: tcp_socket.cc:53
A generic type used for passing data types between the module and the page.
Definition: var.h:21
A reference counted module resource.
Definition: resource.h:20