1/*
2 * Copyright (C) 2012 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_ASYNC_SOCKET_H_
18#define ANDROID_ASYNC_SOCKET_H_
19
20#include "qemu-common.h"
21#include "android/async-io-common.h"
22#include "android/async-utils.h"
23
24/*
25 * Contains declaration of an API that encapsulates communication via an
26 * asynchronous socket.
27 *
28 * This is pretty basic API that allows asynchronous connection to a socket,
29 * and asynchronous read from / write to the connected socket.
30 *
31 * Since all the operations (including connection) are asynchronous, all the
32 * operation results are reported back to the client of this API via set of
33 * callbacks that client supplied to this API.
34 *
35 * Since it's hard to control lifespan of an object in asynchronous environment,
36 * we make AsyncSocketConnector a referenced object, that will self-destruct when
37 * its reference count drops to zero, indicating that the last client has
38 * abandoned that object.
39 */
40
41/* Declares asynchronous socket descriptor. */
42typedef struct AsyncSocket AsyncSocket;
43
44/* Asynchronous socket I/O (reader, or writer) descriptor. */
45typedef struct AsyncSocketIO AsyncSocketIO;
46
47/* Defines client's callback set to monitor socket connection.
48 * Param:
49 *  client_opaque - An opaque pointer associated with the client.
50 *  as - Initialized AsyncSocket instance.
51 *  status - Socket connection status.
52 * Return:
53 *  One of the AsyncIOAction values.
54 */
55typedef AsyncIOAction (*on_as_connection_cb)(void* client_opaque,
56                                             AsyncSocket* as,
57                                             AsyncIOState status);
58
59/* Defines client's callback set to monitor I/O progress.
60 * Param:
61 *  io_opaque - An opaque pointer associated with the I/O.
62 *  asio - Async I/O in progress.
63 *  status - Status of the I/O.
64 * Return:
65 *  One of the AsyncIOAction values.
66 */
67typedef AsyncIOAction (*on_as_io_cb)(void* io_opaque,
68                                     AsyncSocketIO* asio,
69                                     AsyncIOState status);
70
71/********************************************************************************
72 *                          AsyncSocketIO API
73 *******************************************************************************/
74
75/* References AsyncSocketIO object.
76 * Param:
77 *  asio - Initialized AsyncSocketIO instance.
78 * Return:
79 *  Number of outstanding references to the object.
80 */
81extern int async_socket_io_reference(AsyncSocketIO* asio);
82
83/* Releases AsyncSocketIO object.
84 * Note that upon exit from this routine the object might be destroyed, even if
85 * the routine returns value other than zero.
86 * Param:
87 *  asio - Initialized AsyncSocketIO instance.
88 * Return:
89 *  Number of outstanding references to the object.
90 */
91extern int async_socket_io_release(AsyncSocketIO* asio);
92
93/* Gets AsyncSocket instance for an I/O. Note that this routine will reference
94 * AsyncSocket instance before returning it to the caller. */
95extern AsyncSocket* async_socket_io_get_socket(const AsyncSocketIO* asio);
96
97/* Cancels time out set for an I/O */
98extern void async_socket_io_cancel_time_out(AsyncSocketIO* asio);
99
100/* Gets an opaque pointer associated with an I/O */
101extern void* async_socket_io_get_io_opaque(const AsyncSocketIO* asio);
102
103/* Gets an opaque pointer associated with the client that has requested I/O */
104extern void* async_socket_io_get_client_opaque(const AsyncSocketIO* asio);
105
106/* Gets I/O buffer information.
107 * Param:
108 *  asio - I/O descriptor.
109 *  transferred - Optional pointer to receive number of bytes transferred with
110 *      this I/O. Can be NULL.
111 *  to_transfer - Optional pointer to receive number of bytes requested to
112 *      transfer with this I/O. Can be NULL.
113 * Return:
114 *  I/O buffer.
115 */
116extern void* async_socket_io_get_buffer_info(const AsyncSocketIO* asio,
117                                             uint32_t* transferred,
118                                             uint32_t* to_transfer);
119
120/* Gets I/O buffer. */
121extern void* async_socket_io_get_buffer(const AsyncSocketIO* asio);
122
123/* Gets number of bytes transferred with this I/O. */
124extern uint32_t async_socket_io_get_transferred(const AsyncSocketIO* asio);
125
126/* Gets number of bytes requested to transfer with this I/O. */
127extern uint32_t async_socket_io_get_to_transfer(const AsyncSocketIO* asio);
128
129/* Gets I/O type: read (returns 1), or write (returns 0). */
130extern int async_socket_io_is_read(const AsyncSocketIO* asio);
131
132/********************************************************************************
133 *                            AsyncSocket API
134 *******************************************************************************/
135
136/* Creates an asynchronous socket descriptor.
137 * Param:
138 *  port - TCP port to connect the socket to.
139 *  reconnect_to - Timeout before trying to reconnect after disconnection.
140 *  connect_cb - Client callback to monitor connection state (must not be NULL).
141 *  client_opaque - An opaque pointer to associate with the socket client.
142 *  looper - An optional (can be NULL) I/O looper to use for socket I/O. If
143 *      this parameter is NULL, the socket will create its own looper.
144 * Return:
145 *  Initialized AsyncSocket instance on success, or NULL on failure.
146 */
147extern AsyncSocket* async_socket_new(int port,
148                                     int reconnect_to,
149                                     on_as_connection_cb connect_cb,
150                                     void* client_opaque,
151                                     Looper* looper);
152
153/* References AsyncSocket object.
154 * Param:
155 *  as - Initialized AsyncSocket instance.
156 * Return:
157 *  Number of outstanding references to the object.
158 */
159extern int async_socket_reference(AsyncSocket* as);
160
161/* Releases AsyncSocket object.
162 * Note that upon exit from this routine the object might be destroyed, even if
163 * the routine returns value other than zero.
164 * Param:
165 *  as - Initialized AsyncSocket instance.
166 * Return:
167 *  Number of outstanding references to the object.
168 */
169extern int async_socket_release(AsyncSocket* as);
170
171/* Asynchronously connects to an asynchronous socket.
172 * Note that connection result will be reported via callback passed to the
173 * async_socket_new routine.
174 * Param:
175 *  as - Initialized AsyncSocket instance.
176 *  retry_to - Number of milliseconds to wait before retrying a failed
177 *      connection attempt.
178 */
179extern void async_socket_connect(AsyncSocket* as, int retry_to);
180
181/* Disconnects from an asynchronous socket.
182 * NOTE: AsyncSocket instance referenced in this call will be destroyed in this
183 *  routine.
184 * Param:
185 *  as - Initialized and connected AsyncSocket instance.
186 */
187extern void async_socket_disconnect(AsyncSocket* as);
188
189/* Asynchronously reconnects to an asynchronous socket.
190 * Note that connection result will be reported via callback passed to the
191 * async_socket_new routine.
192 * Param:
193 *  as - Initialized AsyncSocket instance.
194 *  retry_to - Number of milliseconds to wait before trying to reconnect.
195 */
196extern void async_socket_reconnect(AsyncSocket* as, int retry_to);
197
198/* Asynchronously reads data from an asynchronous socket with a deadline.
199 * Param:
200 *  as - Initialized and connected AsyncSocket instance.
201 *  buffer, len - Buffer where to read data.
202 *  reader_cb - Callback to monitor I/O progress (must not be NULL).
203 *  reader_opaque - An opaque pointer associated with the reader.
204 *  deadline - Deadline to complete the read.
205 */
206extern void async_socket_read_abs(AsyncSocket* as,
207                                  void* buffer, uint32_t len,
208                                  on_as_io_cb reader_cb,
209                                  void* reader_opaque,
210                                  Duration deadline);
211
212/* Asynchronously reads data from an asynchronous socket with a relative timeout.
213 * Param:
214 *  as - Initialized and connected AsyncSocket instance.
215 *  buffer, len - Buffer where to read data.
216 *  reader_cb - Callback to monitor I/O progress (must not be NULL).
217 *  reader_opaque - An opaque pointer associated with the reader.
218 *  to - Milliseconds to complete the read. to < 0 indicates "no timeout"
219 */
220extern void async_socket_read_rel(AsyncSocket* as,
221                                  void* buffer, uint32_t len,
222                                  on_as_io_cb reader_cb,
223                                  void* reader_opaque,
224                                  int to);
225
226/* Asynchronously writes data to an asynchronous socket with a deadline.
227 * Param:
228 *  as - Initialized and connected AsyncSocket instance.
229 *  buffer, len - Buffer with writing data.
230 *  writer_cb - Callback to monitor I/O progress (must not be NULL).
231 *  writer_opaque - An opaque pointer associated with the writer.
232 *  deadline - Deadline to complete the write.
233 */
234extern void async_socket_write_abs(AsyncSocket* as,
235                                   const void* buffer, uint32_t len,
236                                   on_as_io_cb writer_cb,
237                                   void* writer_opaque,
238                                   Duration deadline);
239
240/* Asynchronously writes data to an asynchronous socket with a relative timeout.
241 * Param:
242 *  as - Initialized and connected AsyncSocket instance.
243 *  buffer, len - Buffer with writing data.
244 *  writer_cb - Callback to monitor I/O progress (must not be NULL)
245 *  writer_opaque - An opaque pointer associated with the writer.
246 *  to - Milliseconds to complete the write. to < 0 indicates "no timeout"
247 */
248extern void async_socket_write_rel(AsyncSocket* as,
249                                   const void* buffer, uint32_t len,
250                                   on_as_io_cb writer_cb,
251                                   void* writer_opaque,
252                                   int to);
253
254/* Get a deadline for the given time interval relative to "now".
255 * Param:
256 *  as - Initialized AsyncSocket instance.
257 *  rel - Time interval. If < 0 an infinite duration will be returned.
258 * Return:
259 *  A deadline for the given time interval relative to "now".
260 */
261extern Duration async_socket_deadline(AsyncSocket* as, int rel);
262
263/* Gets an opaque pointer associated with the socket's client */
264extern void* async_socket_get_client_opaque(const AsyncSocket* as);
265
266/* Gets TCP port for the socket. */
267extern int async_socket_get_port(const AsyncSocket* as);
268
269/* Checks if socket is connected.
270 * Return:
271 *  Boolean: 1 - socket is connected, 0 - socket is not connected.
272 */
273extern int async_socket_is_connected(const AsyncSocket* as);
274
275#endif  /* ANDROID_ASYNC_SOCKET_H_ */
276