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
6/* From ppb_tcp_socket.idl modified Fri Sep 20 09:58:19 2013. */
7
8#ifndef PPAPI_C_PPB_TCP_SOCKET_H_
9#define PPAPI_C_PPB_TCP_SOCKET_H_
10
11#include "ppapi/c/pp_bool.h"
12#include "ppapi/c/pp_completion_callback.h"
13#include "ppapi/c/pp_instance.h"
14#include "ppapi/c/pp_macros.h"
15#include "ppapi/c/pp_resource.h"
16#include "ppapi/c/pp_stdint.h"
17#include "ppapi/c/pp_var.h"
18
19#define PPB_TCPSOCKET_INTERFACE_1_0 "PPB_TCPSocket;1.0"
20#define PPB_TCPSOCKET_INTERFACE_1_1 "PPB_TCPSocket;1.1"
21#define PPB_TCPSOCKET_INTERFACE PPB_TCPSOCKET_INTERFACE_1_1
22
23/**
24 * @file
25 * This file defines the <code>PPB_TCPSocket</code> interface.
26 */
27
28
29/**
30 * @addtogroup Enums
31 * @{
32 */
33/**
34 * Option names used by <code>SetOption()</code>.
35 */
36typedef enum {
37  /**
38   * Disables coalescing of small writes to make TCP segments, and instead
39   * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
40   * This option can only be set after a successful <code>Connect()</code> call.
41   */
42  PP_TCPSOCKET_OPTION_NO_DELAY = 0,
43  /**
44   * Specifies the total per-socket buffer space reserved for sends. Value's
45   * type should be <code>PP_VARTYPE_INT32</code>.
46   * This option can only be set after a successful <code>Connect()</code> call.
47   *
48   * Note: This is only treated as a hint for the browser to set the buffer
49   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
50   * guarantee it will conform to the size.
51   */
52  PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
53  /**
54   * Specifies the total per-socket buffer space reserved for receives. Value's
55   * type should be <code>PP_VARTYPE_INT32</code>.
56   * This option can only be set after a successful <code>Connect()</code> call.
57   *
58   * Note: This is only treated as a hint for the browser to set the buffer
59   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
60   * guarantee it will conform to the size.
61   */
62  PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
63} PP_TCPSocket_Option;
64PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TCPSocket_Option, 4);
65/**
66 * @}
67 */
68
69/**
70 * @addtogroup Interfaces
71 * @{
72 */
73/**
74 * The <code>PPB_TCPSocket</code> interface provides TCP socket operations.
75 *
76 * Permissions: Apps permission <code>socket</code> with subrule
77 * <code>tcp-connect</code> is required for <code>Connect()</code>; subrule
78 * <code>tcp-listen</code> is required for <code>Listen()</code>.
79 * For more details about network communication permissions, please see:
80 * http://developer.chrome.com/apps/app_network.html
81 */
82struct PPB_TCPSocket_1_1 {
83  /**
84   * Creates a TCP socket resource.
85   *
86   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
87   * a module.
88   *
89   * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
90   * on failure.
91   */
92  PP_Resource (*Create)(PP_Instance instance);
93  /**
94   * Determines if a given resource is a TCP socket.
95   *
96   * @param[in] resource A <code>PP_Resource</code> to check.
97   *
98   * @return <code>PP_TRUE</code> if the input is a
99   * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise.
100   */
101  PP_Bool (*IsTCPSocket)(PP_Resource resource);
102  /**
103   * Binds the socket to the given address. The socket must not be bound.
104   *
105   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
106   * socket.
107   * @param[in] addr A <code>PPB_NetAddress</code> resource.
108   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
109   * completion.
110   *
111   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
112   * including (but not limited to):
113   * - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use.
114   * - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid.
115   */
116  int32_t (*Bind)(PP_Resource tcp_socket,
117                  PP_Resource addr,
118                  struct PP_CompletionCallback callback);
119  /**
120   * Connects the socket to the given address. The socket must not be listening.
121   * Binding the socket beforehand is optional.
122   *
123   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
124   * socket.
125   * @param[in] addr A <code>PPB_NetAddress</code> resource.
126   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
127   * completion.
128   *
129   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
130   * including (but not limited to):
131   * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
132   *   permissions.
133   * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
134   *   unreachable.
135   * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
136   *   refused.
137   * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
138   * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
139   *   out.
140   *
141   * Since version 1.1, if the socket is listening/connected or has a pending
142   * listen/connect request, <code>Connect()</code> will fail without starting a
143   * connection attempt; otherwise, any failure during the connection attempt
144   * will cause the socket to be closed.
145   */
146  int32_t (*Connect)(PP_Resource tcp_socket,
147                     PP_Resource addr,
148                     struct PP_CompletionCallback callback);
149  /**
150   * Gets the local address of the socket, if it is bound.
151   *
152   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
153   * socket.
154   *
155   * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
156   */
157  PP_Resource (*GetLocalAddress)(PP_Resource tcp_socket);
158  /**
159   * Gets the remote address of the socket, if it is connected.
160   *
161   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
162   * socket.
163   *
164   * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
165   */
166  PP_Resource (*GetRemoteAddress)(PP_Resource tcp_socket);
167  /**
168   * Reads data from the socket. The socket must be connected. It may perform a
169   * partial read.
170   *
171   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
172   * socket.
173   * @param[out] buffer The buffer to store the received data on success. It
174   * must be at least as large as <code>bytes_to_read</code>.
175   * @param[in] bytes_to_read The number of bytes to read.
176   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
177   * completion.
178   *
179   * @return A non-negative number on success to indicate how many bytes have
180   * been read, 0 means that end-of-file was reached; otherwise, an error code
181   * from <code>pp_errors.h</code>.
182   */
183  int32_t (*Read)(PP_Resource tcp_socket,
184                  char* buffer,
185                  int32_t bytes_to_read,
186                  struct PP_CompletionCallback callback);
187  /**
188   * Writes data to the socket. The socket must be connected. It may perform a
189   * partial write.
190   *
191   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
192   * socket.
193   * @param[in] buffer The buffer containing the data to write.
194   * @param[in] bytes_to_write The number of bytes to write.
195   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
196   * completion.
197   *
198   * @return A non-negative number on success to indicate how many bytes have
199   * been written; otherwise, an error code from <code>pp_errors.h</code>.
200   */
201  int32_t (*Write)(PP_Resource tcp_socket,
202                   const char* buffer,
203                   int32_t bytes_to_write,
204                   struct PP_CompletionCallback callback);
205  /**
206   * Starts listening. The socket must be bound and not connected.
207   *
208   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
209   * socket.
210   * @param[in] backlog A hint to determine the maximum length to which the
211   * queue of pending connections may grow.
212   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
213   * completion.
214   *
215   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
216   * including (but not limited to):
217   * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
218   *   permissions.
219   * - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already listening
220   *   on the same port.
221   */
222  int32_t (*Listen)(PP_Resource tcp_socket,
223                    int32_t backlog,
224                    struct PP_CompletionCallback callback);
225  /**
226   * Accepts a connection. The socket must be listening.
227   *
228   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
229   * socket.
230   * @param[out] accepted_tcp_socket Stores the accepted TCP socket on success.
231   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
232   * completion.
233   *
234   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
235   * including (but not limited to):
236   * - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted.
237   */
238  int32_t (*Accept)(PP_Resource tcp_socket,
239                    PP_Resource* accepted_tcp_socket,
240                    struct PP_CompletionCallback callback);
241  /**
242   * Cancels all pending operations and closes the socket. Any pending callbacks
243   * will still run, reporting <code>PP_ERROR_ABORTED</code> if pending IO was
244   * interrupted. After a call to this method, no output buffer pointers passed
245   * into previous <code>Read()</code> or <code>Accept()</code> calls will be
246   * accessed. It is not valid to call <code>Connect()</code> or
247   * <code>Listen()</code> again.
248   *
249   * The socket is implicitly closed if it is destroyed, so you are not required
250   * to call this method.
251   *
252   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
253   * socket.
254   */
255  void (*Close)(PP_Resource tcp_socket);
256  /**
257   * Sets a socket option on the TCP socket.
258   * Please see the <code>PP_TCPSocket_Option</code> description for option
259   * names, value types and allowed values.
260   *
261   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
262   * socket.
263   * @param[in] name The option to set.
264   * @param[in] value The option value to set.
265   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
266   * completion.
267   *
268   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
269   */
270  int32_t (*SetOption)(PP_Resource tcp_socket,
271                       PP_TCPSocket_Option name,
272                       struct PP_Var value,
273                       struct PP_CompletionCallback callback);
274};
275
276typedef struct PPB_TCPSocket_1_1 PPB_TCPSocket;
277
278struct PPB_TCPSocket_1_0 {
279  PP_Resource (*Create)(PP_Instance instance);
280  PP_Bool (*IsTCPSocket)(PP_Resource resource);
281  int32_t (*Connect)(PP_Resource tcp_socket,
282                     PP_Resource addr,
283                     struct PP_CompletionCallback callback);
284  PP_Resource (*GetLocalAddress)(PP_Resource tcp_socket);
285  PP_Resource (*GetRemoteAddress)(PP_Resource tcp_socket);
286  int32_t (*Read)(PP_Resource tcp_socket,
287                  char* buffer,
288                  int32_t bytes_to_read,
289                  struct PP_CompletionCallback callback);
290  int32_t (*Write)(PP_Resource tcp_socket,
291                   const char* buffer,
292                   int32_t bytes_to_write,
293                   struct PP_CompletionCallback callback);
294  void (*Close)(PP_Resource tcp_socket);
295  int32_t (*SetOption)(PP_Resource tcp_socket,
296                       PP_TCPSocket_Option name,
297                       struct PP_Var value,
298                       struct PP_CompletionCallback callback);
299};
300/**
301 * @}
302 */
303
304#endif  /* PPAPI_C_PPB_TCP_SOCKET_H_ */
305
306