/* Copyright 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 PPB_UDPSocket
interface.
*/
[generate_thunk]
label Chrome {
M29 = 1.0,
M41 = 1.1,
M43 = 1.2
};
/**
* Option names used by SetOption()
.
*/
[assert_size(4)]
enum PP_UDPSocket_Option {
/**
* 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()
.
*/
PP_UDPSOCKET_OPTION_ADDRESS_REUSE = 0,
/**
* Allows sending and receiving packets to and from broadcast addresses.
* Value's type should be PP_VARTYPE_BOOL
.
* On version 1.0, this option can only be set before calling
* Bind()
. On version 1.1 or later, there is no such limitation.
*/
PP_UDPSOCKET_OPTION_BROADCAST = 1,
/**
* Specifies the total per-socket buffer space reserved for sends. Value's
* type should be PP_VARTYPE_INT32
.
* On version 1.0, this option can only be set after a successful
* Bind()
call. On version 1.1 or later, there is no such
* limitation.
*
* Note: This is only treated as a hint for the browser to set the buffer
* size. Even if SetOption()
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
.
* On version 1.0, this option can only be set after a successful
* Bind()
call. On version 1.1 or later, there is no such
* limitation.
*
* Note: This is only treated as a hint for the browser to set the buffer
* size. Even if SetOption()
succeeds, the browser doesn't
* guarantee it will conform to the size.
*/
PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3,
/**
* Specifies whether the packets sent from the host to the multicast group
* should be looped back to the host or not. Value's type should be
* PP_VARTYPE_BOOL
.
* This option can only be set before calling Bind()
.
*
* This is only supported in version 1.2 of the API (Chrome 43) and later.
*/
PP_UDPSOCKET_OPTION_MULTICAST_LOOP = 4,
/**
* Specifies the time-to-live for packets sent to the multicast group. The
* value should be within 0 to 255 range. The default value is 1 and means
* that packets will not be routed beyond the local network. Value's type
* should be PP_VARTYPE_INT32
.
* This option can only be set before calling Bind()
.
*
* This is only supported in version 1.2 of the API (Chrome 43) and later.
*/
PP_UDPSOCKET_OPTION_MULTICAST_TTL = 5
};
/**
* The PPB_UDPSocket
interface provides UDP socket operations.
*
* Permissions: Apps permission socket
with subrule
* udp-bind
is required for Bind()
; subrule
* udp-send-to
is required for SendTo()
.
* For more details about network communication permissions, please see:
* http://developer.chrome.com/apps/app_network.html
*/
interface PPB_UDPSocket {
/**
* Creates a UDP socket resource.
*
* @param[in] instance A PP_Instance
identifying one instance of
* a module.
*
* @return A PP_Resource
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 PP_Resource
to check.
*
* @return PP_TRUE
if the input is a PPB_UDPSocket
* resource; PP_FALSE
otherwise.
*/
PP_Bool IsUDPSocket([in] PP_Resource resource);
/**
* Binds the socket to the given address.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
* @param[in] addr A PPB_NetAddress
resource.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
.
* PP_ERROR_NOACCESS
will be returned if the caller doesn't have
* required permissions. PP_ERROR_ADDRESS_IN_USE
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);
/**
* Gets the address that the socket is bound to. The socket must be bound.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
*
* @return A PPB_NetAddress
resource on success or 0 on failure.
*/
PP_Resource GetBoundAddress([in] PP_Resource udp_socket);
/**
* Receives data from the socket and stores the source address. The socket
* must be bound.
*
* @param[in] udp_socket A PP_Resource
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 num_bytes
.
* @param[in] num_bytes The number of bytes to receive.
* @param[out] addr A PPB_NetAddress
resource to store the source
* address on success.
* @param[in] callback A PP_CompletionCallback
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 pp_errors.h
.
*/
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);
/**
* Sends data to a specific destination. The socket must be bound.
*
* @param[in] udp_socket A PP_Resource
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 PPB_NetAddress
resource holding the
* destination address.
* @param[in] callback A PP_CompletionCallback
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 pp_errors.h
.
* PP_ERROR_NOACCESS
will be returned if the caller doesn't have
* required permissions.
* PP_ERROR_INPROGRESS
will be returned if the socket is busy
* sending. The caller should wait until a pending send completes before
* retrying.
*/
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. Any pending
* callbacks will still run, reporting PP_ERROR_ABORTED
if
* pending IO was interrupted. After a call to this method, no output
* parameters passed into previous RecvFrom()
calls will be
* accessed. It is not valid to call Bind()
again.
*
* The socket is implicitly closed if it is destroyed, so you are not
* required to call this method.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
*/
void Close([in] PP_Resource udp_socket);
/**
* Sets a socket option on the UDP socket.
* Please see the PP_UDPSocket_Option
description for option
* names, value types and allowed values.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
* @param[in] name The option to set.
* @param[in] value The option value to set.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
.
*/
int32_t SetOption([in] PP_Resource udp_socket,
[in] PP_UDPSocket_Option name,
[in] PP_Var value,
[in] PP_CompletionCallback callback);
/**
* Sets a socket option on the UDP socket.
* Please see the PP_UDPSocket_Option
description for option
* names, value types and allowed values.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
* @param[in] name The option to set.
* @param[in] value The option value to set.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
.
*/
[version=1.1]
int32_t SetOption([in] PP_Resource udp_socket,
[in] PP_UDPSocket_Option name,
[in] PP_Var value,
[in] PP_CompletionCallback callback);
/**
* Sets a socket option on the UDP socket.
* Please see the PP_UDPSocket_Option
description for option
* names, value types and allowed values.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
* @param[in] name The option to set.
* @param[in] value The option value to set.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
.
*/
[version=1.2]
int32_t SetOption([in] PP_Resource udp_socket,
[in] PP_UDPSocket_Option name,
[in] PP_Var value,
[in] PP_CompletionCallback callback);
/**
* Joins the multicast group with address specified by group
* parameter, which is expected to be a PPB_NetAddress
object.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
* @param[in] group A PP_Resource
corresponding to the network
* address of the multicast group.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
.
*/
[version=1.2]
int32_t JoinGroup([in] PP_Resource udp_socket,
[in] PP_Resource group,
[in] PP_CompletionCallback callback);
/**
* Leaves the multicast group with address specified by group
* parameter, which is expected to be a PPB_NetAddress
object.
*
* @param[in] udp_socket A PP_Resource
corresponding to a UDP
* socket.
* @param[in] group A PP_Resource
corresponding to the network
* address of the multicast group.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
.
*/
[version=1.2]
int32_t LeaveGroup([in] PP_Resource udp_socket,
[in] PP_Resource group,
[in] PP_CompletionCallback callback);
};