1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
/*
* 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_
#include "android/async-io-common.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 asynchronous 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 a 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.
*
* When client's callback is invoked with an error (ASIO_STATE_FAILED event), the
* client has an opportunity to review the error (available in 'errno'), and
* either abort the connection by returning ASIO_ACTION_ABORT, or schedule a retry
* by returning ASIO_ACTION_RETRY from the callback. If client returns ASIO_ACTION_ABORT
* from the callback, the connector will stop connection attempts, and will
* self-destruct. If ASIO_ACTION_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 ASIO_STATE_RETRYING (indicating that
* connector is about to retry a connection attempt), the client has an opportunity
* to cancel further connection attempts by returning ASIO_ACTION_ABORT, or it
* can allow another connection attempt by returning ASIO_ACTION_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 ASIO_ACTION_RETRY.
*/
/* Declares async socket connector descriptor. */
typedef struct AsyncSocketConnector AsyncSocketConnector;
/* Declares callback that connector's client uses to monitor connection
* status / progress.
* Param:
* opaque - An opaque pointer associated with the client.
* connector - AsyncSocketConnector instance.
* event - Event that has occurred. If event is set to ASIO_STATE_FAILED,
* errno contains connection error.
* Return:
* One of AsyncIOAction values.
*/
typedef AsyncIOAction (*asc_event_cb)(void* opaque,
AsyncSocketConnector* connector,
AsyncIOState event);
/* Creates and initializes AsyncSocketConnector instance.
* Param:
* address - Initialized socket address to connect to.
* retry_to - Timeout to retry a failed connection attempt 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, connector
* will destroy its descriptor after client's callback routine returns with a
* status other than ASIO_ACTION_RETRY.
*/
extern AsyncSocketConnector* async_socket_connector_new(const SockAddress* address,
int retry_to,
asc_event_cb cb,
void* cb_opaque);
/* Initiates asynchronous connection.
* Note that connection result will be reported via callback set with the call to
* async_socket_connector_new routine.
* Param:
* connector - Initialized AsyncSocketConnector instance. Note that this
* connector descriptor might be destroyed asynchronously, before this
* routine returns.
*/
extern void 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 an 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_ */
|
