diff options
Diffstat (limited to 'android/async-socket-connector.h')
| -rw-r--r-- | android/async-socket-connector.h | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/android/async-socket-connector.h b/android/async-socket-connector.h new file mode 100644 index 0000000..998d0c8 --- /dev/null +++ b/android/async-socket-connector.h @@ -0,0 +1,158 @@ +/* + * Copyright (C) 2011 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_CONNECTOR_H_ +#define ANDROID_ASYNC_SOCKET_CONNECTOR_H_ + +/* + * Contains declaration of an API that allows asynchronous connection to a + * socket with retries. + * + * The typical usage of this API is as such: + * + * 1. The client creates an async connector instance by calling async_socket_connector_new + * routine, supplying there address of the socket to connect, and a callback + * to invoke on connection events. + * 2. The client then proceeds with calling async_socket_connector_connect that + * would initiate connection attempts. + * + * The main job on the client side falls on the client's callback routine that + * serves the connection events. Once connection has been initiated, the connector + * will invoke that callback to report current connection status. + * + * In general, there are three connection events passed to the callback: + * 1. Success. + * 2. Failure. + * 3. Retry. + * + * Typically, when client's callback is called for successful connection, the + * client will pull connected socket's FD from the connector, and then this FD + * will be used by the client for I/O on the connected socket. If socket's FD + * is pulled by the client, it must return ASC_CB_KEEP from the callback. + * + * When client's callback is invoked with an error (ASC_CONNECTION_FAILED event), + * the client has an opportunity to review the error (available in 'errno'), and + * either abort the connection by returning ASC_CB_ABORT, or schedule a retry + * by returning ASC_CB_RETRY from the callback. If client returns ASC_CB_ABORT + * from the callback, the connector will stop connection attempts, and will + * self-destruct. If ASC_CB_RETRY is returned from the callback, the connector + * will retry connection attempt after timeout that was set by the caller in the + * call to async_socket_connector_new routine. + * + * When client's callback is invoked with ASC_CONNECTION_RETRY, the client has an + * opportunity to cancel further connection attempts by returning ASC_CB_ABORT, + * or it can allow another connection attempt by returning ASC_CB_RETRY. + * + * The client has no control over the lifespan of initialized connector instance. + * It always self-destructs after client's cllback returns with a status other + * than ASC_CB_RETRY. + */ + +/* Declares async socket connector descriptor. */ +typedef struct AsyncSocketConnector AsyncSocketConnector; + +/* Enumerates connection events. + * Values from this enum are passed to the callback that connector's client uses + * to monitor connection status / progress. + */ +typedef enum ASCEvent { + /* Connection with the socket has been successfuly established. */ + ASC_CONNECTION_SUCCEEDED, + /* A failure has occured while establising connection, with errno containing + * the actual error. */ + ASC_CONNECTION_FAILED, + /* Async socket connector is about to retry the connection. */ + ASC_CONNECTION_RETRY, +} ASCEvent; + +/* Enumerates return values from the callback to the connector's client. + */ +typedef enum ASCCbRes { + /* Keep established connection. */ + ASC_CB_KEEP, + /* Abort connection attempts. */ + ASC_CB_ABORT, + /* Retry connection attempt. */ + ASC_CB_RETRY, +} ASCCbRes; + +/* Enumerates values returned from the connector routine. + */ +typedef enum ASCConnectRes { + /* Connection has succeeded in the connector routine. */ + ASC_CONNECT_SUCCEEDED, + /* Connection has failed in the connector routine. */ + ASC_CONNECT_FAILED, + /* Connection is in progress, and will be completed asynchronously. */ + ASC_CONNECT_IN_PROGRESS, +} ASCConnectRes; + +/* Declares callback that connector's client uses to monitor connection + * status / progress. + * Param: + * opaque - An opaque pointer associated with the client. + * connector - Connector instance for thecallback. + * event - Event that has occured. If event is set to ASC_CONNECTION_FAILED, + * errno contains connection error. + * Return: + * One of ASCCbRes values. + */ +typedef ASCCbRes (*asc_event_cb)(void* opaque, + AsyncSocketConnector* connector, + ASCEvent event); + +/* Creates and initializes AsyncSocketConnector instance. + * Param: + * address - Initialized socket address to connect to. + * retry_to - Retry timeout in milliseconds. + * cb, cb_opaque - Callback to invoke on connection events. This callback is + * required, and must not be NULL. + * Return: + * Initialized AsyncSocketConnector instance. Note that AsyncSocketConnector + * instance returned from this routine will be destroyed by the connector itself, + * when its work on connecting to the socket is completed. Typically, the + * connector wil destroy the descriptor after client's callback routine returns + * with the status other than ASC_CB_RETRY. + */ +extern AsyncSocketConnector* async_socket_connector_new(const SockAddress* address, + int retry_to, + asc_event_cb cb, + void* cb_opaque); + +/* Initiates asynchronous connection. + * Param: + * connector - Initialized AsyncSocketConnector instance. + * Return: + * Status indicating state of the connection: completed, failed, or in progress. + * Note that the connector will always invoke a callback passed to the + * async_socket_connector_new routine prior to exiting from this routine with + * statuses other ASC_CONNECT_IN_PROGRESS. + */ +extern ASCConnectRes async_socket_connector_connect(AsyncSocketConnector* connector); + +/* Pulls socket's file descriptor from the connector. + * This routine should be called from the connection callback on successful + * connection status. This will provide the connector's client with operational + * socket FD, and at the same time this will tell the connector not to close + * the FD when connector descriptor gets destroyed. + * Param: + * connector - Initialized AsyncSocketConnector instance. + * Return: + * File descriptor for the connected socket. + */ +extern int async_socket_connector_pull_fd(AsyncSocketConnector* connector); + +#endif /* ANDROID_ASYNC_SOCKET_CONNECTOR_H_ */ |