62
63
struct SConnectionTag;
63
typedef struct SConnectionTag* CONN; /* connection handle */
67
fCONN_Untie = 1, /* do not call flush method prior to every read */
68
fCONN_Supplement = 2 /* supplement I/O with extended return codes */
70
typedef unsigned int TCONN_Flags; /* bitwise OR of ECONN_Flags */
73
/* Create all data necessary to establish a new connection (merely bind it to
74
* the specified connector). Unsuccessful completion sets conn to 0, and
75
* leaves the connector intact (can be used again).
76
* NOTE1: The real connection will not be established right away. Instead,
77
* it will be established at the moment of the first call to one of
78
* "Flush", "Wait", "Write", or "Read" methods.
79
* NOTE2: "Connection establishment" at this level of abstraction may differ
80
* from actual link establishment at the underlying connector's level.
81
* NOTE3: Initial timeout values are set to kDefaultTimeout, meaning
82
* that connector-specific timeouts are in force for the connection.
64
typedef struct SConnectionTag* CONN; /**< connection handle */
67
/** CONN flags should be kept compatible with CConn_IOStream::TConn_Flags.
70
fCONN_Untie = 1, /**< do not call flush method prior to every read */
71
fCONN_Supplement = 64 /**< supplement I/O with extended return codes */
73
typedef unsigned int TCONN_Flags; /**< bitwise OR of ECONN_Flag */
76
/** Create all data necessary to establish a new connection (merely bind it to
77
* the specified connector).
78
* Unsuccessful completion sets "*conn" to NULL, and leaves the connector
79
* intact (can be used again).
80
* @note Connection is not established right away but at the moment of the
81
* first call to one of "Flush", "Wait", "Write", or "Read" methods.
82
* @note "Connection establishment" at this level of abstraction may differ
83
* from actual link establishment at the underlying connector's level.
84
* @note Initial timeout values are set to kDefaultTimeout, meaning
85
* that connector-specific timeouts are in force for the connection.
84
89
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_CreateEx
85
(CONNECTOR connector, /* [in] connector */
86
TCONN_Flags flags, /* [in] connection flags */
87
CONN* conn /* [out] handle of the created connection */
90
(CONNECTOR connector, /**< [in] connector */
91
TCONN_Flags flags, /**< [in] connection flags */
92
CONN* conn /**< [out] handle of the created connection */
90
/* Same as CONN_CreateEx() called with 0 in the "flags" parameter */
95
/** Same as CONN_CreateEx() called with 0 in the "flags" parameter */
91
96
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Create
92
(CONNECTOR connector, /* [in] connector */
93
CONN* conn /* [out] handle of the created connection */
97
(CONNECTOR connector, /**< [in] connector */
98
CONN* conn /**< [out] handle of the created connection */
97
/* Reinit using new "connector".
98
* If "conn" is already opened then close the current connection at first,
102
/** Reinit using new "connector".
103
* If "conn" is already opened, then close the current connection first,
99
104
* even if "connector" is just the same as the current connector.
100
* If "connector" is NULL then close and destroy the incumbent, and leave
105
* If "connector" is NULL, then close and destroy the incumbent, and leave
101
106
* the connection empty (effective way to destroy connector(s)).
102
* NOTE: Although it closes the previous connection immediately, however it
103
* does not open the new connection right away: see notes on "Create".
107
* @note Although it closes the previous connection immediately, however it
108
* does not open the new connection right away: see notes in "Create".
110
* CONN_Create, CONN_Close
105
112
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_ReInit
106
(CONN conn, /* [in] connection handle */
107
CONNECTOR connector /* [in] new connector */
113
(CONN conn, /**< [in] connection handle */
114
CONNECTOR connector /**< [in] new connector */
111
/* Get verbal representation of connection type as a character string.
112
* Note that the returned value is only valid until the next
113
* I/O operation in the connection. Return value NULL denotes
114
* unknown connection type.
118
/** Get verbal representation of connection type as a character string.
119
* Note that the returned value is only valid until the next I/O operation in
120
* the connection. Return value NULL denotes unknown connection type.
116
122
extern NCBI_XCONNECT_EXPORT const char* CONN_GetType
117
(CONN conn /* [in] connection handle */
123
(CONN conn /**< [in] connection handle */
121
/* Get read ("event" == eIO_Read) or write ("event" == eIO_Write)
127
/** Get read ("event" == eIO_Read) or write ("event" == eIO_Write)
122
128
* position within the connection.
123
129
* Positions are advanced from 0 on, and only concerning I/O that has
124
130
* caused calling to the actual connector's "read" (i.e. pushbacks
141
147
* by the returned string when the description is no longer needed.
143
149
extern NCBI_XCONNECT_EXPORT char* CONN_Description
144
(CONN conn /* [in] connection handle */
150
(CONN conn /**< [in] connection handle */
148
/* Specify timeout for the connection I/O, including "Connect" (aka "Open")
154
/** Specify timeout for the connection I/O, including "Connect" (aka "Open")
149
155
* and "Close". May be called at any time during the connection lifetime.
150
* NOTE1: if "new_timeout" is NULL then set the timeout to be infinite.
151
* NOTE2: if "new_timeout" is kDefaultTimeout then an underlying,
156
* @note If "timeout" is NULL then set the timeout to be infinite.
157
* @note If "timeout" is kDefaultTimeout then an underlying,
152
158
* connector-specific value is used (this is the default).
154
160
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetTimeout
155
(CONN conn, /* [in] connection handle */
156
EIO_Event event, /* [in] I/O direction */
157
const STimeout* new_timeout /* [in] new timeout */
161
(CONN conn, /**< [in] connection handle */
162
EIO_Event event, /**< [in] I/O direction */
163
const STimeout* timeout /**< [in] new timeout */
161
/* Retrieve current timeout (return NULL if it is infinite).
167
/** Retrieve current timeout (return NULL if it is infinite).
162
168
* The returned pointer is guaranteed to point to a valid timeout structure,
163
169
* or to be either NULL or kDefaultTimeout until next CONN_SetTimeout()
164
170
* or CONN_Close().
166
172
extern NCBI_XCONNECT_EXPORT const STimeout* CONN_GetTimeout
167
(CONN conn, /* [in] connection handle */
168
EIO_Event event /* [in] I/O direction, not "eIO_ReadWrite" */
173
(CONN conn, /**< [in] connection handle */
174
EIO_Event event /**< [in] I/O direction, not "eIO_ReadWrite"! */
172
/* Block on the connection until it becomes available for either read or
173
* write (dep. on "event"), until timeout expires, or until any error.
174
* NOTE: "timeout" can also be one of two special values:
175
* NULL (means infinite), kDefaultTimeout (connector-defined).
178
/** Block on the connection until it becomes available for either reading or
179
* writing (depending on "event"), until timeout expires, or until any error.
180
* @note "timeout" can also be one of the two special values:
181
* * NULL (for infinite timeout, also as kInfiniteTimeout);
182
* * kDefaultTimeout (connector-defined).
184
* CONN_Read, CONN_Write
177
186
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Wait
178
(CONN conn, /* [in] connection handle */
179
EIO_Event event, /* [in] can be either eIO_Read or eIO_Write only! */
180
const STimeout* timeout /* [in] the maximal wait time */
187
(CONN conn, /**< [in] connection handle */
188
EIO_Event event, /**< [in] can only be either of eIO_Read, IO_Write */
189
const STimeout* timeout /**< [in] the maximal wait time */
184
/* Write up to "size" bytes from the buffer "buf" to the connection.
193
/** Write up to "size" bytes from the buffer "buf" to the connection.
185
194
* Return the number of actually written bytes in "*n_written".
186
* It may not return eIO_Success if no data at all can be written before
187
* the write timeout expired or an error occurred.
195
* May not return eIO_Success if no data at all can be written before
196
* the write timeout expires or an error occurs.
188
197
* Parameter "how" modifies the write behavior:
189
* eIO_WritePlain -- return immediately after having written as little
190
* as 1 byte of data, or if an error has occurred;
191
* eIO_WritePersist -- return only after having written all of the data from
192
* "buf" (eIO_Success), or if an error has occurred
193
* (fewer bytes written, non-eIO_Success).
194
* NOTE: See CONN_SetTimeout() for how to set the write timeout.
198
* * @var eIO_WritePlain
199
* return immediately after having written as little
200
* as 1 byte of data (return eIO_Success), or if an
201
* error has occurred (and "*n_written == 0");
202
* * @var eIO_WritePersist
203
* return only after having written all of the data from
204
* "buf" (return eIO_Success), or if an error has
205
* occurred (fewer bytes written, non-eIO_Success);
206
* * @var eIO_WriteSupplement
207
* same as eIO_WritePlain but can return non-eIO_Success
208
* even with some data written (as indicated by
209
* "*n_written"), to signify that an error has occurred
210
* past the just written block of data.
211
* @note See CONN_SetTimeout() for how to set the write timeout.
196
215
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Write
197
(CONN conn, /* [in] connection handle */
198
const void* buf, /* [in] pointer to the data buffer to write */
199
size_t size, /* [in] # of bytes to write */
200
size_t* n_written, /* [out, non-NULL] # of actually written bytes */
201
EIO_WriteMethod how /* [in] eIO_WritePlain or eIO_WritePersist */
216
(CONN conn, /**< [in] connection handle */
217
const void* buf, /**< [in] pointer to the data buffer to write */
218
size_t size, /**< [in] # of bytes to write */
219
size_t* n_written, /**< [out] non-NULL, # of actually written bytes*/
220
EIO_WriteMethod how /**< [in] eIO_WritePlain or eIO_WritePersist */
205
/* Push back "size" bytes from the buffer "buf" into connection.
224
/** Push back "size" bytes from the buffer "buf" into connection.
206
225
* Return eIO_Success on success, other code on error.
207
* NOTE1: The data pushed back may not necessarily be the same as
208
* previously obtained from the connection.
209
* NOTE2: Upon a following read operation, the pushed back data are
226
* @note The data pushed back may not necessarily be the same as
227
* previously obtained from the connection.
228
* @note Upon a following read operation, the pushed back data are
231
* CONN_Read, CONN_Write
212
233
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_PushBack
213
(CONN conn, /* [in] connection handle */
214
const void* buf, /* [in] pointer to the data being pushed back */
215
size_t size /* [in] # of bytes to push back */
234
(CONN conn, /**< [in] connection handle */
235
const void* buf, /**< [in] pointer to the data being pushed back */
236
size_t size /**< [in] # of bytes to push back */
219
/* Explicitly flush connection from any pending data written by CONN_Write().
220
* NOTE1: CONN_Flush() effectively opens connection (if it wasn't open yet).
221
* NOTE2: Connection considered open if underlying connector's "Open" method
222
* has successfully executed; an actual data link may not yet exist.
223
* NOTE3: CONN_Read() always calls CONN_Flush() before proceeding; so does
224
* CONN_Close() but only if the connection is already open.
240
/** Explicitly flush connection from any pending data written by CONN_Write().
241
* @note CONN_Flush() effectively opens connection (if it wasn't open yet).
242
* @note Connection considered open if underlying connector's "Open" method
243
* has successfully executed; an actual data link may not yet exist.
244
* @note CONN_Read() always calls CONN_Flush() before proceeding (unless the
245
* connection was created with fCONN_Untie); so does CONN_Close() but
246
* only if the connection is already open.
248
* CONN_Read, CONN_Write, CONN_Close
226
250
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Flush
227
(CONN conn /* [in] connection handle */
251
(CONN conn /**< [in] connection handle */
231
/* Read up to "size" bytes from connection to the buffer pointed to by "buf".
255
/** Read up to "size" bytes from connection to the buffer pointed to by "buf".
232
256
* Return the number of actually read bytes in "*n_read".
233
257
* May not return eIO_Success if no data at all can be read before
234
* the read timeout expired or an error occurred.
258
* the read timeout expires or an error occurs.
235
260
* Parameter "how" modifies the read behavior:
236
* eIO_ReadPlain -- return immediately after having read as many as
237
* 1 byte from connection, or if an error has occurred;
238
* eIO_ReadPeek -- eIO_ReadPlain but don't discard read data from CONN;
239
* eIO_ReadPersist -- return only after having filled full "buf" with data
240
* (exactly "size" bytes, eIO_Success), or if an error
241
* has occurred (fewer bytes, non-eIO_Success).
242
* NOTE: See CONN_SetTimeout() for how to set the read timeout.
261
* * @var eIO_ReadPlain
262
* return immediately after having read as many as
263
* 1 byte from connection (return eIO_Success), or
264
* if an error has occurred (and "*n_read == 0");
265
* * @var eIO_ReadPeek
266
* eIO_ReadPlain but don't discard data read from CONN;
267
* * @var eIO_ReadPersist
268
* return only after having filled full "buf" with data
269
* (exactly "size" bytes, eIO_Success), or if an error
270
* has occurred (fewer bytes, non-eIO_Success);
271
* * @var eIO_ReadSupplement
272
* same as eIO_ReadPlain but can return non-eIO_Success
273
* even with some read data (as indicated by
274
* "*n_read"), to show that an error has been following
275
* the just read block of data (eg eIO_Closed for EOF).
276
* @note See CONN_SetTimeout() for how to set the read timeout.
278
* CONN_SetTimeout, CONN_ReadLine
244
280
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Read
245
(CONN conn, /* [in] connection handle */
246
void* buf, /* [out] memory buffer to read to */
247
size_t size, /* [in] max. # of bytes to read */
248
size_t* n_read, /* [out, non-NULL] # of actually read bytes */
249
EIO_ReadMethod how /* [in] read/peek | persist */
281
(CONN conn, /**< [in] connection handle */
282
void* buf, /**< [out] memory buffer to read to */
283
size_t size, /**< [in] max. # of bytes to read */
284
size_t* n_read, /**< [out] non-NULL, # of actually read bytes */
285
EIO_ReadMethod how /**< [in] peek/read/persist */
253
/* Read up to "size" bytes from connection into the string buffer pointed
289
/** Read up to "size" bytes from connection into the string buffer pointed
254
290
* to by "line". Stop reading if either '\n' or an error is encountered.
255
291
* Replace '\n' with '\0'. Upon return "*n_read" contains the number
256
292
* of characters written to "line", not including the terminating '\0'.
257
293
* If not enough space provided in "line" to accomodate the '\0'-terminated
258
294
* line, then all "size" bytes are used up and "*n_read" is equal to "size"
259
295
* upon return - this is the only case when "line" will not be '\0'-terminated.
260
297
* Return code advises the caller whether another read can be attempted:
261
* eIO_Success -- read completed successfully, keep reading;
262
* other code -- an error occurred, and further attempt may fail.
298
* * eIO_Success -- read completed successfully, keep reading;
299
* * other code -- an error occurred, and further read attempt may fail.
264
301
* This call utilizes eIO_Read timeout as set by CONN_SetTimeout().
303
* CONN_Read, CONN_SetTimeout
266
305
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_ReadLine
306
(CONN conn, /**< [in] connection handle */
307
char* line, /**< [out] buffer to read to */
308
size_t size, /**< [in] buffer size */
309
size_t* n_read /**< [out] line length */
274
/* Obtain status of the last IO operation. This is NOT a completion
275
* code of the last CONN-call, but rather a status from the lower level
313
/** Obtain status of the last I/O operation. This is NOT a completion
314
* code of the last CONN call, but rather some status from a lower level
315
* connector's layer (if available).
316
* @par Special case: eIO_Open as "dir" checks whether the connection is in
317
* an open state (which means the underlying connector has been successfully
318
* opened, but does not assure/check availability for any data or I/O), and
319
* returns eIO_Success if it is, or an error code otherwise.
321
* CONN_Create, CONN_Read, CONN_Write, CONN_Flush
278
323
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Status
279
(CONN conn, /* [in] connection handle */
280
EIO_Event dir /* [in] = {eIO_Read | eIO_Write} */
284
/* Cancel the connection's I/O ability.
285
* This is *not* connection closure, but any data extraction or
286
* insertion (Read/Write) will be effectively rejected after this call
287
* (and eIO_Interrupt will result, same for CONN_Status()).
288
* CONN_Close() is still required to release internal connection structures.
290
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Cancel
291
(CONN conn /* [in] connection handle */
295
/* Close the connection, destroy all relevant internal data.
296
* NOTE: whatever error code is returned, the connection handle "conn"
297
* will have become invalid (so, you should not use it anymore).
324
(CONN conn, /**< [in] connection handle */
325
EIO_Event dir /**< [in] eIO_Read or eIO_Write */
329
/** Close the connection and destroy all relevant internal data.
330
* @note Whatever the error code is returned, the connection handle "conn"
331
* will have become invalid (so, it should not be used anymore).
299
335
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Close
300
(CONN conn /* [in] connection handle */
336
(CONN conn /**< [in] connection handle */
304
/* Set user callback function to be called upon an event specified by the
340
/** Set user callback function to be called upon an event specified by the
305
341
* callback type. Note that the callback function is always called prior
306
342
* to the event to happen, e.g. the eCONN_OnClose callback is called when
307
* the connection is about to close, but have not yet been closed.
343
* the connection is about to close, but has not yet been closed.
308
345
* The callback function is supplied with 3 arguments: the connection handle,
309
346
* a type of event, and a user data (specified when the callback was set).
310
347
* CONN_SetCallback() stores previous callback in "old_cb" (if it is not NULL).
311
* The callbacks are acivated only once (they get reset each time prior to
312
* been actually called), so the code that wants to get callbacks repeatedly
313
* must reinstate them as necessary with CONN_SetCallback() calls
314
* (e.g. from inside the callbacks themselves).
315
* Normally, callback would return eIO_Success; non-eIO_Success return
316
* value causes return to the caller level (with possibly some processing
317
* already completed by then, e.g. such as a partial read for eCONN_OnRead).
349
* The callbacks remain valid until they are explicitly changed / de-activated
350
* or the connection becomes closed.
352
* This means that if a callback is intercepted and then relayed to the old
353
* handler, the interceptor may not assume the callback remains set, and
354
* must re-instate itself upon each upcall of the old handler (in general).
356
* Normally, callback would return eIO_Success and let the operation continue;
357
* non-eIO_Success return value causes it to be returned to the caller level
358
* (but possibly with some processing already completed by then, e.g. such as
359
* a partial read for eCONN_OnRead from an internal connection buffer).
360
* @note eIO_Interrupt returned from the callback switches connection into a
361
* cancelled state irreversibly, causing any further I/O for this handle to
362
* fail with eIO_Interrupt.
363
* @note non-eIO_Success from an eCONN_OnClose callback cannot postpone the
364
* connection closure (but the error code is still passed through to the user).
365
* @note eCONN_OnTimeout can restart the I/O that has timed out by returning
368
* CONN_Read, CONN_Write, CONN_Close
320
eCONN_OnClose = 0, /* NB: connection has been flushed prior to the call*/
321
eCONN_OnRead = 1, /* Read from connector is about to occur */
322
eCONN_OnWrite = 2, /* Write to connector is about to occur */
323
eCONN_OnCancel = 3 /* CONN_Cancel() is about to take effect */
371
eCONN_OnClose = 0, /**< NB: CONN has been flushed prior to the call */
372
eCONN_OnRead = 1, /**< Read from connector is about to occur */
373
eCONN_OnWrite = 2, /**< Write to connector is about to occur */
374
eCONN_OnFlush = 3, /**< Connector is about to be flushed */
375
eCONN_OnTimeout = 4 /**< Connector I/O has timed out */
324
376
} ECONN_Callback;
325
#define CONN_N_CALLBACKS 4
377
#define CONN_N_CALLBACKS 5
327
379
typedef EIO_Status (*FCONN_Callback)(CONN conn,ECONN_Callback type,void* data);
330
FCONN_Callback func; /* Function to call on the event */
331
void* data; /* Data to pass to the callback as its last arg */
382
FCONN_Callback func; /**< function to call on the event */
383
void* data; /**< data to pass to the callback as its last arg */
332
384
} SCONN_Callback;
334
386
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetCallback
335
(CONN conn, /* [in] connection to set callback for */
336
ECONN_Callback type, /* [in] callback type */
337
const SCONN_Callback* new_cb, /* [in] callback to set (may be 0 to reset) */
338
SCONN_Callback* old_cb /* [out] to save old callback at (may be 0) */
387
(CONN conn, /**< [in] connection to set callback for */
388
ECONN_Callback type, /**< [in] callback type */
389
const SCONN_Callback* new_cb, /**< [in] callback to set (NULL to reset) */
390
SCONN_Callback* old_cb /**< [out] to save old callback at (may be 0)*/
394
/** Get an underlying SOCK handle for connection that is implemented as a
395
* socket. Not a eIO_Success return code guarantees "*sock" is NULL.
396
* Set "*sock" to NULL when no socket handle can be obtained.
397
* @note The returned SOCK object remains in use by the connection.
399
* SOCK, SOCK_GetOSHandleEx
401
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_GetSOCK
402
(CONN conn, /**< [in] connection handle */
403
SOCK* sock /**< [out] non-NULL, to get the SOCK to */
407
/** Set connection processing flags.
409
* eIO_Success on success, other error code on error.
411
* CONN_CreateEx, CONN_GetFlags
413
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetFlags
414
(CONN conn, /**< [in] connection handle */
415
TCONN_Flags flags /**< [in] new connection flags */
419
/** Get connection processing flags currently in effect.
421
* Current value of the flags.
423
* CONN_CreateEx, CONN_SetFlags
425
extern NCBI_XCONNECT_EXPORT TCONN_Flags CONN_GetFlags
426
(CONN conn /**< [in] connection handle */
342
430
#ifdef __cplusplus
343
431
} /* extern "C" */
added
removed
connect/ncbi_connection.h
