/* 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_TCPSocket
interface.
*/
label Chrome {
M29 = 1.0,
M31 = 1.1,
M41 = 1.2
};
/**
* Option names used by SetOption()
.
*/
[assert_size(4)]
enum PP_TCPSocket_Option {
/**
* Disables coalescing of small writes to make TCP segments, and instead
* delivers data immediately. Value's type is PP_VARTYPE_BOOL
.
* On version 1.1 or earlier, this option can only be set after a successful
* Connect()
call. On version 1.2 or later, there is no such
* limitation.
*/
PP_TCPSOCKET_OPTION_NO_DELAY = 0,
/**
* Specifies the total per-socket buffer space reserved for sends. Value's
* type should be PP_VARTYPE_INT32
.
* On version 1.1 or earlier, this option can only be set after a successful
* Connect()
call. On version 1.2 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_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
/**
* Specifies the total per-socket buffer space reserved for receives. Value's
* type should be PP_VARTYPE_INT32
.
* On version 1.1 or earlier, this option can only be set after a successful
* Connect()
call. On version 1.2 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_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
};
/**
* The PPB_TCPSocket
interface provides TCP socket operations.
*
* Permissions: Apps permission socket
with subrule
* tcp-connect
is required for Connect()
; subrule
* tcp-listen
is required for Listen()
.
* For more details about network communication permissions, please see:
* http://developer.chrome.com/apps/app_network.html
*/
interface PPB_TCPSocket {
/**
* Creates a TCP socket resource.
*
* @param[in] instance A PP_Instance
identifying one instance of
* a module.
*
* @return A PP_Resource
corresponding to a TCP socket or 0
* on failure.
*/
PP_Resource Create([in] PP_Instance instance);
/**
* Determines if a given resource is a TCP socket.
*
* @param[in] resource A PP_Resource
to check.
*
* @return PP_TRUE
if the input is a
* PPB_TCPSocket
resource; PP_FALSE
otherwise.
*/
PP_Bool IsTCPSocket([in] PP_Resource resource);
/**
* Binds the socket to the given address. The socket must not be bound.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* 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
,
* including (but not limited to):
* - PP_ERROR_ADDRESS_IN_USE
: the address is already in use.
* - PP_ERROR_ADDRESS_INVALID
: the address is invalid.
*/
[version=1.1]
int32_t Bind([in] PP_Resource tcp_socket,
[in] PP_Resource addr,
[in] PP_CompletionCallback callback);
/**
* Connects the socket to the given address. The socket must not be listening.
* Binding the socket beforehand is optional.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* 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
,
* including (but not limited to):
* - PP_ERROR_NOACCESS
: the caller doesn't have required
* permissions.
* - PP_ERROR_ADDRESS_UNREACHABLE
: addr
is
* unreachable.
* - PP_ERROR_CONNECTION_REFUSED
: the connection attempt was
* refused.
* - PP_ERROR_CONNECTION_FAILED
: the connection attempt failed.
* - PP_ERROR_CONNECTION_TIMEDOUT
: the connection attempt timed
* out.
*
* Since version 1.1, if the socket is listening/connected or has a pending
* listen/connect request, Connect()
will fail without starting a
* connection attempt; otherwise, any failure during the connection attempt
* will cause the socket to be closed.
*/
int32_t Connect([in] PP_Resource tcp_socket,
[in] PP_Resource addr,
[in] PP_CompletionCallback callback);
/**
* Gets the local address of the socket, if it is bound.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
*
* @return A PPB_NetAddress
resource on success or 0 on failure.
*/
PP_Resource GetLocalAddress([in] PP_Resource tcp_socket);
/**
* Gets the remote address of the socket, if it is connected.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
*
* @return A PPB_NetAddress
resource on success or 0 on failure.
*/
PP_Resource GetRemoteAddress([in] PP_Resource tcp_socket);
/**
* Reads data from the socket. The socket must be connected. It may perform a
* partial read.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
* @param[out] buffer The buffer to store the received data on success. It
* must be at least as large as bytes_to_read
.
* @param[in] bytes_to_read The number of bytes to read.
* @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 read, 0 means that end-of-file was reached; otherwise, an error code
* from pp_errors.h
.
*/
int32_t Read([in] PP_Resource tcp_socket,
[out] str_t buffer,
[in] int32_t bytes_to_read,
[in] PP_CompletionCallback callback);
/**
* Writes data to the socket. The socket must be connected. It may perform a
* partial write.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
* @param[in] buffer The buffer containing the data to write.
* @param[in] bytes_to_write The number of bytes to write.
* @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 written; otherwise, an error code from pp_errors.h
.
*/
int32_t Write([in] PP_Resource tcp_socket,
[in] str_t buffer,
[in] int32_t bytes_to_write,
[in] PP_CompletionCallback callback);
/**
* Starts listening. The socket must be bound and not connected.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
* @param[in] backlog A hint to determine the maximum length to which the
* queue of pending connections may grow.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
,
* including (but not limited to):
* - PP_ERROR_NOACCESS
: the caller doesn't have required
* permissions.
* - PP_ERROR_ADDRESS_IN_USE
: Another socket is already listening
* on the same port.
*/
[version=1.1]
int32_t Listen([in] PP_Resource tcp_socket,
[in] int32_t backlog,
[in] PP_CompletionCallback callback);
/**
* Accepts a connection. The socket must be listening.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
* @param[out] accepted_tcp_socket Stores the accepted TCP socket on success.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion.
*
* @return An int32_t containing an error code from pp_errors.h
,
* including (but not limited to):
* - PP_ERROR_CONNECTION_ABORTED
: A connection has been aborted.
*/
[version=1.1]
int32_t Accept([in] PP_Resource tcp_socket,
[out] PP_Resource accepted_tcp_socket,
[in] PP_CompletionCallback callback);
/**
* Cancels all pending operations 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 buffer pointers passed
* into previous Read()
or Accept()
calls will be
* accessed. It is not valid to call Connect()
or
* Listen()
again.
*
* The socket is implicitly closed if it is destroyed, so you are not required
* to call this method.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* socket.
*/
void Close([in] PP_Resource tcp_socket);
/**
* Sets a socket option on the TCP socket.
* Please see the PP_TCPSocket_Option
description for option
* names, value types and allowed values.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* 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 tcp_socket,
[in] PP_TCPSocket_Option name,
[in] PP_Var value,
[in] PP_CompletionCallback callback);
/**
* Sets a socket option on the TCP socket.
* Please see the PP_TCPSocket_Option
description for option
* names, value types and allowed values.
*
* @param[in] tcp_socket A PP_Resource
corresponding to a TCP
* 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 tcp_socket,
[in] PP_TCPSocket_Option name,
[in] PP_Var value,
[in] PP_CompletionCallback callback);
};