| /* |
| * 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_ */ |
