Introduce PPB_UDPSocket_Dev.

ppapi/api/dev/ppb_udp_socket_dev.idl

Index: ppapi/api/dev/ppb_udp_socket_dev.idl
diff --git a/ppapi/api/dev/ppb_udp_socket_dev.idl b/ppapi/api/dev/ppb_udp_socket_dev.idl
new file mode 100644
index 0000000000000000000000000000000000000000..5f628e499dfb59a86dd70fc2763d1e8b538e5675
--- /dev/null
+++ b/ppapi/api/dev/ppb_udp_socket_dev.idl
@@ -0,0 +1,113 @@
+/* Copyright (c) 2013 The Chromium Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+/**
+ * This file defines the <code>PPB_UDPSocket_Dev</code> interface.
+ * TODO(yzshen): Tidy up the document.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  M29 = 0.1
+};
+
+[assert_size(4)]
+enum PP_UDPSocket_Option_Dev {
+  // Allows the socket to share the local address to which it will be bound with
+  // other processes. Value's type should be PP_VARTYPE_BOOL.
+  PP_UDPSOCKET_OPTION_ADDRESS_REUSE = 0,
+
+  // Allows sending and receiving packets to and from broadcast addresses.
+  // Value's type should be PP_VARTYPE_BOOL.
+  PP_UDPSOCKET_OPTION_BROADCAST = 1,
+
+  // Specifies the total per-socket buffer space reserved for sends. Value's
+  // type should be PP_VARTYPE_INT32.
+  // Note: This is only treated as a hint for the browser to set the buffer
+  // size. Even if SetOption() reports that this option has been successfully
+  // set, the browser doesn't guarantee to conform to it.

[bbudge, 2013/06/12 18:52:37]

s/guarantee to/guarantee it will/
Here and below.

[yzshen1, 2013/06/12 19:32:53]

Done.

+  PP_UDPSOCKET_OPTION_SEND_BUFFER_SIZE = 2,
+
+  // Specifies the total per-socket buffer space reserved for receives. Value's
+  // type should be PP_VARTYPE_INT32.
+  // Note: This is only treated as a hint for the browser to set the buffer
+  // size. Even if SetOption() reports that this option has been successfully
+  // set, the browser doesn't guarantee to conform to it.
+  PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3,
+
+  // Specifies the receiving timeout. Value's type should be PP_VARTYPE_DOUBLE
+  // which is in seconds. 0 (the default value) means the operation will never
+  // timeout.
+  PP_UDPSOCKET_OPTION_RECV_TIMEOUT = 4

[bbudge, 2013/06/12 18:52:37]

Remove?

[yzshen1, 2013/06/12 19:32:53]

Done.

+};
+
+interface PPB_UDPSocket_Dev {
+  /**
+   * Creates a UDP socket resource.
+   */
+  PP_Resource Create([in] PP_Instance instance);
+
+  /**
+   * Determines if a given resource is a UDP socket.
+   */
+  PP_Bool IsUDPSocket([in] PP_Resource resource);
+
+  /**
+   * Binds to the address given by |addr|, which is a PPB_NetAddress_Dev
+   * resource.
+   */
+  int32_t Bind([in] PP_Resource udp_socket,
+               [in] PP_Resource addr,
+               [in] PP_CompletionCallback callback);
+
+  /**
+   * Returns the address that the socket has bound to, as a PPB_NetAddress_Dev
+   * resource.  A successful call to Bind must be called first. Returns 0 if
+   * Bind fails, or if Close has been called.
+   */
+  PP_Resource GetBoundAddress([in] PP_Resource udp_socket);
+
+  /**
+   * Performs a non-blocking recvfrom call on socket.
+   * Bind must be called first. |callback| is invoked when recvfrom reads data.
+   * |addr| will store a PPB_NetAddress_Dev resource on success.
+   */
+  int32_t RecvFrom([in] PP_Resource udp_socket,
+                   [out] str_t buffer,
+                   [in] int32_t num_bytes,
+                   [out] PP_Resource addr,
+                   [in] PP_CompletionCallback callback);
+
+  /**
+   * Performs a non-blocking sendto call on the socket created and bound (has
+   * already called Bind). |addr| is a PPB_NetAddress_Dev resource indicating

[bbudge, 2013/06/12 18:52:37]

A little awkward - why not use the wording from RecvFrom above? i.e.
* Performs a non-blocking sendto call on socket.
* Bind must be called first. |addr| is a PPB_NetAddress_Dev resource holding
* the target address. |callback| is invoked when SendTo completes.

[yzshen1, 2013/06/12 19:32:53]

Done. Thanks!
On 2013/06/12 18:52:37, bbudge1 wrote:

+   * the target address. The callback |callback| is invoked when sendto
+   * completes.
+   */
+  int32_t SendTo([in] PP_Resource udp_socket,
+                 [in] str_t buffer,
+                 [in] int32_t num_bytes,
+                 [in] PP_Resource addr,
+                 [in] PP_CompletionCallback callback);
+
+  /**
+   * Cancels all pending reads and writes, and closes the socket.
+   */
+  void Close([in] PP_Resource udp_socket);
+
+  /**
+   * Sets a socket option to |udp_socket|. Should be called before Bind().
+   * Possible values for |name|, |value| and |value|'s type are described in

[bbudge, 2013/06/12 18:52:37]

Maybe this would be a little clearer:
* See the PP_UDPSocketOption_Dev description for option names
* value types, and allowed values.

[yzshen1, 2013/06/12 19:32:53]

Done.

+   * PP_UDPSocketOption_Dev description. If no error occurs, returns PP_OK.

[bbudge, 2013/06/12 18:52:37]

s/If no error occurs, returns PP_OK/Returns PP_OK on success.

[yzshen1, 2013/06/12 19:32:53]

Thanks!

Sorry for bad comments. :) Some of them were from the private API but some of
them were introduced by me.

I am planning to have a separate CL to tidy up the document (adding tags such as
@param and clarifying some more things). I will send to you for review.

On 2013/06/12 18:52:37, bbudge1 wrote:

+   * Otherwise, returns PP_ERROR_BADRESOURCE (if bad |udp_socket| provided),
+   * PP_ERROR_BADARGUMENT (if bad name/value/value's type provided) or
+   * PP_ERROR_FAILED in the case of internal errors.
+   */
+  int32_t SetOption([in] PP_Resource udp_socket,
+                    [in] PP_UDPSocket_Option_Dev name,
+                    [in] PP_Var value,
+                    [in] PP_CompletionCallback callback);
+};