1 /* 2 * Copyright (C) 2011 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_CONNECTOR_H_ 18 #define ANDROID_ASYNC_SOCKET_CONNECTOR_H_ 19 20 #include "android/async-io-common.h" 21 22 /* 23 * Contains declaration of an API that allows asynchronous connection to a 24 * socket with retries. 25 * 26 * The typical usage of this API is as such: 27 * 28 * 1. The client creates an asynchronous connector instance by calling 29 * async_socket_connector_new routine, supplying there address of the socket 30 * to connect, and a callback to invoke on connection events. 31 * 2. The client then proceeds with calling async_socket_connector_connect that 32 * would initiate connection attempts. 33 * 34 * The main job on the client side falls on the client's callback routine that 35 * serves the connection events. Once connection has been initiated, the connector 36 * will invoke that callback to report current connection status. 37 * 38 * In general, there are three connection events passed to the callback: 39 * 1. Success. 40 * 2. Failure. 41 * 3. Retry. 42 * 43 * Typically, when client's callback is called for a successful connection, the 44 * client will pull connected socket's FD from the connector, and then this FD 45 * will be used by the client for I/O on the connected socket. 46 * 47 * When client's callback is invoked with an error (ASIO_STATE_FAILED event), the 48 * client has an opportunity to review the error (available in 'errno'), and 49 * either abort the connection by returning ASIO_ACTION_ABORT, or schedule a retry 50 * by returning ASIO_ACTION_RETRY from the callback. If client returns ASIO_ACTION_ABORT 51 * from the callback, the connector will stop connection attempts, and will 52 * self-destruct. If ASIO_ACTION_RETRY is returned from the callback, the connector 53 * will retry connection attempt after timeout that was set by the caller in the 54 * call to async_socket_connector_new routine. 55 * 56 * When client's callback is invoked with ASIO_STATE_RETRYING (indicating that 57 * connector is about to retry a connection attempt), the client has an opportunity 58 * to cancel further connection attempts by returning ASIO_ACTION_ABORT, or it 59 * can allow another connection attempt by returning ASIO_ACTION_RETRY. 60 * 61 * Since it's hard to control lifespan of an object in asynchronous environment, 62 * we make AsyncSocketConnector a referenced object, that will self-destruct when 63 * its reference count drops to zero, indicating that the last client has 64 * abandoned that object. 65 */ 66 67 /* Declares async socket connector descriptor. */ 68 typedef struct AsyncSocketConnector AsyncSocketConnector; 69 70 /* Declares callback that connector's client uses to monitor connection 71 * status / progress. 72 * Param: 73 * opaque - An opaque pointer associated with the client. 74 * connector - AsyncSocketConnector instance. 75 * event - Event that has occurred. If event is set to ASIO_STATE_FAILED, 76 * errno contains connection error. 77 * Return: 78 * One of AsyncIOAction values. 79 */ 80 typedef AsyncIOAction (*asc_event_cb)(void* opaque, 81 AsyncSocketConnector* connector, 82 AsyncIOState event); 83 84 /* Creates and initializes AsyncSocketConnector instance. 85 * Note that upon exit from this routine the reference count to the returned 86 * object is set to 1. 87 * Param: 88 * address - Initialized socket address to connect to. 89 * retry_to - Timeout to retry a failed connection attempt in milliseconds. 90 * cb, cb_opaque - Callback to invoke on connection events. This callback is 91 * required, and must not be NULL. 92 * looper - An optional (can be NULL) I/O looper to use for connection I/O. If 93 * this parameter is NULL, the connector will create its own looper. 94 * Return: 95 * Initialized AsyncSocketConnector instance. Note that AsyncSocketConnector 96 * instance returned from this routine will be destroyed by the connector itself, 97 * when its work on connecting to the socket is completed. Typically, connector 98 * will destroy its descriptor after client's callback routine returns with a 99 * status other than ASIO_ACTION_RETRY. 100 */ 101 extern AsyncSocketConnector* async_socket_connector_new(const SockAddress* address, 102 int retry_to, 103 asc_event_cb cb, 104 void* cb_opaque, 105 Looper* looper); 106 107 /* References AsyncSocketConnector object. 108 * Param: 109 * connector - Initialized AsyncSocketConnector instance. 110 * Return: 111 * Number of outstanding references to the object. 112 */ 113 extern int async_socket_connector_reference(AsyncSocketConnector* connector); 114 115 /* Releases AsyncSocketConnector object. 116 * Note that upon exit from this routine the object might be destroyed, even if 117 * the routine returns value other than zero. 118 * Param: 119 * connector - Initialized AsyncSocketConnector instance. 120 * Return: 121 * Number of outstanding references to the object. 122 */ 123 extern int async_socket_connector_release(AsyncSocketConnector* connector); 124 125 /* Initiates asynchronous connection. 126 * Note that connection result will be reported via callback set with the call to 127 * async_socket_connector_new routine. 128 * Param: 129 * connector - Initialized AsyncSocketConnector instance. Note that this 130 * connector descriptor might be destroyed asynchronously, before this 131 * routine returns. 132 */ 133 extern void async_socket_connector_connect(AsyncSocketConnector* connector); 134 135 /* Pulls socket's file descriptor from the connector. 136 * This routine should be called from the connection callback on successful 137 * connection status. This will provide the connector's client with an operational 138 * socket FD, and at the same time this will tell the connector not to close the 139 * FD when connector descriptor gets destroyed. 140 * Param: 141 * connector - Initialized AsyncSocketConnector instance. 142 * Return: 143 * File descriptor for the connected socket. 144 */ 145 extern int async_socket_connector_pull_fd(AsyncSocketConnector* connector); 146 147 #endif /* ANDROID_ASYNC_SOCKET_CONNECTOR_H_ */ 148