← Back to branch summary

~ubuntu-branches/ubuntu/raring/ncbi-tools6/raring

« back to all changes in this revision

Viewing changes to connect/ncbi_connection.h

  • Committer: Package Import Robot
  • Author(s): Aaron M. Ucko
  • Date: 2011-09-05 18:55:02 UTC
  • mfrom: (1.1.11 upstream)
  • Revision ID: package-import@ubuntu.com-20110905185502-iuvmoe65ytljhckn
Tags: 6.1.20110713-1
* New upstream release.
* debian/*.symbols: update accordingly.
* make/makeshlb.unx: link libcn3dOGL.so against -lm for sqrt.
* doc/man/*.1: update for new release.
* debian/rules:
  - (VIB): add asnmacro, as upstream takes care to publish binaries thereof.
  - Retire obsolete multiarch-unaware checks for libpthread.
  - Fully modernize Debhelper usage; in particular, transition to overrides.
* debian/compat: advance to 9 per rules modernization.
* debian/ncbi-tools-bin.install: add asnmacro.
* make/makenet.unx: link asnmacro only against libraries it directly needs.
* doc/man/asnmacro.1: give asnmacro a man page.
* doc/man/Psequin.1: list it in SEE ALSO.
* network/id1arch/idfetch.c: revert redundant change (from #295110).
* Convert to multiarch.
  - debian/rules: Install libraries (and ncbithr.o) to multiarch directories.
  - debian/lib*.install: match multiarch library paths.
  - debian/control:
    + Build-Depends: debhelper (>= 8.1.3~), implying a recent dpkg-dev.
    + Set Multi-Arch: as appropriate across the board, and specify
      Pre-Depends: ${misc:Pre-Depends} for runtime libraries.
* debian/*.lintian-overrides: drop leading slashes for Lintian 2.5.x.
* debian/control: Standards-Version: 3.9.2 (already compliant).

Show diffs side-by-side

added added

removed removed

Lines of Context:
connect/ncbi_connection.h
1
1
#ifndef CONNECT___NCBI_CONNECTION__H
2
2
#define CONNECT___NCBI_CONNECTION__H
3
3
 
4
 
/* $Id: ncbi_connection.h,v 6.22 2010/02/01 13:54:31 kazimird Exp $
 
4
/* $Id: ncbi_connection.h,v 6.28 2011/06/02 14:14:32 kazimird Exp $
5
5
 * ===========================================================================
6
6
 *
7
7
 *                            PUBLIC DOMAIN NOTICE
63
63
typedef struct SConnectionTag* CONN;      /* connection handle */
64
64
 
65
65
 
66
 
/* Compose all data necessary to establish a new connection
67
 
 * (merely bind it to the specified connector). Unsuccessful completion
68
 
 * sets conn to 0, and leaves connector intact (can be used again).
69
 
 * NOTE1:  The real connection will not be established right away. Instead,
 
66
typedef enum {
 
67
    fCONN_Untie      = 1,  /* do not call flush method prior to every read   */
 
68
    fCONN_Supplement = 2   /* supplement I/O with extended return codes      */
 
69
} ECONN_Flags;
 
70
typedef unsigned int TCONN_Flags;  /* bitwise OR of ECONN_Flags   */
 
71
 
 
72
 
 
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,
70
77
 *         it will be established at the moment of the first call to one of
71
78
 *         "Flush", "Wait", "Write", or "Read" methods.
72
79
 * NOTE2:  "Connection establishment" at this level of abstraction may differ
73
80
 *         from actual link establishment at the underlying connector's level.
74
 
 * NOTE3:  Initial timeout values are set to CONN_DEFAULT_TIMEOUT, meaning
 
81
 * NOTE3:  Initial timeout values are set to kDefaultTimeout, meaning
75
82
 *         that connector-specific timeouts are in force for the connection.
76
83
 */
 
84
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 */
 
88
 );
 
89
 
 
90
/* Same as CONN_CreateEx() called with 0 in the "flags" parameter */
77
91
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Create
78
 
(CONNECTOR connector,  /* [in]  connector                        */
79
 
 CONN*     conn        /* [out] handle of the created connection */
 
92
(CONNECTOR   connector,  /* [in]  connector                        */
 
93
 CONN*       conn        /* [out] handle of the created connection */
80
94
 );
81
95
 
82
96
 
83
 
/* Reinit, using "connector".
 
97
/* Reinit using new "connector".
84
98
 * If "conn" is already opened then close the current connection at first,
85
99
 * even if "connector" is just the same as the current connector.
86
 
 * If "connector" is NULL then close and destroy current connector, and leave
87
 
 * connection empty (effective way to destroy connector(s)).
 
100
 * If "connector" is NULL then close and destroy the incumbent, and leave
 
101
 * the connection empty (effective way to destroy connector(s)).
88
102
 * NOTE:  Although it closes the previous connection immediately, however it
89
 
 *        does not open the new connection right away -- see notes to "Create".
 
103
 *        does not open the new connection right away:  see notes on "Create".
90
104
 */
91
105
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_ReInit
92
106
(CONN      conn,      /* [in] connection handle */
96
110
 
97
111
/* Get verbal representation of connection type as a character string.
98
112
 * Note that the returned value is only valid until the next
99
 
 * I/O operation in the connection. Return value NULL denotes
 
113
 * I/O operation in the connection.  Return value NULL denotes
100
114
 * unknown connection type.
101
115
 */
102
116
extern NCBI_XCONNECT_EXPORT const char* CONN_GetType
104
118
 );
105
119
 
106
120
 
107
 
/* Return human-readable description of the connection as a character
108
 
 * 0-terminated string. The string is not guaranteed to have any
 
121
/* Get read ("event" == eIO_Read) or write ("event" == eIO_Write)
 
122
 * position within the connection.
 
123
 * Positions are advanced from 0 on, and only concerning I/O that has
 
124
 * caused calling to the actual connector's "read" (i.e. pushbacks
 
125
 * never considered, and peeks -- not always) and "write" methods.
 
126
 * Special case:  eIO_Open as "event" causes to clear both positions
 
127
 * with 0, and to return 0.
 
128
 */
 
129
extern NCBI_XCONNECT_EXPORT TNCBI_BigCount CONN_GetPosition
 
130
(CONN      conn,  /* [in]  connection handle */ 
 
131
 EIO_Event event  /* [in]  see description   */
 
132
 );
 
133
 
 
134
 
 
135
/* Return a human-readable description of the connection as a character
 
136
 * '\0'-terminated string.  The string is not guaranteed to have any
109
137
 * particular format and is intended solely for something like
110
 
 * logging and debugging. Return NULL if the connection cannot
 
138
 * logging and debugging.  Return NULL if the connection cannot
111
139
 * provide any description information (or if it is in a bad state).
112
 
 * Application program is responsible to deallocate the space occupied
113
 
 * by the returned string calling free() when the description is no longer
114
 
 * needed.
 
140
 * Application program must call free() to deallocate space occupied
 
141
 * by the returned string when the description is no longer needed.
115
142
 */
116
143
extern NCBI_XCONNECT_EXPORT char* CONN_Description
117
144
(CONN conn  /* [in]  connection handle */
118
145
 );
119
146
 
120
147
 
121
 
/* Specify timeout for the connection I/O (including "Connect" (aka "Open")
122
 
 * and "Close"). May be called at any time during the connection lifetime.
 
148
/* Specify timeout for the connection I/O, including "Connect" (aka "Open")
 
149
 * and "Close".  May be called at any time during the connection lifetime.
123
150
 * NOTE1:  if "new_timeout" is NULL then set the timeout to be infinite.
124
 
 * NOTE2:  if "new_timeout" is CONN_DEFAULT_TIMEOUT then underlying
 
151
 * NOTE2:  if "new_timeout" is kDefaultTimeout then an underlying,
125
152
 *         connector-specific value is used (this is the default).
126
153
 */
127
154
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetTimeout
132
159
 
133
160
 
134
161
/* Retrieve current timeout (return NULL if it is infinite).
135
 
 * The returned pointer is guaranteed to point to the valid timeout structure
136
 
 * (or be either NULL or CONN_DEFAULT_TIMEOUT) until the next "SetTimeout"
137
 
 * or "Close" method's call.
 
162
 * The returned pointer is guaranteed to point to a valid timeout structure,
 
163
 * or to be either NULL or kDefaultTimeout until next CONN_SetTimeout()
 
164
 * or CONN_Close().
138
165
 */
139
166
extern NCBI_XCONNECT_EXPORT const STimeout* CONN_GetTimeout
140
167
(CONN      conn,  /* [in] connection handle                  */
143
170
 
144
171
 
145
172
/* Block on the connection until it becomes available for either read or
146
 
 * write (dep. on "event"), or until the timeout expires, or until any error.
 
173
 * write (dep. on "event"), until timeout expires, or until any error.
147
174
 * NOTE:  "timeout" can also be one of two special values:
148
 
 *         NULL (means infinite), CONN_DEFAULT_TIMEOUT (connector-defined).
 
175
 *         NULL (means infinite), kDefaultTimeout (connector-defined).
149
176
 */
150
177
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Wait
151
 
(CONN            conn,    /* [in] connection handle                  */
152
 
 EIO_Event       event,   /* [in] can be eIO_Read or eIO_Write only! */
153
 
 const STimeout* timeout  /* [in] the maximal wait time              */
 
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                     */
154
181
 );
155
182
 
156
183
 
157
 
/* Write "size" bytes from the mem.buffer "buf" to the connection.
158
 
 * In "*n_written", return the number of successfully written bytes.
159
 
 * Parameter "how" modifies behavior of CONN_Write():
160
 
 * eIO_WritePlain   -- return eIO_Success if some data were written and
161
 
 *                     yet write timeout had not occurred, error otherwise;
162
 
 * eIO_WritePersist -- return eIO_Success only if all data were written and
163
 
 *                     yet write timeout had not occurred, error otherwise.
164
 
 * NOTE:  See CONN_SetTimeout() hoe to set write timeout.
 
184
/* Write up to "size" bytes from the buffer "buf" to the connection.
 
185
 * 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.
 
188
 * 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.
165
195
 */
166
196
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Write
167
197
(CONN            conn,      /* [in]  connection handle                     */ 
172
202
 );
173
203
 
174
204
 
175
 
/* Push back "size" bytes from the mem.buffer "buf" into connection.
176
 
 * Return eIO_Success on success, other code on an error.
177
 
 * NOTE1:  Data pushed back are not necessarily those taken from the
178
 
 *         connection before.
179
 
 * NOTE2:  Upon successive read operation, the pushed back data are
 
205
/* Push back "size" bytes from the buffer "buf" into connection.
 
206
 * 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
180
210
 *         taken out first.
181
211
 */
182
212
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_PushBack
186
216
 );
187
217
 
188
218
 
189
 
/* Explicitly flush to the connection all data written by "CONN_Write()".
 
219
/* Explicitly flush connection from any pending data written by CONN_Write().
190
220
 * NOTE1:  CONN_Flush() effectively opens connection (if it wasn't open yet).
191
221
 * NOTE2:  Connection considered open if underlying connector's "Open" method
192
 
 *         has successfully executed; actual data link may not yet exist.
193
 
 * NOTE3:  CONN_Read() always calls CONN_Flush() before proceeding.
194
 
 *         So does CONN_Close() but only if connection is was open before.
 
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.
195
225
 */
196
226
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Flush
197
227
(CONN        conn   /* [in] connection handle                      */
198
228
 );
199
229
 
200
230
 
201
 
/* Read up to "size" bytes from a connection to the buffer to pointed by "buf".
202
 
 * In "*n_read", return the number of successfully read bytes.
203
 
 * If there is absolutely no data available to read and the timeout (see
204
 
 * CONN_SetTimeout()) is expired then return eIO_Timeout (and "*n_read" := 0).
205
 
 * The arg "how" means:
206
 
 *   eIO_ReadPlain   -- read presently available data only and return
207
 
 *   eIO_ReadPeek    -- eIO_ReadPlain but dont discard read data from inp.queue
208
 
 *   eIO_ReadPersist -- try to read exactly "n" bytes;  return eIO_Timeout if
209
 
 *                      could not read the requested # of bytes, and read
210
 
 *                      timeout has expired.
 
231
/* Read up to "size" bytes from connection to the buffer pointed to by "buf".
 
232
 * Return the number of actually read bytes in "*n_read".
 
233
 * May not return eIO_Success if no data at all can be read before
 
234
 * the read timeout expired or an error occurred.
 
235
 * 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.
211
243
 */
212
244
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Read
213
245
(CONN           conn,   /* [in]  connection handle                  */
218
250
 );
219
251
 
220
252
 
221
 
/* Read up to "size" bytes from a connection into the string buffer pointed
 
253
/* Read up to "size" bytes from connection into the string buffer pointed
222
254
 * to by "line".  Stop reading if either '\n' or an error is encountered.
223
255
 * Replace '\n' with '\0'.  Upon return "*n_read" contains the number
224
256
 * of characters written to "line", not including the terminating '\0'.
225
257
 * If not enough space provided in "line" to accomodate the '\0'-terminated
226
 
 * line, then all "size" bytes are used and "*n_read" equals "size" on return.
227
 
 * This is the only case when "line" will not be '\0'-terminated.
228
 
 * Return code advises the caller whether another line read can be attempted:
 
258
 * line, then all "size" bytes are used up and "*n_read" is equal to "size"
 
259
 * upon return - this is the only case when "line" will not be '\0'-terminated.
 
260
 * Return code advises the caller whether another read can be attempted:
229
261
 *   eIO_Success -- read completed successfully, keep reading;
230
262
 *   other code  -- an error occurred, and further attempt may fail.
231
263
 *
249
281
 );
250
282
 
251
283
 
252
 
/* Close the connection, destroy relevant internal data.
 
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.
 
289
 */
 
290
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Cancel
 
291
(CONN conn  /* [in] connection handle */
 
292
 );
 
293
 
 
294
 
 
295
/* Close the connection, destroy all relevant internal data.
253
296
 * NOTE:  whatever error code is returned, the connection handle "conn"
254
 
 *        will become invalid (so, you should not use it anymore).
 
297
 *        will have become invalid (so, you should not use it anymore).
255
298
 */
256
299
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Close
257
300
(CONN conn  /* [in] connection handle */
259
302
 
260
303
 
261
304
/* Set user callback function to be called upon an event specified by the
262
 
 * callback type. Note that the callback function is always called prior to
263
 
 * the event to happen, e.g. the eCONN_OnClose callback is called when
264
 
 * the connection is about to close, but not closed yet.
265
 
 * The callback function is supplied with 3 arguments: connection handle,
266
 
 * type of event, and user data (specified when the callback was set).
267
 
 * CONN_SetCallback stores previous callback in "old_cb" (if it is not NULL).
 
305
 * callback type.  Note that the callback function is always called prior
 
306
 * 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.
 
308
 * The callback function is supplied with 3 arguments: the connection handle,
 
309
 * a type of event, and a user data (specified when the callback was set).
 
310
 * 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).
268
318
 */
269
319
typedef enum {
270
 
    eCONN_OnClose = 0
 
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            */
271
324
} ECONN_Callback;
272
 
#define CONN_N_CALLBACKS 1
 
325
#define CONN_N_CALLBACKS 4
273
326
 
274
 
typedef void (*FConnCallback)(CONN conn, ECONN_Callback type, void* data);
 
327
typedef EIO_Status (*FCONN_Callback)(CONN conn,ECONN_Callback type,void* data);
275
328
 
276
329
typedef struct {
277
 
    FConnCallback func;  /* Function to call on event                */
278
 
    void*         data;  /* Data to pass to the callback as last arg */
 
330
    FCONN_Callback func;  /* Function to call on the event                */
 
331
    void*          data;  /* Data to pass to the callback as its last arg */
279
332
} SCONN_Callback;
280
333
 
281
334
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetCallback
282
 
(CONN                  conn,    /* [in]  connection to set callback for     */
283
 
 ECONN_Callback        type,    /* [in]  callback type                      */
284
 
 const SCONN_Callback* new_cb,  /* [in]  callback to set (may be 0)         */
285
 
 SCONN_Callback*       old_cb   /* [out] to save old callback at (may be 0) */
 
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)  */
286
339
);
287
340
 
288
341