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