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. */ 42 typedef struct AsyncSocket AsyncSocket; 43 44 /* Asynchronous socket I/O (reader, or writer) descriptor. */ 45 typedef 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 */ 55 typedef 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 */ 67 typedef 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 */ 81 extern 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 */ 91 extern 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. */ 95 extern AsyncSocket* async_socket_io_get_socket(const AsyncSocketIO* asio); 96 97 /* Cancels time out set for an I/O */ 98 extern void async_socket_io_cancel_time_out(AsyncSocketIO* asio); 99 100 /* Gets an opaque pointer associated with an I/O */ 101 extern 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 */ 104 extern 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 */ 116 extern 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. */ 121 extern void* async_socket_io_get_buffer(const AsyncSocketIO* asio); 122 123 /* Gets number of bytes transferred with this I/O. */ 124 extern uint32_t async_socket_io_get_transferred(const AsyncSocketIO* asio); 125 126 /* Gets number of bytes requested to transfer with this I/O. */ 127 extern uint32_t async_socket_io_get_to_transfer(const AsyncSocketIO* asio); 128 129 /* Gets I/O type: read (returns 1), or write (returns 0). */ 130 extern 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 */ 147 extern 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 */ 159 extern 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 */ 169 extern 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 */ 179 extern 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 */ 187 extern 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 */ 196 extern 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 */ 206 extern 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 */ 220 extern 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 */ 234 extern 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 */ 248 extern 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 */ 261 extern Duration async_socket_deadline(AsyncSocket* as, int rel); 262 263 /* Gets an opaque pointer associated with the socket's client */ 264 extern void* async_socket_get_client_opaque(const AsyncSocket* as); 265 266 /* Gets TCP port for the socket. */ 267 extern 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 */ 273 extern int async_socket_is_connected(const AsyncSocket* as); 274 275 #endif /* ANDROID_ASYNC_SOCKET_H_ */ 276