« back to all changes in this revision
Viewing changes to connect/ncbi_socket.h
- browse files at revision 8
- compare with another revision
- download diff
- download tarball
- view history from revision 8
- Committer: Bazaar Package Importer
- Author(s): Barry deFreese
- Date: 2006-07-19 23:28:07 UTC
- mfrom: (1.1.5 upstream)
- Revision ID: james.westby@ubuntu.com-20060719232807-et3cdmcjgmnyleyx
Tags: 6.1.20060507-3ubuntu1
Re-merge with Debian
- files added:
- algo/blast/api/blast_message_api.c
- files removed:
- debian/libvibrant6.install
- files modified:
- VERSION
added
removed
connect/ncbi_socket.h
1
1
#ifndef CONNECT___NCBI_SOCKET__H
2
2
#define CONNECT___NCBI_SOCKET__H
3
3
4
/* $Id: ncbi_socket.h,v 6.56 2005/07/19 19:54:56 lavr Exp $
4
/* $Id: ncbi_socket.h,v 6.61 2006/03/16 19:12:21 ucko Exp $
5
5
* ===========================================================================
6
6
*
7
7
* PUBLIC DOMAIN NOTICE
114
114
* SOCK_gethostbyname
115
115
* SOCK_gethostbyaddr
116
116
* SOCK_GetLoopbackAddress
117
* SOCK_StringToHostPort
118
* SOCK_HostPortToString
117
119
*
118
120
*/
119
121
140
142
*/
141
143
142
144
143
/* Network and host byte order enumeration type
145
/** Network and host byte order enumeration type
144
146
*/
145
147
typedef enum {
146
148
eNH_HostByteOrder,
148
150
} ENH_ByteOrder;
149
151
150
152
151
/* Forward declarations of the hidden socket internal structure, and
153
/** Forward declarations of the hidden socket internal structure, and
152
154
* their upper-level handles to use by the LSOCK_*() and SOCK_*() API
153
155
*/
154
156
struct LSOCK_tag; /* listening socket: internal storage */
182
184
/******************************************************************************
183
185
* Error & Data Logging
184
186
*
185
* NOTE: Use CORE_SetLOG() from "ncbi_core.h" to setup the log handler.
187
* @li <b>NOTE:</b> Use CORE_SetLOG() from "ncbi_core.h" to setup the log handler.
186
188
*/
187
189
188
190
189
/* By default ("log" == eDefault, which is eOff), the data is not logged.
190
* To start logging the data, call this func with "log" == eOn.
191
* To stop logging the data, call this func with "log" == eOff.
192
* Return prior setting.
191
/** By default ("log" == eDefault, which is eOff), the data is not logged.
192
* @param log
193
* To start logging the data, call this func with "log" == eOn.
194
* To stop logging the data, call this func with "log" == eOff.
195
* @return
196
* Prior setting.
193
197
*/
194
198
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetDataLoggingAPI
195
199
(ESwitch log
196
200
);
197
201
198
202
199
/* Control the data logging for socket "sock" individually.
200
* To reset to the global default behavior (as set by SOCK_SetDataLoggingAPI),
201
* call this function with "log" == eDefault.
202
* Return prior setting.
203
/** Control the data logging for socket "sock" individually.
204
* @param sock
205
* [in] socket handle
206
* @param log
207
* To reset to the global default behavior (as set by SOCK_SetDataLoggingAPI),
208
* call this function with "log" == eDefault.
209
* @return
210
* Return prior setting.
203
211
*/
204
212
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetDataLogging
205
213
(SOCK sock,
212
220
* I/O restart on signals
213
221
*/
214
222
215
216
/* By default ("on_off" == eDefault,eOff), I/O is restartable if interrupted.
217
* Return prior setting.
223
/** By default ("on_off" == eDefault,eOff), I/O is restartable if interrupted.
224
* @param on_off
225
*
226
* @return
227
* Prior setting.
218
228
*/
219
229
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetInterruptOnSignalAPI
220
230
(ESwitch on_off
221
231
);
222
232
223
233
224
/* Control sockets individually. eDefault causes the use of global API flag.
225
* Return prior setting.
234
/** Control sockets individually. eDefault causes the use of global API flag.
235
* @param sock
236
* [in] socket handle
237
* @param on_off
238
*
239
* @return
240
* Prior setting.
226
241
*/
227
242
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetInterruptOnSignal
228
243
(SOCK sock,
238
253
239
254
/* By default ("on_off" == eDefault,eOff), address is not marked for reuse
240
255
* in SOCK, but is always reused for LSOCK.
241
* Return prior setting.
256
* @param on_off
257
*
258
* @return
259
* Prior setting.
242
260
*/
243
261
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReuseAddressAPI
244
262
(ESwitch on_off
245
263
);
246
264
247
265
248
/* Control sockets individually (Note: only boolean value is available here.)
249
* No return value is available.
266
/** Control sockets individually (Note: only boolean value is available here.)
267
* @param sock
268
* [in] socket handle
269
* @param on_off
270
*
271
* @return
272
* No return value is available.
250
273
*/
251
274
extern NCBI_XCONNECT_EXPORT void SOCK_SetReuseAddress
252
(SOCK sock,
253
int/*bool*/ on_off);
275
(SOCK sock,
276
int/**bool*/ on_off);
254
277
255
278
256
279
259
282
*/
260
283
261
284
262
/*
285
/**
286
* @param timeout
287
*
263
288
*/
264
289
extern NCBI_XCONNECT_EXPORT const STimeout*SOCK_SetSelectInternalRestartTimeout
265
290
(const STimeout* timeout);
266
291
267
292
268
/* By default (on UNIX platforms) the SOCK API functions automagically call
293
/** By default (on UNIX platforms) the SOCK API functions automagically call
269
294
* "signal(SIGPIPE, SIG_IGN)" on initialization. To prohibit this feature,
270
295
* you must call SOCK_AllowSigPipeAPI() before you call any other
271
296
* function from the SOCK API.
273
298
extern NCBI_XCONNECT_EXPORT void SOCK_AllowSigPipeAPI(void);
274
299
275
300
276
/* Initialize all internal/system data & resources to be used by the SOCK API.
277
* NOTE:
301
/** Initialize all internal/system data & resources to be used by the SOCK API.
302
* @li <b>NOTE:</b>
278
303
* You can safely call it more than once; just, all calls after the first
279
304
* one will have no result.
280
* NOTE:
305
* @li <b>NOTE:</b>
281
306
* Usually, SOCK API does not require an explicit initialization -- as it is
282
307
* guaranteed to initialize itself automagically, in one of API functions,
283
308
* when necessary. Yet, see the "Multi Thread safety" remark above.
284
* NOTE:
309
* @li <b>NOTE:</b>
285
310
* This call, when used for the very first time in the application, enqueues
286
311
* SOCK_ShutdownAPI() to be called upon application exit on plaftorms that
287
312
* provide this functionality. In any case, the application can opt for
290
315
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_InitializeAPI(void);
291
316
292
317
293
/* Cleanup; destroy all internal/system data & resources used by the SOCK API.
318
/** Cleanup; destroy all internal/system data & resources used by the SOCK API.
294
319
* ATTENTION: no function from the SOCK API should be called after this call!
295
* NOTE: you can safely call it more than once; just, all calls after the first
320
* @li <b>NOTE:</b> you can safely call it more than once; just, all calls after the first
296
321
* one will have no result.
297
322
*/
298
323
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_ShutdownAPI(void);
312
337
} FLSCE_Flags;
313
338
typedef unsigned int TLSCE_Flags;
314
339
315
/* [SERVER-side] Create and initialize the server-side(listening) socket
340
/** [SERVER-side] Create and initialize the server-side(listening) socket
316
341
* (socket() + bind() + listen())
317
* NOTE: on some systems, "backlog" can be silently limited down to 128 (or 5).
342
* @li <b>NOTE:</b> on some systems, "backlog" can be silently limited down to 128 (or 5).
343
* @param port
344
* [in] the port to listen at
345
* @param backlog
346
* [in] maximal # of pending connections
347
* @param lsock
348
* [out] handle of the created listening socket
349
* @param flags
350
* [in] special modifiers
318
351
*/
319
352
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_CreateEx
320
(unsigned short port, /* [in] the port to listen at */
321
unsigned short backlog, /* [in] maximal # of pending connections */
322
LSOCK* lsock, /* [out] handle of the created listening socket */
323
TLSCE_Flags flags /* [in] special modifiers */
353
(unsigned short port,
354
unsigned short backlog,
355
LSOCK* lsock,
356
TLSCE_Flags flags
324
357
);
325
358
359
/**
360
* @param port
361
* [in] the port to listen at
362
* @param backlog
363
* [in] maximal # of pending connections
364
* @param lsock
365
* [out] handle of the created listening socket
366
*/
326
367
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_Create
327
(unsigned short port, /* [in] the port to listen at */
328
unsigned short backlog, /* [in] maximal # of pending connections */
329
LSOCK* lsock /* [out] handle of the created listening socket */
368
(unsigned short port,
369
unsigned short backlog,
370
LSOCK* lsock
330
371
);
331
372
332
373
333
/* [SERVER-side] Accept connection from a client.
334
* NOTE: the "*timeout" is for this accept() only. To set I/O timeout,
374
/** [SERVER-side] Accept connection from a client.
375
* @li <b>NOTE:</b> the "*timeout" is for this accept() only. To set I/O timeout,
335
376
* use SOCK_SetTimeout(); all I/O timeouts are infinite by default.
377
* @param lsock
378
* [in] handle of a listening socket
379
* @param timeout
380
* [in] timeout (infinite if NULL)
381
* @param sock
382
* [out] handle of the created socket
336
383
*/
337
384
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_Accept
338
(LSOCK lsock, /* [in] handle of a listening socket */
339
const STimeout* timeout, /* [in] timeout (infinite if NULL) */
340
SOCK* sock /* [out] handle of the created socket */
385
(LSOCK lsock,
386
const STimeout* timeout,
387
SOCK* sock
341
388
);
342
389
343
390
344
/* [SERVER-side] Close the listening socket, destroy relevant internal data.
391
/** [SERVER-side] Close the listening socket, destroy relevant internal data.
392
* @param lsock
393
*
345
394
*/
346
395
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_Close(LSOCK lsock);
347
396
348
397
349
398
/* Get an OS-dependent native socket handle to use by platform-specific API.
350
399
* FYI: on MS-Windows it will be "SOCKET", on other platforms -- "int".
400
* @param lsock
401
* [in] socket handle
402
* @param handle_buf
403
* Pointer to a memory area to put the socket's native OS handle at
404
* @param handle_size
405
* The exact(!) size of the expected OS handle
351
406
*/
352
407
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_GetOSHandle
353
408
(LSOCK lsock,
354
void* handle_buf, /* pointer to a memory area to put the OS handle at */
355
size_t handle_size /* the exact(!) size of the expected OS handle */
409
void* handle_buf,
410
size_t
356
411
);
357
412
358
413
362
417
*/
363
418
364
419
365
/* [CLIENT-side] Connect client to another(server-side, listening) socket
420
/** [CLIENT-side] Connect client to another(server-side, listening) socket
366
421
* (socket() + connect() [+ select()])
422
* Equivalent to SOCK_CreateEx(host, port, timeout, sock, 0, 0, eDefault).
423
*
424
* @param host
425
* [in] host to connect to
426
* @param port
427
* [in] port to connect to
428
* @param timeout
429
* [in] the connect timeout (infinite if NULL)
430
* @param sock
431
* [out] handle of the created socket
432
* @sa SOCK_CreateEx()
367
433
*/
368
/* SOCK_CreateEx(host, port, timeout, sock, 0, 0, eDefault) */
369
434
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Create
370
(const char* host, /* [in] host to connect to */
371
unsigned short port, /* [in] port to connect to */
372
const STimeout* timeout, /* [in] the connect timeout (infinite if NULL) */
373
SOCK* sock /* [out] handle of the created socket */
435
(const char* host,
436
unsigned short port,
437
const STimeout* timeout,
438
SOCK* sock
374
439
);
375
440
441
442
/** [CLIENT-side] Connect client to another(server-side, listening) socket
443
* (socket() + connect() [+ select()])
444
*
445
* @param host
446
* [in] Host to connect to
447
* @param port
448
* [in] port to connect to
449
* @param timeout
450
* [in] the connect timeout (infinite if NULL)
451
* @param sock
452
* [out] handle of the created socket
453
* @param init_data
454
* [in] initial output data segment (may be NULL)
455
* @param init_size
456
* [in] size of initial data segment (may be 0)
457
* @param log
458
* [in] whether to do logging on this socket
459
* @sa SOCK_Create()
460
*/
376
461
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateEx
377
(const char* host, /* [in] host to connect to */
378
unsigned short port, /* [in] port to connect to */
379
const STimeout* timeout, /* [in] the connect timeout (infinite if NULL) */
380
SOCK* sock, /* [out] handle of the created socket */
381
const void* init_data,/* [in] initial output data segment (may be NULL)*/
382
size_t init_size,/* [in] size of initial data segment (may be 0) */
383
ESwitch log /* [in] whether to do logging on this socket */
384
);
385
386
387
/* [SERVER-side] Create a socket on top of OS-dependent "handle"
388
* (file descriptor on Unix). Returned socket is not reopenable to its
389
* default peer (SOCK_Reconnect may not specify zeros for the connection
390
* point). All timeouts are set to its default [infinite] values.
462
(const char* host,
463
unsigned short port,
464
const STimeout* timeout,
465
SOCK* sock,
466
const void* init_data,
467
size_t init_size,
468
ESwitch log
469
);
470
471
/**
472
* @sa SOCK_CreateOnTopEx()
473
*/
474
typedef enum {
475
eSCOT_KeepOnClose, /** Do not close "handle" on SOCK_Close() */
476
eSCOT_CloseOnClose /** Do close "handle" on SOCK_Close() */
477
} ESCOT_OnClose;
478
479
480
/** [SERVER-side] Create a socket on top of OS-dependent "handle".
481
*
482
* Equivalent of SOCK_CreateOnTopEx(handle, handle_size, sock,
483
* 0, 0, eDefault, eSCOT_CloseOnClose).
484
* @param handle
485
* [in] OS-dependent "handle" to be converted
486
* @param handle_size
487
* [in] "handle" size
488
* @param sock
489
* [out] SOCK built on top of OS "handle"
490
* @sa SOCK_CreateOnTopEx()
491
*/
492
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTop
493
(const void* handle,
494
size_t handle_size,
495
SOCK* sock
496
);
497
498
499
/** [SERVER-side] Create a socket on top of OS-dependent "handle"
500
* (file descriptor on Unix, SOCKET on MS-Windows). Returned socket
501
* is not reopenable to its default peer (SOCK_Reconnect may not specify
502
* zeros for the connection point).
503
* All timeouts are set to default [infinite] values.
391
504
* SOCK_Close() will close the "handle" only if the "close_on_close"
392
505
* parameter is passed non-zero (eSCOT_CloseOnClose).
393
* Return eIO_Success on success; otherwise: eIO_Closed if the "handle" does
394
* not refer to an open socket [but e.g. to a normal file or a pipe];
395
* other error codes in case of other errors.
506
* @param handle
507
* [in] OS-dependent "handle" to be converted
508
* @param handle_size
509
* [in] "handle" size
510
* @param sock
511
* [out] SOCK built on top of OS "handle"
512
* @param init_data
513
* [in] initial output data segment (ok NULL)
514
* @param init_size
515
* [in] size of initial data segment (ok 0)
516
* @param log
517
* [in] data logging for the resulting SOCK
518
* @param on_close
519
* [in] if to keep "handle" in SOCK_Close()
520
* @return
521
* Return eIO_Success on success; otherwise: eIO_Closed if the "handle" does
522
* not refer to an open socket [but e.g. to a normal file or a pipe];
523
* other error codes in case of other errors.
524
* @sa SOCK_CreateOnTop()
396
525
*/
397
typedef enum {
398
eSCOT_KeepOnClose, /* Do not close "handle" on SOCK_Close() */
399
eSCOT_CloseOnClose /* Do close "handle" on SOCK_Close() */
400
} ESCOT_OnClose;
401
402
/* SOCK_CreateOnTopEx(handle, handle_size, sock,
403
0, 0, eDefault, eSCOT_CloseOnClose) */
404
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTop
405
(const void* handle, /* [in] OS-dependent "handle" to be converted */
406
size_t handle_size, /* [in] "handle" size */
407
SOCK* sock /* [out] SOCK built on top of OS "handle" */
408
);
409
410
526
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTopEx
411
(const void* handle, /* [in] OS-dependent "handle" to be converted */
412
size_t handle_size, /* [in] "handle" size */
413
SOCK* sock, /* [out] SOCK built on top of OS "handle" */
414
const void* init_data, /* [in] initial output data segment (ok NULL) */
415
size_t init_size, /* [in] size of initial data segment (ok 0) */
416
ESwitch log, /* [in] data logging for the resulting SOCK */
417
ESCOT_OnClose on_close /* [in] if to keep "handle" in SOCK_Close() */
527
(const void* handle,
528
size_t handle_size,
529
SOCK* sock,
530
const void* init_data,
531
size_t init_size,
532
ESwitch log,
533
ESCOT_OnClose on_close
418
534
);
419
535
420
536
421
/* [CLIENT-side] Close the socket referred to by "sock" and then connect
537
/** [CLIENT-side] Close the socket referred to by "sock" and then connect
422
538
* it to another "host:port"; fail if it takes more than "timeout"
423
539
* (close() + connect() [+ select()])
424
540
*
425
541
* HINT: if "host" is NULL then connect to the same host address as before;
426
542
* if "port" is zero then connect to the same port # as before.
427
543
*
428
* NOTE1: "new" socket inherits the old I/O timeouts.
429
* NOTE2: the call is applicable to stream [not datagram] sockets only.
430
* NOTE3: "timeout"==NULL is infinite; "timeout"=={0,0} causes no wait for
544
* @li <b>NOTE 1:</b> "new" socket inherits the old I/O timeouts.
545
* @li <b>NOTE 2:</b> the call is applicable to stream [not datagram] sockets only.
546
* @li <b>NOTE 3:</b> "timeout"==NULL is infinite; "timeout"=={0,0} causes no wait for
431
547
* connection to be established and to return immediately.
432
* NOTE4: UNIX sockets can only be reconnected to the same file thus both
548
* @li <b>NOTE 4:</b> UNIX sockets can only be reconnected to the same file thus both
433
549
* host and port have to be passed as 0s.
550
* @param sock
551
* [in] handle of the socket to reconnect
552
* @param host
553
* [in] host to connect to (can be NULL)
554
* @param port
555
* [in] port to connect to (can be 0)
556
* @param timeout
557
* [in] the connect timeout (infinite if NULL)
434
558
*/
435
559
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Reconnect
436
(SOCK sock, /* [in] handle of the socket to reconnect */
437
const char* host, /* [in] host to connect to (can be NULL) */
438
unsigned short port, /* [in] port to connect to (can be 0) */
439
const STimeout* timeout /* [in] the connect timeout (infinite if NULL) */
560
(SOCK sock,
561
const char* host,
562
unsigned short port,
563
const STimeout* timeout
440
564
);
441
565
442
566
443
/* Shutdown the connection in only one direction (specified by "direction").
567
/** Shutdown the connection in only one direction (specified by "direction").
444
568
* Later attempts to I/O (or to wait) in the shutdown direction will
445
569
* do nothing, and immediately return with "eIO_Closed" status.
446
570
* Pending data output can cause data transfer to the remote end (subject
447
571
* for eIO_Close timeout as previously set by SOCK_SetTimeout()).
448
572
* Cannot be applied to datagram sockets (eIO_InvalidArg results).
573
* @param sock
574
* [in] handle of the socket to shutdown
575
* @param how
576
* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite
449
577
*/
450
578
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Shutdown
451
(SOCK sock, /* [in] handle of the socket to shutdown */
452
EIO_Event how /* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
579
(SOCK sock,
580
EIO_Event how
453
581
);
454
582
455
583
456
/* Close the connection, destroy relevant internal data.
584
/** Close the connection, destroy relevant internal data.
457
585
* The "sock" handle goes invalid after this function call, regardless
458
586
* of whether the call was successful or not.
459
* NOTE1: if eIO_Close timeout was specified (or NULL) then it blocks until
587
* @li <b>NOTE 1:</b> if eIO_Close timeout was specified (or NULL) then it blocks until
460
588
* either all unsent data are sent, error flagged, or the timeout
461
589
* expires.
462
* NOTE2: if there is output pending, that output will be flushed.
590
* @li <b>NOTE 2:</b> if there is output pending, that output will be flushed.
591
* @param sock
592
* [in] Socket
463
593
*/
464
594
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Close(SOCK sock);
465
595
466
596
467
/* Close the connection, and conditionally destroy relevant internal data.
468
* NOTE1: if eIO_Close timeout was specified (or NULL) then it blocks until
597
/** Close the connection, and conditionally destroy relevant internal data.
598
* @li <b>NOTE 1:</b> if eIO_Close timeout was specified (or NULL) then it blocks until
469
599
* either all unsent data are sent, error flagged, or the timeout
470
600
* expires.
471
* NOTE2: if there is output pending, that output will be flushed.
472
* NOTE3: SOCK_CloseEx(sock, 1) is equivalent to SOCK_Close(sock);
601
* @li <b>NOTE 2:</b> if there is output pending, that output will be flushed.
602
* @li <b>NOTE 3:</b> SOCK_CloseEx(sock, 1) is equivalent to SOCK_Close(sock);
603
* @param sock
604
* [in] handle of the socket to close
605
* @param destroy
606
* [in] =1 to destroy handle; =0 to keep handle
473
607
*/
474
608
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CloseEx
475
(SOCK sock, /* [in] handle of the socket to close */
476
int/*bool*/ destroy /* [in] =1 to destroy handle; =0 to keep handle */
609
(SOCK sock,
610
int/**bool*/ destroy
477
611
);
478
612
479
613
480
/* Block on the socket until either read/write (dep. on the "event" arg) is
614
/** Block on the socket until either read/write (dep. on the "event" arg) is
481
615
* available or timeout expires (if "timeout" is NULL then assume it infinite).
482
616
* For a datagram socket, eIO_Closed is returned if the internally latched
483
617
* message was entirely read out, and eIO_Read was requested as the "event".
484
618
* Both eIO_Write and eIO_ReadWrite events always immediately succeed for
485
619
* the datagram socket.
620
* @param sock
621
* [in] socket handle
622
* @param event
623
* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite
624
* @param timeout
625
* [in] Maximum time to wait for an event
486
626
*/
487
627
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Wait
488
628
(SOCK sock,
489
EIO_Event event, /* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
629
EIO_Event event,
490
630
const STimeout* timeout
491
631
);
492
632
493
633
494
/* Block until at least one of the sockets enlisted in "polls" array
634
/**
635
* @sa SOCK_Poll()
636
*/
637
typedef struct {
638
SOCK sock; /** [in] SOCK to poll (NULL if not to poll) */
639
EIO_Event event; /** [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
640
EIO_Event revent; /** [out] one of: eIO_Open/Read/Write/ReadWrite/Close */
641
} SSOCK_Poll;
642
643
644
/** Block until at least one of the sockets enlisted in "polls" array
495
645
* (of size "n") becomes available for requested operation (event),
496
646
* or until timeout expires (wait indefinitely if timeout is passed NULL).
497
647
* Return eIO_Success if at least one socket was found ready; eIO_Timeout
498
648
* if timeout expired; eIO_Unknown if underlying system call(s) failed.
499
* NOTE1: For a socket found not ready for an operation, eIO_Open is returned
649
* @li <b>NOTE 1:</b> For a socket found not ready for an operation, eIO_Open is returned
500
650
* in its "revent"; for a failing socket, eIO_Close is returned;
501
* NOTE2: This call may return eIO_InvalidArg if
651
* @li <b>NOTE 2:</b> This call may return eIO_InvalidArg if
502
652
* - parameters to the call are inconsistent;
503
653
* - a non-NULL socket polled with a bad "event" (eIO_Open, eIO_Close).
504
654
* With this return code, the calling program cannot rely on "revent"
505
655
* fields the "polls" array as they might not be properly updated.
506
* NOTE3: If either both "n" and "polls" are NULL, or all sockets in "polls"
656
* @li <b>NOTE 3:</b> If either both "n" and "polls" are NULL, or all sockets in "polls"
507
657
* are NULL, then the returned result is either
508
658
* eIO_Timeout (after the specified amount of time was spent idle), or
509
659
* eIO_Interrupted (if signal came while the waiting was in progress).
510
* NOTE4: For datagram sockets, the readiness for reading is determined by
660
* @li <b>NOTE 4:</b> For datagram sockets, the readiness for reading is determined by
511
661
* message data latched since last message receive call (DSOCK_RecvMsg).
512
* NOTE5: This call allows intermixture of stream and datagram sockets.
513
* NOTE6: This call can cause some socket I/O in those sockets marked for
662
* @li <b>NOTE 5:</b> This call allows intermixture of stream and datagram sockets.
663
* @li <b>NOTE 6:</b> This call can cause some socket I/O in those sockets marked for
514
664
* read-on-write and those with pending connection or output data.
665
* @param n
666
* [in] # of SSOCK_Poll elems in "polls"
667
* @param polls[]
668
* [in|out] array of query/result structures
669
* @param timeout
670
* [in] max time to wait (infinite if NULL)
671
* @param n_ready
672
* [out] # of ready sockets (may be NULL)
515
673
*/
516
517
typedef struct {
518
SOCK sock; /* [in] SOCK to poll (NULL if not to poll) */
519
EIO_Event event; /* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
520
EIO_Event revent; /* [out] one of: eIO_Open/Read/Write/ReadWrite/Close */
521
} SSOCK_Poll;
522
523
674
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Poll
524
(size_t n, /* [in] # of SSOCK_Poll elems in "polls" */
525
SSOCK_Poll polls[], /* [in|out] array of query/result structures */
526
const STimeout* timeout, /* [in] max time to wait (infinite if NULL) */
527
size_t* n_ready /* [out] # of ready sockets (may be NULL) */
675
(size_t n,
676
SSOCK_Poll polls[],
677
const STimeout* timeout,
678
size_t* n_ready
528
679
);
529
680
530
681
531
682
532
/* GENERIC POLLABLE INTERFACE, please see above for explanations
683
/** GENERIC POLLABLE INTERFACE, please see above for explanations
533
684
*/
534
685
struct SPOLLABLE_tag;
535
686
typedef struct SPOLLABLE_tag* POLLABLE;
540
691
EIO_Event revent;
541
692
} SPOLLABLE_Poll;
542
693
694
/**
695
* @param n
696
*
697
* @param polls[]
698
*
699
* @param timeout
700
*
701
* @param n_ready
702
*
703
*/
543
704
extern NCBI_XCONNECT_EXPORT EIO_Status POLLABLE_Poll
544
705
(size_t n,
545
706
SPOLLABLE_Poll polls[],
548
709
);
549
710
550
711
551
/* Return 0 if conversion cannot be made; otherwise converted handle */
712
/**
713
* @return
714
* Return 0 if conversion cannot be made; otherwise converted handle
715
*/
552
716
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromSOCK (SOCK);
553
717
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromLSOCK(LSOCK);
554
718
extern NCBI_XCONNECT_EXPORT SOCK POLLABLE_ToSOCK (POLLABLE);
555
719
extern NCBI_XCONNECT_EXPORT LSOCK POLLABLE_ToLSOCK (POLLABLE);
556
720
557
721
558
/* Specify timeout for the connection i/o (see SOCK_[Read|Write|Close] funcs).
722
/** Specify timeout for the connection i/o (see SOCK_[Read|Write|Close] funcs).
559
723
* If "timeout" is NULL then set the timeout to be infinite;
560
* NOTE: the default timeout is infinite (wait "ad infinitum" on I/O).
724
* @li <b>NOTE:</b> the default timeout is infinite (wait "ad infinitum" on I/O).
725
* @param sock
726
* [in] socket handle
727
* @param event
728
* [in] one of: eIO_[Read/Write/ReadWrite/Close]
729
* @param timeout
730
* [in] new timeout value to set
561
731
*/
562
732
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_SetTimeout
563
733
(SOCK sock,
564
EIO_Event event, /* [in] one of: eIO_[Read/Write/ReadWrite/Close] */
565
const STimeout* timeout /* [in] new timeout value to set */
734
EIO_Event event,
735
const STimeout* timeout
566
736
);
567
737
568
738
569
/* Get the connection's i/o timeout (or NULL, if the timeout is infinite).
570
* NOTE1: the returned timeout is guaranteed to be pointing to a valid
739
/** Get the connection's i/o timeout (or NULL, if the timeout is infinite).
740
* @li <b>NOTE 1:</b> the returned timeout is guaranteed to be pointing to a valid
571
741
* (and correct) structure in memory at least until the SOCK is closed
572
742
* or SOCK_SetTimeout is called for this "sock".
573
* NOTE2: eIO_ReadWrite timeout is the least of eIO_Read and eIO_Write ones.
743
* @li <b>NOTE 2:</b> eIO_ReadWrite timeout is the least of eIO_Read and eIO_Write ones.
744
* @param sock
745
* [in] socket handle
746
* @param event
747
* [in] one of: eIO_[Read/Write/Close]
574
748
*/
575
749
extern NCBI_XCONNECT_EXPORT const STimeout* SOCK_GetTimeout
576
750
(SOCK sock,
577
EIO_Event event /* [in] one of: eIO_[Read/Write/Close] */
751
EIO_Event event
578
752
);
579
753
580
754
581
/* Read/peek up to "size" bytes from "sock" to the mem.buffer pointed by "buf".
755
/** Read/peek up to "size" bytes from "sock" to the mem.buffer pointed by "buf".
582
756
* In "*n_read", return the number of successfully read bytes.
583
757
* Read method "how" can be either of the following:
584
758
* eIO_ReadPlain -- read as many as "size" bytes and return (eIO_Success);
611
785
* eIO_Read[Persist] -- discard up to "size" bytes from internal buffer
612
786
* and socket (check "*n_read" to know how many).
613
787
*
614
* NOTE1: "Read" and "peek" methods differ: if "read" is performed and not
788
* @li <b>NOTE 1:</b> "Read" and "peek" methods differ: if "read" is performed and not
615
789
* enough but some data available immediately from the internal buffer,
616
790
* then the call completes with eIO_Success status. For "peek", if
617
791
* not all requested data were available, the real I/O occurs to pick up
618
792
* additional data (if any) from the system. Keep this difference in
619
793
* mind when programming loops that heavily use "peek"s without "read"s.
620
* NOTE2: If on input "size" == 0, then "*n_read" is set to 0, and the
794
* @li <b>NOTE 2:</b> If on input "size" == 0, then "*n_read" is set to 0, and the
621
795
* return value can be either of eIO_Success, eIO_Closed or
622
796
* eIO_Unknown depending on connection status of the socket.
797
* @param sock
798
* [in] socket handle
799
* @param buf
800
* [out] data buffer to read to
801
* @param size
802
* [in] max # of bytes to read to "buf"
803
* @param n_read
804
* [out] # of bytes read (can be NULL)
805
* @param how
806
* [in] how to read the data
623
807
*/
624
808
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Read
625
809
(SOCK sock,
626
void* buf, /* [out] data buffer to read to */
627
size_t size, /* [in] max # of bytes to read to "buf" */
628
size_t* n_read, /* [out] # of bytes read (can be NULL) */
629
EIO_ReadMethod how /* [in] how to read the data */
810
void* buf,
811
size_t size,
812
size_t* n_read,
813
EIO_ReadMethod how
630
814
);
631
815
632
816
633
/*
817
/**
634
818
* Read a line from SOCK. A line is terminated by either '\n' (with
635
819
* optional preceding '\r') or '\0'. Returned result is always '\0'-
636
820
* terminated and having '\r'(if any)'\n' stripped. *n_read (if 'n_read'
640
824
* line, all 'size' bytes will be filled, with *n_read == size upon
641
825
* return. Note that there will be no terminating '\0' in this
642
826
* (and the only) case, which the caller can easily distinguish.
643
* Return code eIO_Success upon successful completion, other - upon
644
* an error. Note that *n_read must be analyzed prior to return code,
645
* because the buffer could have received some contents before
646
* the indicated error occurred (especially when connection closed).
827
* @param sock
828
* [in] socket handle
829
* @param buf
830
* [out] data buffer to read to
831
* @param size
832
* [in] max # of bytes to read to "buf"
833
* @param n_read
834
* [out] # of bytes read (can be NULL)
835
* @return
836
* Return code eIO_Success upon successful completion, other - upon
837
* an error. Note that *n_read must be analyzed prior to return code,
838
* because the buffer could have received some contents before
839
* the indicated error occurred (especially when connection closed).
647
840
*/
648
841
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_ReadLine
649
842
(SOCK sock,
650
char* buf, /* [out] data buffer to read to */
651
size_t size, /* [in] max # of bytes to read to "buf" */
652
size_t* n_read /* [out] # of bytes read (can be NULL) */
843
char* buf,
844
size_t size,
845
size_t* n_read
653
846
);
654
847
655
848
656
/* Push the specified data back to the socket input queue (in the socket's
849
/** Push the specified data back to the socket input queue (in the socket's
657
850
* internal read buffer). These can be any data, not necessarily the data
658
851
* previously read from the socket.
852
* @param sock
853
* [in] socket handle
854
* @param buf
855
* [in] data to push back to the socket's local buffer
856
* @param size
857
* [in] # of bytes (starting at "buf") to push back
659
858
*/
660
859
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_PushBack
661
860
(SOCK sock,
662
const void* buf, /* [in] data to push back to the socket's local buffer */
663
size_t size /* [in] # of bytes (starting at "buf") to push back */
861
const void* buf,
862
size_t size
664
863
);
665
864
666
865
667
/* Return (for the specified "direction" [eIO_Open to check for closed sock]):
866
/**
867
* @param sock
868
* [in] socket handle
869
* @param direction
870
* [in] one of: eIO_Open, eIO_Read, eIO_Write
871
* @return
872
* Return (for the specified "direction" [eIO_Open to check for closed sock]):
668
873
* eIO_Closed -- if the connection was shutdown by SOCK_Shutdown(), or
669
874
* (for "eIO_Read" only) if EOF was detected
670
875
* if "direction"==eIO_Open, this code means socket closed
673
878
* eIO_Timeout -- if the socket is not yet actually connected
674
879
* eIO_Success -- otherwise (incl. eIO_Timeout on last I/O)
675
880
*
676
* NOTE: The SOCK_Read() and SOCK_Wait(eIO_Read) will not return any error
881
* @li <b>NOTE:</b> The SOCK_Read() and SOCK_Wait(eIO_Read) will not return any error
677
882
* as long as there is any unread (buffered) data left.
678
883
* Thus, when you are "peeking" data instead of actually reading it,
679
884
* then this is the only "non-destructive" way to check whether EOF
681
886
*/
682
887
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Status
683
888
(SOCK sock,
684
EIO_Event direction /* [in] one of: eIO_Open, eIO_Read, eIO_Write */
889
EIO_Event direction
685
890
);
686
891
687
892
688
/* Write "size" bytes from buffer "buf" to "sock".
689
* In "*n_written", return the number of bytes actually written.
690
* eIO_WritePlain -- write as many bytes as possible at once and return
893
/** Write "size" bytes from buffer "buf" to "sock".
894
* @param sock
895
* [in] socket handle
896
* @param buf
897
* [in] data to write to the socket
898
* @param size
899
* [in] # of bytes (starting at "buf") to write
900
* @param n_written
901
* [out] # of written bytes (can be NULL)
902
* @param how
903
* [in] eIO_WritePlain | eIO_WritePersist
904
* @return
905
* In "*n_written", return the number of bytes actually written.
906
* eIO_WritePlain -- write as many bytes as possible at once and return
691
907
* immediately; if no bytes can be written then wait
692
908
* at most WRITE timeout, try again and return.
693
* eIO_WritePersist -- write all data (doing an internal retry loop
909
* eIO_WritePersist -- write all data (doing an internal retry loop
694
910
* if necessary); if any single write attempt times out
695
911
* or fails then stop writing and return (error code).
696
* Return status: eIO_Success -- some bytes were written successfully [Plain]
912
* Return status: eIO_Success -- some bytes were written successfully [Plain]
697
913
* -- all bytes were written successfully [Persist]
698
914
* other code denotes an error, but some bytes might have
699
915
* been sent nevertheless (always check *n_written to know).
700
916
*
701
* NOTE1: With eIO_WritePlain the call returns eIO_Success iff some data
917
* @li <b>NOTE 1:</b> With eIO_WritePlain the call returns eIO_Success iff some data
702
918
* were actually written to the socket. If no data could be written
703
919
* (and perhaps timeout expired) this call always returns an error.
704
* NOTE2: eIO_WritePlain and eIO_WritePersist differs that the latter can
920
* @li <b>NOTE 2:</b> eIO_WritePlain and eIO_WritePersist differs that the latter can
705
921
* flag an error condition even if some data were actually written
706
922
* (see "the rule of thumb" in the comments for SOCK_Read() above).
707
* NOTE3: if "size"==0, return value can be eIO_Success if no pending data
923
* @li <b>NOTE 3:</b> if "size"==0, return value can be eIO_Success if no pending data
708
924
* left in the socket, or eIO_Timeout if there are still data pending.
709
925
* In either case, "*n_written" is set to 0 on return.
710
926
*/
711
927
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Write
712
928
(SOCK sock,
713
const void* buf, /* [in] data to write to the socket */
714
size_t size, /* [in] # of bytes (starting at "buf") to write */
715
size_t* n_written, /* [out] # of written bytes (can be NULL) */
716
EIO_WriteMethod how /* [in] eIO_WritePlain | eIO_WritePersist */
929
const void* buf,
930
size_t size,
931
size_t* n_written,
932
EIO_WriteMethod how
717
933
);
718
934
719
935
720
/* If there is outstanding connection or output data pending, cancel it.
936
/** If there is outstanding connection or output data pending, cancel it.
721
937
* Mark the socket as if it has been shut down for both reading and writing.
722
938
* Break actual connection if any was established.
723
939
* Do not attempt to send anything upon SOCK_Close().
724
940
* This call is available for stream sockets only.
941
* @param sock
942
* Socket handle
725
943
*/
726
944
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Abort
727
945
(SOCK sock
728
946
);
729
947
730
948
731
/* Get host and port of the socket's peer.
732
* If "network_byte_order" is true(non-zero) then return the host/port in the
733
* network byte order; otherwise return them in the local host byte order.
949
/** Get host and port of the socket's peer.
950
* @param sock
951
* [in] socket handle
952
* @param host
953
* [out] the peer's host (can be NULL)
954
* @param port
955
* [out] the peer's port (can be NULL)
956
* @param byte_order
957
* [in] host/port byte order
958
* @return
959
* If "network_byte_order" is true(non-zero) then return the host/port in the
960
* network byte order; otherwise return them in the local host byte order.
734
961
*/
735
962
extern NCBI_XCONNECT_EXPORT void SOCK_GetPeerAddress
736
963
(SOCK sock,
737
unsigned int* host, /* [out] the peer's host (can be NULL) */
738
unsigned short* port, /* [out] the peer's port (can be NULL) */
739
ENH_ByteOrder byte_order /* [in] host/port byte order */
964
unsigned int* host,
965
unsigned short* port,
966
ENH_ByteOrder byte_order
740
967
);
741
968
742
969
743
/* Get textual representation of the socket's peer.
970
/** Get textual representation of the socket's peer.
744
971
* For INET domain sockets, the result is of the form "aaa.bbb.ccc.ddd:ppppp";
745
972
* for UNIX domain socket, the result is the name of the socket's file.
746
* On success, return its "buf" argument; return 0 on error.
747
*/
973
* @param sock
974
* [in] socket handle
975
* @param buf
976
* [out] pointer to provided buffer to store the text to
977
* @param buflen
978
* [in] usable size of the buffer above
979
* @return
980
* On success, return its "buf" argument; return 0 on error.
981
*/
748
982
extern NCBI_XCONNECT_EXPORT char* SOCK_GetPeerAddressString
749
983
(SOCK sock,
750
char* buf, /* [out] pointer to provided buffer to store the text to */
751
size_t buflen /* [in] usable size of the buffer above */
984
char* buf,
985
size_t buflen
752
986
);
753
987
754
988
755
/* Get an OS-dependent native socket handle to use by platform-specific API.
989
/** Get an OS-dependent native socket handle to use by platform-specific API.
756
990
* FYI: on MS-Windows it will be "SOCKET", on other platforms -- "int".
991
* @param sock
992
* Socket handle
993
* @param handle_buf
994
* pointer to a memory area to put the OS handle at
995
* @param handle_size
996
* the exact(!) size of the expected OS handle
757
997
*/
758
998
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_GetOSHandle
759
999
(SOCK sock,
760
void* handle_buf, /* pointer to a memory area to put the OS handle at */
761
size_t handle_size /* the exact(!) size of the expected OS handle */
1000
void* handle_buf,
1001
size_t handle_size
762
1002
);
763
1003
764
1004
765
/* By default ("on_off" == eDefault,eOff), sockets will not try to read data
1005
/** By default ("on_off" == eDefault,eOff), sockets will not try to read data
766
1006
* from inside SOCK_Write(). If you want to automagically upread the data
767
1007
* (and cache it in the internal socket buffer) when the write operation
768
1008
* is not immediately available, call this func with "on_off" == eOn.
769
* Return prior setting.
770
*/
1009
* @param on_off
1010
*
1011
* @return
1012
* Prior setting.
1013
*/
771
1014
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWriteAPI
772
1015
(ESwitch on_off
773
1016
);
774
1017
775
1018
776
/* Control the reading-while-writing feature for socket "sock" individually.
1019
/** Control the reading-while-writing feature for socket "sock" individually.
777
1020
* To reset to the global default behavior (as set by
778
1021
* SOCK_SetReadOnWriteAPI), call this function with "on_off" == eDefault.
779
* Return prior setting.
1022
* @param sock
1023
* [in] socket handle
1024
* @param on_off
1025
*
1026
* @return
1027
* Prior setting.
780
1028
*/
781
1029
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWrite
782
1030
(SOCK sock,
784
1032
);
785
1033
786
1034
787
/* Control OS-defined send strategy by disabling/enabling TCP
1035
/** Control OS-defined send strategy by disabling/enabling TCP
788
1036
* Nagle algorithm that packs multiple requests into a single
789
1037
* frame and thus transferring data in fewer transactions,
790
1038
* miminizing the network traffic and bursting the throughput.
792
1040
* default behavior for the sake of their performance increase
793
1041
* (like in case of short transactions otherwise held by the system
794
1042
* to be possibly coalesced into larger chunks).
1043
* @param sock
1044
* [in] socket handle
1045
* @param on_off
1046
*
1047
* NB: use true to disable; false to enable
795
1048
*/
796
1049
extern NCBI_XCONNECT_EXPORT void SOCK_DisableOSSendDelay
797
(SOCK sock,
798
int/*bool*/ on_off /* NB: use true to disable; false to enable */
1050
(SOCK sock,
1051
int/**bool*/ on_off
799
1052
);
800
1053
801
1054
842
1095
* buffers correspondingly.
843
1096
*/
844
1097
845
1098
/**
1099
* @param sock
1100
* [out] socket created
1101
*/
846
1102
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Create
847
(SOCK* sock /* [out] socket created */
1103
(SOCK* sock
848
1104
);
849
1105
850
1106
/**
1107
* @param sock
1108
* [out] socket created
1109
* @param log
1110
* [in] whether to log data activity
1111
*/
851
1112
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_CreateEx
852
(SOCK* sock, /* [out] socket created */
853
ESwitch log /* [in] whether to log data activity*/
1113
(SOCK* sock,
1114
ESwitch log
854
1115
);
855
1116
856
1117
/**
1118
* @param sock
1119
* [in] SOCK from DSOCK_Create[Ex]()
1120
* @param port
1121
* [in] port to bind to (!=0)
1122
*/
857
1123
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Bind
858
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
859
unsigned short port /* [in] port to bind to (!=0) */
1124
(SOCK sock,
1125
unsigned short port
860
1126
);
861
1127
862
1128
/**
1129
* @param sock
1130
* [in] SOCK from DSOCK_Create[Ex]()
1131
* @param host
1132
* [in] peer host
1133
* @param port
1134
* [in] peer port
1135
*/
863
1136
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Connect
864
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
865
const char* host, /* [in] peer host */
866
unsigned short port /* [in] peer port */
1137
(SOCK sock,
1138
const char* host,
1139
unsigned short port
867
1140
);
868
1141
869
1142
/**
1143
* @param sock
1144
* [in] SOCK from DSOCK_Create[Ex]()
1145
* @param timeout
1146
* [in] time to wait for message
1147
*/
870
1148
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_WaitMsg
871
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
872
const STimeout* timeout /* [in] time to wait for message */
1149
(SOCK sock,
1150
const STimeout* timeout
873
1151
);
874
1152
875
1153
/**
1154
* @param sock
1155
* [in] SOCK from DSOCK_Create[Ex]()
1156
* @param host
1157
* [in] hostname or dotted IP
1158
* @param port
1159
* [in] port number, host byte order
1160
* @param data
1161
* [in] additional data to send
1162
* @param datalen
1163
* [in] size of additional data (bytes)
1164
*/
876
1165
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_SendMsg
877
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
878
const char* host, /* [in] hostname or dotted IP */
879
unsigned short port, /* [in] port number, host byte order*/
880
const void* data, /* [in] additional data to send */
881
size_t datalen /* [in] size of addtl data (bytes) */
1166
(SOCK sock,
1167
const char* host,
1168
unsigned short port,
1169
const void* data,
1170
size_t datalen
882
1171
);
883
1172
884
1173
/**
1174
* @param sock
1175
* [in] SOCK from DSOCK_Create[Ex]()
1176
* @param buf
1177
* [in] buf to store msg at,m.b.NULL
1178
* @param buflen
1179
* [in] buf length provided
1180
* @param maxmsglen
1181
* [in] maximal expected message len
1182
* @param msglen
1183
* [out] actual msg size, may be NULL
1184
* @param sender_addr
1185
* [out] net byte order, may be NULL
1186
* @param sender_port
1187
* [out] host byte order, may be NULL
1188
*/
885
1189
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_RecvMsg
886
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
887
void* buf, /* [in] buf to store msg at,m.b.NULL*/
888
size_t buflen, /* [in] buf length provided */
889
size_t maxmsglen, /* [in] maximal expected message len*/
890
size_t* msglen, /* [out] actual msg size, may be NULL*/
891
unsigned int* sender_addr, /* [out] net byte order, may be NULL */
892
unsigned short* sender_port /* [out] host byte order, may be NULL*/
1190
(SOCK sock,
1191
void* buf,
1192
size_t buflen,
1193
size_t maxmsglen,
1194
size_t* msglen,
1195
unsigned int* sender_addr,
1196
unsigned short* sender_port
893
1197
);
894
1198
895
1199
/**
1200
* @param sock
1201
* [in] SOCK from DSOCK_Create[Ex]()
1202
* @param direction
1203
* [in] either of eIO_Read|eIO_Write
1204
*/
896
1205
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_WipeMsg
897
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
898
EIO_Event direction /* [in] either of eIO_Read|eIO_Write*/
1206
(SOCK sock,
1207
EIO_Event direction
899
1208
);
900
1209
901
1210
/**
1211
* @param sock
1212
* [in] SOCK from DSOCK_Create[Ex]()
1213
* @param broadcast
1214
* [in] set(1)/unset(0) bcast capab
1215
*/
902
1216
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_SetBroadcast
903
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
904
int/*bool*/ broadcast /* [in] set(1)/unset(0) bcast capab.*/
1217
(SOCK sock,
1218
int/**bool*/ broadcast
905
1219
);
906
1220
907
1221
911
1225
*/
912
1226
913
1227
914
/* Return non-zero value if socket "sock" was created by DSOCK_Create[Ex]().
915
* Return zero otherwise.
916
*/
917
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsDatagram(SOCK sock);
918
919
920
/* Return non-zero value if socket "sock" was created by SOCK_Create[Ex]().
921
* Return zero otherwise.
922
*/
923
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsClientSide(SOCK sock);
924
925
926
/* Return non-zero value if socket "sock" was created by LSOCK_Accept().
927
* Return zero otherwise.
928
*/
929
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsServerSide(SOCK sock);
930
931
932
/* Return non-zero value if socket "sock" was created by LSOCK_Accept().
933
* Return zero otherwise.
934
*/
935
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsUNIX(SOCK sock);
1228
/**
1229
* @param sock
1230
* [in] socket handle
1231
* @return
1232
* Non-zero value if socket "sock" was created by DSOCK_Create[Ex]().
1233
* Return zero otherwise.
1234
*/
1235
extern NCBI_XCONNECT_EXPORT int/**bool*/ SOCK_IsDatagram(SOCK sock);
1236
1237
1238
/**
1239
* @param sock
1240
* [in] socket handle
1241
* @return
1242
* Non-zero value if socket "sock" was created by SOCK_Create[Ex]().
1243
* Return zero otherwise.
1244
*/
1245
extern NCBI_XCONNECT_EXPORT int/**bool*/ SOCK_IsClientSide(SOCK sock);
1246
1247
1248
/**
1249
* @param sock
1250
* [in] socket handle
1251
* @return
1252
* Non-zero value if socket "sock" was created by LSOCK_Accept().
1253
* Return zero otherwise.
1254
*/
1255
extern NCBI_XCONNECT_EXPORT int/**bool*/ SOCK_IsServerSide(SOCK sock);
1256
1257
1258
/**
1259
* @param sock
1260
* [in] socket handle
1261
* @return
1262
* Non-zero value if socket "sock" was created by LSOCK_Accept().
1263
* Return zero otherwise.
1264
*/
1265
extern NCBI_XCONNECT_EXPORT int/**bool*/ SOCK_IsUNIX(SOCK sock);
936
1266
937
1267
938
1268
941
1271
*/
942
1272
943
1273
944
/* Return zero on success, non-zero on error. See BSD gethostname().
945
* On error "name" returned emptied (name[0] == '\0').
1274
/**
1275
* @param name
1276
* [out] (guaranteed to be '\0'-terminated)
1277
* @param namelen
1278
* [in] max # of bytes allowed to put to "name"
1279
* @return
1280
* Zero on success, non-zero on error. See BSD gethostname().
1281
* On error "name" returned emptied (name[0] == '\0').
946
1282
*/
947
1283
extern NCBI_XCONNECT_EXPORT int SOCK_gethostname
948
(char* name, /* [out] (guaranteed to be '\0'-terminated) */
949
size_t namelen /* [in] max # of bytes allowed to put to "name" */
1284
(char* name,
1285
size_t namelen
950
1286
);
951
1287
952
1288
953
/* Return zero on success, non-zero on error. Vaguely related to BSD's
954
* inet_ntoa(). On error "buf" returned emptied (buf[0] == '\0').
1289
/**
1290
* @param addr
1291
* [in] must be in the network byte-order
1292
* @param buf
1293
* [out] to be filled by smth. like "123.45.67.89\0"
1294
* @param buflen
1295
* [in] max # of bytes to put to "buf"
1296
* @return
1297
* Zero on success, non-zero on error. Vaguely related to BSD's
1298
* inet_ntoa(). On error "buf" returned emptied (buf[0] == '\0').
955
1299
*/
956
1300
extern NCBI_XCONNECT_EXPORT int SOCK_ntoa
957
(unsigned int addr, /* [in] must be in the network byte-order */
958
char* buf, /* [out] to be filled by smth. like "123.45.67.89\0"*/
959
size_t buflen /* [in] max # of bytes to put to "buf" */
1301
(unsigned int addr,
1302
char* buf,
1303
size_t buflen
960
1304
);
961
1305
962
1306
963
/* See man for the BSDisms, htonl() and htons().
1307
/** See man for the BSDisms, htonl() and htons().
1308
* @param value
1309
*
964
1310
*/
965
1311
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_HostToNetLong
966
1312
(unsigned int value
968
1314
969
1315
#define SOCK_NetToHostLong SOCK_HostToNetLong
970
1316
1317
/**
1318
* @param value
1319
*
1320
*/
971
1321
extern NCBI_XCONNECT_EXPORT unsigned short SOCK_HostToNetShort
972
1322
(unsigned short value
973
1323
);
974
1324
975
1325
#define SOCK_NetToHostShort SOCK_HostToNetShort
976
1326
977
/* Deprecated */
978
#define SOCK_htonl SOCK_HostToNetLong
979
#define SOCK_ntohl SOCK_NetToHostLong
980
#define SOCK_htons SOCK_HostToNetShort
981
#define SOCK_ntohs SOCK_NetToHostShort
982
983
984
/* Return INET host address (in network byte order) of the
985
* specified host (or local host, if hostname is passed as NULL),
986
* which can be either domain name or an IP address in
987
* dotted notation (e.g. "123.45.67.89\0"). Return 0 on error.
988
* NOTE: "0.0.0.0" and "255.255.255.255" are considered invalid.
1327
1328
/* Deprecated: Use SOCK_{Host|Net}To{Net|Host}{Long|Short}() instead */
1329
#ifndef NCBI_DEPRECATED
1330
# define NCBI_SOCK_DEPRECATED
1331
#else
1332
# define NCBI_SOCK_DEPRECATED NCBI_DEPRECATED
1333
#endif
1334
extern NCBI_XCONNECT_EXPORT NCBI_SOCK_DEPRECATED
1335
unsigned int SOCK_htonl(unsigned int);
1336
#define SOCK_ntohl SOCK_htonl
1337
extern NCBI_XCONNECT_EXPORT NCBI_SOCK_DEPRECATED
1338
unsigned short SOCK_htons(unsigned short);
1339
#define SOCK_ntohs SOCK_htons
1340
1341
1342
/**
1343
* @param hostname
1344
* [in] return current host address if hostname is 0
1345
* @return
1346
* INET host address (in network byte order) of the
1347
* specified host (or local host, if hostname is passed as NULL),
1348
* which can be either domain name or an IP address in
1349
* dotted notation (e.g. "123.45.67.89\0"). Return 0 on error.
1350
* @li <b>NOTE:</b> "0.0.0.0" and "255.255.255.255" are considered invalid.
989
1351
*/
990
1352
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_gethostbyname
991
(const char* hostname /* [in] return current host address if hostname is 0 */
1353
(const char* hostname \
992
1354
);
993
1355
994
1356
995
/* Take INET host address (in network byte order) and fill out the
1357
/** Take INET host address (in network byte order) and fill out the
996
1358
* the provided buffer with the name, which the address corresponds to
997
* (in case of multiple names the primary name is used). Return value 0
998
* means error, while success is denoted by the 'name' argument returned.
999
* Note that on error the name returned emptied (name[0] == '\0').
1359
* (in case of multiple names the primary name is used).
1360
* @param addr
1361
* [in] host address in network byte order
1362
* @param name
1363
* [out] buffer to put the name to
1364
* @param namelen
1365
* [in] size (bytes) of the buffer above
1366
* @return
1367
* Value 0
1368
* means error, while success is denoted by the 'name' argument returned.
1369
* Note that on error the name returned emptied (name[0] == '\0').
1000
1370
*/
1001
1371
extern NCBI_XCONNECT_EXPORT char* SOCK_gethostbyaddr
1002
(unsigned int addr, /* [in] host address in network byte order */
1003
char* name, /* [out] buffer to put the name to */
1004
size_t namelen /* [in] size (bytes) of the buffer above */
1372
(unsigned int addr,
1373
char* name,
1374
size_t namelen
1005
1375
);
1006
1376
1007
1377
1008
/* Return loopback address (in network byte order).
1378
/**
1379
* @return
1380
* Loopback address (in network byte order).
1009
1381
*/
1010
1382
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_GetLoopbackAddress(void);
1011
1383
1012
1384
1385
/** Read (skipping leading blanks) "[host][:port]" from a string.
1386
* @param str
1387
* must not be NULL
1388
* @param host
1389
* must not be NULL
1390
* @param port
1391
* must not be NULL
1392
* @return
1393
* On success, return the advanced pointer past the host/port read.
1394
* If no host/port detected, return 'str'.
1395
* On format error, return 0.
1396
* If host and/or port fragments are missing,
1397
* then corresponding 'host'/'port' value returned as 0.
1398
* Note that 'host' returned is in network byte order,
1399
* unlike 'port', which always comes out in host (native) byte order.
1400
*/
1401
extern NCBI_XCONNECT_EXPORT const char* SOCK_StringToHostPort
1402
(const char* str,
1403
unsigned int* host,
1404
unsigned short* port
1405
);
1406
1407
1408
/** Print host:port into provided buffer string, not to exceed 'buflen' size.
1409
* Suppress printing host if parameter 'host' is zero.
1410
* @param host
1411
*
1412
* @param port
1413
*
1414
* @param buf
1415
*
1416
* @param buflen
1417
*
1418
* @return
1419
* Number of bytes printed.
1420
*/
1421
extern NCBI_XCONNECT_EXPORT size_t SOCK_HostPortToString
1422
(unsigned int host,
1423
unsigned short port,
1424
char* buf,
1425
size_t buflen
1426
);
1427
1428
1013
1429
#ifdef __cplusplus
1014
1430
} /* extern "C" */
1015
1431
#endif
1021
1437
/*
1022
1438
* ---------------------------------------------------------------------------
1023
1439
* $Log: ncbi_socket.h,v $
1440
* Revision 6.61 2006/03/16 19:12:21 ucko
1441
* Fix SOCK_CreateOnTopEx's prototype, which accidentally lost one
1442
* argument in the previous commit.
1443
*
1444
* Revision 6.60 2006/03/16 18:15:34 serovav
1445
* added markup for Doxygen
1446
*
1447
* Revision 6.58 2006/01/27 19:17:41 lavr
1448
* Fix NCBI_DEPRECATED placement to satify MSVC compiler
1449
*
1450
* Revision 6.57 2006/01/27 16:57:15 lavr
1451
* Added SOCK_StringHostToPort() and SOCK_HostPortToString() [from ncbi_connutil]
1452
*
1024
1453
* Revision 6.56 2005/07/19 19:54:56 lavr
1025
1454
* +SOCK_GetLoopbackAddress()
1026
1455
*
Loggerhead is a web-based interface for Breezy
Version: 2.0.1