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 }; 163
