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/** 7 * This file defines the <code>PPB_UDPSocket</code> interface. 8 */ 9 10[generate_thunk] 11 12label Chrome { 13 M29 = 1.0 14}; 15 16/** 17 * Option names used by <code>SetOption()</code>. 18 */ 19[assert_size(4)] 20enum PP_UDPSocket_Option { 21 /** 22 * Allows the socket to share the local address to which it will be bound with 23 * other processes. Value's type should be <code>PP_VARTYPE_BOOL</code>. 24 * This option can only be set before calling <code>Bind()</code>. 25 */ 26 PP_UDPSOCKET_OPTION_ADDRESS_REUSE = 0, 27 28 /** 29 * Allows sending and receiving packets to and from broadcast addresses. 30 * Value's type should be <code>PP_VARTYPE_BOOL</code>. 31 * This option can only be set before calling <code>Bind()</code>. 32 */ 33 PP_UDPSOCKET_OPTION_BROADCAST = 1, 34 35 /** 36 * Specifies the total per-socket buffer space reserved for sends. Value's 37 * type should be <code>PP_VARTYPE_INT32</code>. 38 * This option can only be set after a successful <code>Bind()</code> call. 39 * 40 * Note: This is only treated as a hint for the browser to set the buffer 41 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 42 * guarantee it will conform to the size. 43 */ 44 PP_UDPSOCKET_OPTION_SEND_BUFFER_SIZE = 2, 45 46 /** 47 * Specifies the total per-socket buffer space reserved for receives. Value's 48 * type should be <code>PP_VARTYPE_INT32</code>. 49 * This option can only be set after a successful <code>Bind()</code> call. 50 * 51 * Note: This is only treated as a hint for the browser to set the buffer 52 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 53 * guarantee it will conform to the size. 54 */ 55 PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3 56}; 57 58/** 59 * The <code>PPB_UDPSocket</code> interface provides UDP socket operations. 60 * 61 * Permissions: Apps permission <code>socket</code> with subrule 62 * <code>udp-bind</code> is required for <code>Bind()</code>; subrule 63 * <code>udp-send-to</code> is required for <code>SendTo()</code>. 64 * For more details about network communication permissions, please see: 65 * http://developer.chrome.com/apps/app_network.html 66 */ 67interface PPB_UDPSocket { 68 /** 69 * Creates a UDP socket resource. 70 * 71 * @param[in] instance A <code>PP_Instance</code> identifying one instance of 72 * a module. 73 * 74 * @return A <code>PP_Resource</code> corresponding to a UDP socket or 0 75 * on failure. 76 */ 77 PP_Resource Create([in] PP_Instance instance); 78 79 /** 80 * Determines if a given resource is a UDP socket. 81 * 82 * @param[in] resource A <code>PP_Resource</code> to check. 83 * 84 * @return <code>PP_TRUE</code> if the input is a <code>PPB_UDPSocket</code> 85 * resource; <code>PP_FALSE</code> otherwise. 86 */ 87 PP_Bool IsUDPSocket([in] PP_Resource resource); 88 89 /** 90 * Binds the socket to the given address. 91 * 92 * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP 93 * socket. 94 * @param[in] addr A <code>PPB_NetAddress</code> resource. 95 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 96 * completion. 97 * 98 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 99 * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have 100 * required permissions. <code>PP_ERROR_ADDRESS_IN_USE</code> will be returned 101 * if the address is already in use. 102 */ 103 int32_t Bind([in] PP_Resource udp_socket, 104 [in] PP_Resource addr, 105 [in] PP_CompletionCallback callback); 106 107 /** 108 * Gets the address that the socket is bound to. The socket must be bound. 109 * 110 * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP 111 * socket. 112 * 113 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 114 */ 115 PP_Resource GetBoundAddress([in] PP_Resource udp_socket); 116 117 /** 118 * Receives data from the socket and stores the source address. The socket 119 * must be bound. 120 * 121 * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP 122 * socket. 123 * @param[out] buffer The buffer to store the received data on success. It 124 * must be at least as large as <code>num_bytes</code>. 125 * @param[in] num_bytes The number of bytes to receive. 126 * @param[out] addr A <code>PPB_NetAddress</code> resource to store the source 127 * address on success. 128 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 129 * completion. 130 * 131 * @return A non-negative number on success to indicate how many bytes have 132 * been received; otherwise, an error code from <code>pp_errors.h</code>. 133 */ 134 int32_t RecvFrom([in] PP_Resource udp_socket, 135 [out] str_t buffer, 136 [in] int32_t num_bytes, 137 [out] PP_Resource addr, 138 [in] PP_CompletionCallback callback); 139 140 /** 141 * Sends data to a specific destination. The socket must be bound. 142 * 143 * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP 144 * socket. 145 * @param[in] buffer The buffer containing the data to send. 146 * @param[in] num_bytes The number of bytes to send. 147 * @param[in] addr A <code>PPB_NetAddress</code> resource holding the 148 * destination address. 149 * @param[in] callback A <code>PP_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 sent; otherwise, an error code from <code>pp_errors.h</code>. 154 * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have 155 * required permissions. 156 */ 157 int32_t SendTo([in] PP_Resource udp_socket, 158 [in] str_t buffer, 159 [in] int32_t num_bytes, 160 [in] PP_Resource addr, 161 [in] PP_CompletionCallback callback); 162 163 /** 164 * Cancels all pending reads and writes, and closes the socket. Any pending 165 * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if 166 * pending IO was interrupted. After a call to this method, no output 167 * parameters passed into previous <code>RecvFrom()</code> calls will be 168 * accessed. It is not valid to call <code>Bind()</code> again. 169 * 170 * The socket is implicitly closed if it is destroyed, so you are not 171 * required to call this method. 172 * 173 * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP 174 * socket. 175 */ 176 void Close([in] PP_Resource udp_socket); 177 178 /** 179 * Sets a socket option on the UDP socket. 180 * Please see the <code>PP_UDPSocket_Option</code> description for option 181 * names, value types and allowed values. 182 * 183 * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP 184 * socket. 185 * @param[in] name The option to set. 186 * @param[in] value The option value to set. 187 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 188 * completion. 189 * 190 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 191 */ 192 int32_t SetOption([in] PP_Resource udp_socket, 193 [in] PP_UDPSocket_Option name, 194 [in] PP_Var value, 195 [in] PP_CompletionCallback callback); 196}; 197