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