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