|
NCBI Home IEB Home C Toolkit docs C++ Toolkit source browser C Toolkit source browser (2) |
NCBI C Toolkit Cross ReferenceC/connect/ncbi_connector.h |
source navigation diff markup identifier search freetext search file search |
1 #ifndef CONNECT___NCBI_CONNECTOR__H
2 #define CONNECT___NCBI_CONNECTOR__H
3
4 /* $Id: ncbi_connector.h,v 6.17 2007/09/04 20:25:30 kazimird Exp $
5 * ===========================================================================
6 *
7 * PUBLIC DOMAIN NOTICE
8 * National Center for Biotechnology Information
9 *
10 * This software/database is a "United States Government Work" under the
11 * terms of the United States Copyright Act. It was written as part of
12 * the author's official duties as a United States Government employee and
13 * thus cannot be copyrighted. This software/database is freely available
14 * to the public for use. The National Library of Medicine and the U.S.
15 * Government have not placed any restriction on its use or reproduction.
16 *
17 * Although all reasonable efforts have been taken to ensure the accuracy
18 * and reliability of the software and data, the NLM and the U.S.
19 * Government do not and cannot warrant the performance or results that
20 * may be obtained by using this software or data. The NLM and the U.S.
21 * Government disclaim all warranties, express or implied, including
22 * warranties of performance, merchantability or fitness for any particular
23 * purpose.
24 *
25 * Please cite the author in any work or product based on this material.
26 *
27 * ===========================================================================
28 *
29 * Author: Denis Vakatov
30 *
31 * File Description:
32 * Specifications to implement a connector("CONNECTOR") to be used to open
33 * and handle connection("CONN", see also in "ncbi_connection.[ch]") to an
34 * abstract I/O service. This is generally not for the public use.
35 * It is to be used in the modules that implement a particular connector.
36 *
37 */
38
39 #include <connect/ncbi_core.h>
40
41
42 /** @addtogroup Connectors
43 *
44 * @{
45 */
46
47
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
51
52
53 struct SConnectorTag;
54 typedef struct SConnectorTag* CONNECTOR; /* connector handle */
55
56
57 /* Function type definitions for the connector method table.
58 * The arguments & the behavior of "FConnector***" functions are mostly just
59 * the same as those for their counterparts "CONN_***" in ncbi_connection.h.
60 * First argument of these functions accepts a real connector handle
61 * rather than a connection handle("CONN").
62 * In every call, which has STimeout as an argument, this argument
63 * can be either NULL, CONN_DEFAULT_TIMEOUT, or other non-NULL pointer,
64 * pointing to finite timeout structure. NULL is treated as an infinite
65 * timeout, while CONN_DEFAULT_TIMEOUT means to use any timeout, which
66 * is somehow pre-defined by the connector itself.
67 */
68
69
70 /* Get the name of the connector (may be NULL on error)
71 */
72 typedef const char* (*FConnectorGetType)
73 (CONNECTOR connector
74 );
75
76
77 /* Get the human readable connector's description (may be NULL on error)
78 */
79 typedef char* (*FConnectorDescr)
80 (CONNECTOR connector
81 );
82
83
84 /* Open connection. Used to setup all related data structures,
85 * but not necessarily has to actually open the data channel.
86 */
87 typedef EIO_Status (*FConnectorOpen)
88 (CONNECTOR connector,
89 const STimeout* timeout
90 );
91
92
93 /* Wait until either read or write (dep. on the "direction" value) becomes
94 * available, or until "timeout" expires, or until error occurs.
95 * NOTE 1: FConnectorWait is guaranteed to be called after FConnectorOpen,
96 * and only if FConnectorOpen returned "eIO_Success".
97 * NOTE 2: "event" is guaranteed to be either "eIO_Read" or "eIO_Write".
98 */
99 typedef EIO_Status (*FConnectorWait)
100 (CONNECTOR connector,
101 EIO_Event event,
102 const STimeout* timeout
103 );
104
105
106 /* The passed "n_written" is always non-NULL, and "*n_written" is always zero.
107 * It returns "eIO_Success" if at least some data have been successfully
108 * written; other error code if no data at all have been written.
109 * It returns the # of successfully written data (in bytes) in "*n_written".
110 * NOTE: FConnectorWrite is guaranteed to be called after FConnectorOpen,
111 * and only if the latter succeeded (returned "eIO_Success").
112 */
113 typedef EIO_Status (*FConnectorWrite)
114 (CONNECTOR connector,
115 const void* buf,
116 size_t size,
117 size_t* n_written,
118 const STimeout* timeout
119 );
120
121
122 /* Flush yet unwritten output data, if any.
123 * NOTE: FConnectorFlush is guaranteed to be called after FConnectorOpen,
124 * and only if the latter succeeded (returned "eIO_Success").
125 */
126 typedef EIO_Status (*FConnectorFlush)
127 (CONNECTOR connector,
128 const STimeout* timeout
129 );
130
131
132 /* The passed "n_read" is always non-NULL, and "*n_read" is always zero.
133 * It returns "eIO_Success" if at least some data have been successfully
134 * read; other error code if no data at all have been read.
135 * The number of successfully read bytes returned in "*n_read".
136 * NOTE: FConnectorRead is guaranteed to be called after FConnectorOpen,
137 * and only if the latter succeeded (returned "eIO_Success").
138 */
139 typedef EIO_Status (*FConnectorRead)
140 (CONNECTOR connector,
141 void* buf,
142 size_t size,
143 size_t* n_read,
144 const STimeout* timeout
145 );
146
147 /* Obtain last I/O completion code from the transport level (connector).
148 * NOTE 1: FConnectorStatus is guaranteed to be called after FConnectorOpen,
149 * and only if the latter succeeded (returned "eIO_Success").
150 * NOTE 2: "direction" is guaranteed to be either "eIO_Read" or "eIO_Write".
151 * NOTE 3: Should return "eIO_Success" in case of inexistent (incomplete)
152 * low level transport, if any.
153 */
154 typedef EIO_Status (*FConnectorStatus)
155 (CONNECTOR connector,
156 EIO_Event direction
157 );
158
159
160 /* Close data link (if any) and cleanup related data structures.
161 * NOTE 1: FConnectorClose is guaranteed to be called after FConnectorOpen,
162 * and only if the latter succeeded (returned "eIO_Success").
163 * NOTE 2: FConnectorFlush gets called before FConnectorClose automatically.
164 */
165 typedef EIO_Status (*FConnectorClose)
166 (CONNECTOR connector,
167 const STimeout* timeout
168 );
169
170
171 /* Standard set of connector methods to handle a connection (corresponding
172 * connectors are also here), part of connection handle("CONN").
173 */
174 typedef struct {
175 FConnectorGetType get_type; CONNECTOR c_get_type;
176 FConnectorDescr descr; CONNECTOR c_descr;
177 FConnectorOpen open; CONNECTOR c_open;
178 FConnectorWait wait; CONNECTOR c_wait;
179 #ifdef IMPLEMENTED__CONN_WaitAsync
180 FConnectorWaitAsync wait_async; CONNECTOR c_wait_async;
181 #endif
182 FConnectorWrite write; CONNECTOR c_write;
183 FConnectorFlush flush; CONNECTOR c_flush;
184 FConnectorRead read; CONNECTOR c_read;
185 FConnectorStatus status; CONNECTOR c_status;
186 FConnectorClose close; CONNECTOR c_close;
187 const STimeout* default_timeout; /* default timeout pointer */
188 STimeout default_tmo; /* storage for default_timeout */
189 CONNECTOR list;
190 } SMetaConnector;
191
192
193 #define CONN_TWO2ONE(a, b) a##b
194
195 #define CONN_SET_METHOD(meta, method, function, connector) \
196 do { \
197 meta->method = function; \
198 meta->CONN_TWO2ONE(c_,method) = connector; \
199 } while (0);
200
201
202 #define CONN_SET_DEFAULT_TIMEOUT(meta, timeout) \
203 do { \
204 if (timeout) { \
205 meta->default_timeout = &meta->default_tmo; \
206 meta->default_tmo = *timeout; \
207 } else \
208 meta->default_timeout = 0; \
209 } while (0);
210
211
212 /* Insert a connector in the beginning of the connection's list of connectors.
213 */
214 extern NCBI_XCONNECT_EXPORT EIO_Status METACONN_Add
215 (SMetaConnector* meta,
216 CONNECTOR connector
217 );
218
219
220 /* Delete given "connector" all its descendants (all connectors if "connector"
221 * is 0) from the connections's list of connectors. FConnectorDestroy is
222 * called for each removed connector.
223 */
224 extern NCBI_XCONNECT_EXPORT EIO_Status METACONN_Remove
225 (SMetaConnector* meta,
226 CONNECTOR connector
227 );
228
229
230 /* Upcall on request to setup virtual function table (called from connection).
231 */
232 typedef void (*FSetupVTable)
233 (SMetaConnector* meta,
234 CONNECTOR connector
235 );
236
237
238 /* Destroy connector and its data handle. This is NOT a close request!
239 * Should not to be used on open connectors (that is, for those
240 * FConnectorClose has to be called first prior to this call).
241 */
242 typedef void (*FDestroy)
243 (CONNECTOR connector
244 );
245
246
247 /* Connector specification.
248 */
249 typedef struct SConnectorTag {
250 SMetaConnector* meta; /* back link to CONNECTION */
251 FSetupVTable setup; /* used in CONNECTION init */
252 FDestroy destroy; /* destroys handle, can be NULL */
253 void* handle; /* data handle of the connector */
254 CONNECTOR next; /* linked list */
255 } SConnector;
256
257
258 #ifdef IMPLEMENTED__CONN_WaitAsync
259 typedef struct {
260 CONN conn;
261 EIO_Event event;
262 FConnAsyncHandler handler;
263 void* data;
264 FConnAsyncCleanup cleanup;
265 } SConnectorAsyncHandler;
266
267 typedef void (*FConnectorAsyncHandler)
268 (SConnectorAsyncHandler* data,
269 EIO_Event event,
270 EIO_Status status
271 );
272
273 typedef EIO_Status (*FConnectorWaitAsync)
274 (CONNECTOR connector,
275 FConnectorAsyncHandler func,
276 SConnectorAsyncHandler* data
277 );
278 #endif /* IMPLEMENTED__CONN_WaitAsync */
279
280
281 #ifdef __cplusplus
282 } /* extern "C" */
283 #endif
284
285
286 /* @} */
287
288 #endif /* CONNECT___NCBI_CONNECTOR__H */
289 |
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more information. |