ppapi/api/private/ppb_tcp_socket_private.idl

   1 /* Copyright (c) 2012 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_TCPSocket_Private</code> interface.
   8  */
   9
  10 label Chrome {
  11   M17 = 0.3,
  12   M20 = 0.4,
  13   M27 = 0.5
  14 };
  15
  16 [assert_size(4)]
  17 enum PP_TCPSocketOption_Private {
  18   // Special value used for testing. Guaranteed to fail SetOption().
  19   PP_TCPSOCKETOPTION_PRIVATE_INVALID = 0,
  20
  21   // Disable coalescing of small writes to make TCP segments, and instead
  22   // deliver data immediately. For SSL sockets, this option must be set before
  23   // SSLHandshake() is called. Value type is PP_VARTYPE_BOOL.
  24   PP_TCPSOCKETOPTION_PRIVATE_NO_DELAY = 1
  25 };
  26
  27 /**
  28  * The <code>PPB_TCPSocket_Private</code> interface provides TCP socket
  29  * operations.
  30  */
  31 interface PPB_TCPSocket_Private {
  32   /**
  33    * Allocates a TCP socket resource.
  34    */
  35   PP_Resource Create([in] PP_Instance instance);
  36
  37   /**
  38    * Determines if a given resource is TCP socket.
  39    */
  40   PP_Bool IsTCPSocket([in] PP_Resource resource);
  41
  42   /**
  43    * Connects to a TCP port given as a host-port pair.
  44    * When a proxy server is used, |host| and |port| refer to the proxy server
  45    * instead of the destination server.
  46    */
  47   int32_t Connect([in] PP_Resource tcp_socket,
  48                   [in] str_t host,
  49                   [in] uint16_t port,
  50                   [in] PP_CompletionCallback callback);
  51
  52   /**
  53    * Same as Connect(), but connecting to the address given by |addr|. A typical
  54    * use-case would be for reconnections.
  55    */
  56   int32_t ConnectWithNetAddress([in] PP_Resource tcp_socket,
  57                                 [in] PP_NetAddress_Private addr,
  58                                 [in] PP_CompletionCallback callback);
  59
  60   /**
  61    * Gets the local address of the socket, if it has been connected.
  62    * Returns PP_TRUE on success.
  63    */
  64   PP_Bool GetLocalAddress([in] PP_Resource tcp_socket,
  65                           [out] PP_NetAddress_Private local_addr);
  66
  67   /**
  68    * Gets the remote address of the socket, if it has been connected.
  69    * Returns PP_TRUE on success.
  70    */
  71   PP_Bool GetRemoteAddress([in] PP_Resource tcp_socket,
  72                            [out] PP_NetAddress_Private remote_addr);
  73
  74   /**
  75    * Does SSL handshake and moves to sending and receiving encrypted data. The
  76    * socket must have been successfully connected. |server_name| will be
  77    * compared with the name(s) in the server's certificate during the SSL
  78    * handshake. |server_port| is only used to identify an SSL server in the SSL
  79    * session cache.
  80    * When a proxy server is used, |server_name| and |server_port| refer to the
  81    * destination server.
  82    * If the socket is not connected, or there are pending read/write requests,
  83    * SSLHandshake() will fail without starting a handshake. Otherwise, any
  84    * failure during the handshake process will cause the socket to be
  85    * disconnected.
  86    */
  87   int32_t SSLHandshake([in] PP_Resource tcp_socket,
  88                        [in] str_t server_name,
  89                        [in] uint16_t server_port,
  90                        [in] PP_CompletionCallback callback);
  91
  92   /**
  93    * Returns the server's <code>PPB_X509Certificate_Private</code> for a socket
  94    * connection if an SSL connection has been established using
  95    * <code>SSLHandshake</code>. If no SSL connection has been established, a
  96    * null resource is returned.
  97    */
  98   [version=0.4]
  99   PP_Resource GetServerCertificate([in] PP_Resource tcp_socket);
 100
 101   /**
 102    * NOTE: This function is not implemented and will return
 103    * <code>PP_FALSE</code>.
 104    * Adds a trusted/untrusted chain building certificate to be used for this
 105    * connection. The <code>certificate</code> must be a
 106    * <code>PPB_X509Certificate_Private<code>. <code>PP_TRUE</code> is returned
 107    * upon success.
 108    */
 109   [version=0.4]
 110   PP_Bool AddChainBuildingCertificate([in] PP_Resource tcp_socket,
 111                                       [in] PP_Resource certificate,
 112                                       [in] PP_Bool is_trusted);
 113
 114   /**
 115    * Reads data from the socket. The size of |buffer| must be at least as large
 116    * as |bytes_to_read|. May perform a partial read. Returns the number of bytes
 117    * read or an error code. If the return value is 0, then it indicates that
 118    * end-of-file was reached.
 119    * This method won't return more than 1 megabyte, so if |bytes_to_read|
 120    * exceeds 1 megabyte, it will always perform a partial read.
 121    * Multiple outstanding read requests are not supported.
 122    */
 123   int32_t Read([in] PP_Resource tcp_socket,
 124                [out] str_t buffer,
 125                [in] int32_t bytes_to_read,
 126                [in] PP_CompletionCallback callback);
 127
 128   /**
 129    * Writes data to the socket. May perform a partial write. Returns the number
 130    * of bytes written or an error code.
 131    * This method won't write more than 1 megabyte, so if |bytes_to_write|
 132    * exceeds 1 megabyte, it will always perform a partial write.
 133    * Multiple outstanding write requests are not supported.
 134    */
 135   int32_t Write([in] PP_Resource tcp_socket,
 136                 [in] str_t buffer,
 137                 [in] int32_t bytes_to_write,
 138                 [in] PP_CompletionCallback callback);
 139
 140   /**
 141    * Cancels any IO that may be pending, and disconnects the socket. Any pending
 142    * callbacks will still run, reporting PP_Error_Aborted if pending IO was
 143    * interrupted. It is NOT valid to call Connect() again after a call to this
 144    * method. Note: If the socket is destroyed when it is still connected, then
 145    * it will be implicitly disconnected, so you are not required to call this
 146    * method.
 147    */
 148   void Disconnect([in] PP_Resource tcp_socket);
 149
 150   /**
 151    * Sets an option on |tcp_socket|.  Supported |name| and |value| parameters
 152    * are as described for PP_TCPSocketOption_Private.  |callback| will be
 153    * invoked with PP_OK if setting the option succeeds, or an error code
 154    * otherwise. The socket must be connection before SetOption is called.
 155    */
 156   [version=0.5]
 157   int32_t SetOption([in] PP_Resource tcp_socket,
 158                     [in] PP_TCPSocketOption_Private name,
 159                     [in] PP_Var value,
 160                     [in] PP_CompletionCallback callback);
 161
 162 };