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