diff options
Diffstat (limited to 'ppapi/api/dev/ppb_udp_socket_dev.idl')
| -rw-r--r-- | ppapi/api/dev/ppb_udp_socket_dev.idl | 161 |
1 files changed, 124 insertions, 37 deletions
diff --git a/ppapi/api/dev/ppb_udp_socket_dev.idl b/ppapi/api/dev/ppb_udp_socket_dev.idl index a4d7d53..95d02ac 100644 --- a/ppapi/api/dev/ppb_udp_socket_dev.idl +++ b/ppapi/api/dev/ppb_udp_socket_dev.idl @@ -5,7 +5,6 @@ /** * This file defines the <code>PPB_UDPSocket_Dev</code> interface. - * TODO(yzshen): Tidy up the document. */ [generate_thunk] @@ -14,65 +13,125 @@ label Chrome { M29 = 0.1 }; +/** + * Option names used by <code>SetOption()</code>. + */ [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. - // This option can only be set before calling Bind(). + /** + * Allows the socket to share the local address to which it will be bound with + * other processes. Value's type should be <code>PP_VARTYPE_BOOL</code>. + * This option can only be set before calling <code>Bind()</code>. + */ PP_UDPSOCKET_OPTION_ADDRESS_REUSE = 0, - // Allows sending and receiving packets to and from broadcast addresses. - // Value's type should be PP_VARTYPE_BOOL. - // This option can only be set before calling Bind(). + /** + * Allows sending and receiving packets to and from broadcast addresses. + * Value's type should be <code>PP_VARTYPE_BOOL</code>. + * This option can only be set before calling <code>Bind()</code>. + */ PP_UDPSOCKET_OPTION_BROADCAST = 1, - // Specifies the total per-socket buffer space reserved for sends. Value's - // type should be PP_VARTYPE_INT32. - // This option can only be set after a successful Bind() call. - // 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 it will conform to it. + /** + * Specifies the total per-socket buffer space reserved for sends. Value's + * type should be <code>PP_VARTYPE_INT32</code>. + * This option can only be set after a successful <code>Bind()</code> call. + * + * Note: This is only treated as a hint for the browser to set the buffer + * size. Even if <code>SetOption()</code> succeeds, the browser doesn't + * guarantee it will conform to the size. + */ 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. - // This option can only be set after a successful Bind() call. - // 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 it will conform to it. + /** + * Specifies the total per-socket buffer space reserved for receives. Value's + * type should be <code>PP_VARTYPE_INT32</code>. + * This option can only be set after a successful <code>Bind()</code> call. + * + * Note: This is only treated as a hint for the browser to set the buffer + * size. Even if <code>SetOption()</code> succeeds, the browser doesn't + * guarantee it will conform to the size. + */ PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3 }; +/** + * The <code>PPB_UDPSocket_Dev</code> interface provides UDP socket operations. + * + * Permissions: Apps permission <code>socket</code> with subrule + * <code>udp-bind</code> is required for <code>Bind()</code>; subrule + * <code>udp-send-to</code> is required for <code>SendTo()</code>. + * For more details about network communication permissions, please see: + * http://developer.chrome.com/apps/app_network.html + */ interface PPB_UDPSocket_Dev { /** * Creates a UDP socket resource. + * + * @param[in] instance A <code>PP_Instance</code> identifying one instance of + * a module. + * + * @return A <code>PP_Resource</code> corresponding to a UDP socket or 0 + * on failure. */ PP_Resource Create([in] PP_Instance instance); /** * Determines if a given resource is a UDP socket. + * + * @param[in] resource A <code>PP_Resource</code> to check. + * + * @return <code>PP_TRUE</code> if the input is a + * <code>PPB_UDPSocket_Dev</code> resource; <code>PP_FALSE</code> + * otherwise. */ PP_Bool IsUDPSocket([in] PP_Resource resource); /** - * Binds to the address given by |addr|, which is a PPB_NetAddress_Dev - * resource. + * Binds the socket to the given address. + * + * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP + * socket. + * @param[in] addr A <code>PPB_NetAddress_Dev</code> resource. + * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon + * completion. + * + * @return An int32_t containing an error code from <code>pp_errors.h</code>. + * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have + * required permissions. <code>PP_ERROR_ADDRESS_IN_USE</code> will be returned + * if the address is already in use. */ 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. Bind must be called and succeed first. Returns 0 if Bind fails, - * or if Close has been called. + * Gets the address that the socket is bound to. The socket must be bound. + * + * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP + * socket. + * + * @return A <code>PPB_NetAddress_Dev</code> resource on success or 0 on + * failure. */ 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. + * Receives data from the socket and stores the source address. The socket + * must be bound. + * + * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP + * socket. + * @param[out] buffer The buffer to store the received data on success. It + * must be at least as large as <code>num_bytes</code>. + * @param[in] num_bytes The number of bytes to receive. + * @param[out] addr A <code>PPB_NetAddress_Dev</code> resource to store the + * source address on success. + * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon + * completion. + * + * @return A non-negative number on success to indicate how many bytes have + * been received; otherwise, an error code from <code>pp_errors.h</code>. */ int32_t RecvFrom([in] PP_Resource udp_socket, [out] str_t buffer, @@ -81,9 +140,21 @@ interface PPB_UDPSocket_Dev { [in] PP_CompletionCallback callback); /** - * Performs a non-blocking sendto call on the socket. - * Bind must be called first. |addr| is a PPB_NetAddress_Dev resource holding - * the target address. |callback| is invoked when sendto completes. + * Sends data to a specific destination. The socket must be bound. + * + * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP + * socket. + * @param[in] buffer The buffer containing the data to send. + * @param[in] num_bytes The number of bytes to send. + * @param[in] addr A <code>PPB_NetAddress_Dev</code> resource holding the + * destination address. + * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon + * completion. + * + * @return A non-negative number on success to indicate how many bytes have + * been sent; otherwise, an error code from <code>pp_errors.h</code>. + * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have + * required permissions. */ int32_t SendTo([in] PP_Resource udp_socket, [in] str_t buffer, @@ -92,17 +163,33 @@ interface PPB_UDPSocket_Dev { [in] PP_CompletionCallback callback); /** - * Cancels all pending reads and writes, and closes the socket. + * Cancels all pending reads and writes, and closes the socket. Any pending + * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if + * pending IO was interrupted. After a call to this method, no output + * parameters passed into previous <code>RecvFrom()</code> calls will be + * accessed. It is not valid to call <code>Bind()</code> again. + * + * The socket is implicitly closed if it is destroyed, so you are not + * required to call this method. + * + * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP + * socket. */ void Close([in] PP_Resource udp_socket); /** - * Sets a socket option on |udp_socket|. - * See the PP_UDPSocket_Option_Dev description for option names, value types - * and allowed values. - * Returns PP_OK on success. 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. + * Sets a socket option on the UDP socket. + * Please see the <code>PP_UDPSocket_Option_Dev</code> description for option + * names, value types and allowed values. + * + * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP + * socket. + * @param[in] name The option to set. + * @param[in] value The option value to set. + * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon + * completion. + * + * @return An int32_t containing an error code from <code>pp_errors.h</code>. */ int32_t SetOption([in] PP_Resource udp_socket, [in] PP_UDPSocket_Option_Dev name, |