• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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