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
10label Chrome {
11  M17 = 0.3,
12  M20 = 0.4,
13  M27 = 0.5
14};
15
16[assert_size(4)]
17enum 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 */
31interface 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