android/async-socket.h

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