309
338
typedef unsigned int TLSCE_Flags;
311
/* [SERVER-side] Create and initialize the server-side(listening) socket
340
/** [SERVER-side] Create and initialize the server-side(listening) socket
312
341
* (socket() + bind() + listen())
313
* 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).
344
* [in] the port to listen at
346
* [in] maximal # of pending connections
348
* [out] handle of the created listening socket
350
* [in] special modifiers
315
352
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_CreateEx
316
(unsigned short port, /* [in] the port to listen at */
317
unsigned short backlog, /* [in] maximal # of pending connections */
318
LSOCK* lsock, /* [out] handle of the created listening socket */
319
TLSCE_Flags flags /* [in] special modifiers */
353
(unsigned short port,
354
unsigned short backlog,
361
* [in] the port to listen at
363
* [in] maximal # of pending connections
365
* [out] handle of the created listening socket
322
367
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_Create
323
(unsigned short port, /* [in] the port to listen at */
324
unsigned short backlog, /* [in] maximal # of pending connections */
325
LSOCK* lsock /* [out] handle of the created listening socket */
368
(unsigned short port,
369
unsigned short backlog,
329
/* [SERVER-side] Accept connection from a client.
330
* 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,
331
376
* use SOCK_SetTimeout(); all I/O timeouts are infinite by default.
378
* [in] handle of a listening socket
380
* [in] timeout (infinite if NULL)
382
* [out] handle of the created socket
333
384
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_Accept
334
(LSOCK lsock, /* [in] handle of a listening socket */
335
const STimeout* timeout, /* [in] timeout (infinite if NULL) */
336
SOCK* sock /* [out] handle of the created socket */
386
const STimeout* timeout,
340
/* [SERVER-side] Close the listening socket, destroy relevant internal data.
391
/** [SERVER-side] Close the listening socket, destroy relevant internal data.
342
395
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_Close(LSOCK lsock);
345
398
/* Get an OS-dependent native socket handle to use by platform-specific API.
346
399
* FYI: on MS-Windows it will be "SOCKET", on other platforms -- "int".
403
* Pointer to a memory area to put the socket's native OS handle at
405
* The exact(!) size of the expected OS handle
348
407
extern NCBI_XCONNECT_EXPORT EIO_Status LSOCK_GetOSHandle
350
void* handle_buf, /* pointer to a memory area to put the OS handle at */
351
size_t handle_size /* the exact(!) size of the expected OS handle */
361
/* [CLIENT-side] Connect client to another(server-side, listening) socket
420
/** [CLIENT-side] Connect client to another(server-side, listening) socket
362
421
* (socket() + connect() [+ select()])
422
* Equivalent to SOCK_CreateEx(host, port, timeout, sock, 0, 0, eDefault).
425
* [in] host to connect to
427
* [in] port to connect to
429
* [in] the connect timeout (infinite if NULL)
431
* [out] handle of the created socket
432
* @sa SOCK_CreateEx()
364
/* SOCK_CreateEx(host, port, timeout, sock, 0, 0, eDefault) */
365
434
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Create
366
(const char* host, /* [in] host to connect to */
367
unsigned short port, /* [in] port to connect to */
368
const STimeout* timeout, /* [in] the connect timeout (infinite if NULL) */
369
SOCK* sock /* [out] handle of the created socket */
437
const STimeout* timeout,
442
/** [CLIENT-side] Connect client to another(server-side, listening) socket
443
* (socket() + connect() [+ select()])
446
* [in] Host to connect to
448
* [in] port to connect to
450
* [in] the connect timeout (infinite if NULL)
452
* [out] handle of the created socket
454
* [in] initial output data segment (may be NULL)
456
* [in] size of initial data segment (may be 0)
458
* [in] whether to do logging on this socket
372
461
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateEx
373
(const char* host, /* [in] host to connect to */
374
unsigned short port, /* [in] port to connect to */
375
const STimeout* timeout, /* [in] the connect timeout (infinite if NULL) */
376
SOCK* sock, /* [out] handle of the created socket */
377
const void* init_data,/* [in] initial output data segment (may be NULL)*/
378
size_t init_size,/* [in] size of initial data segment (may be 0) */
379
ESwitch log /* [in] whether to do logging on this socket */
383
/* [SERVER-side] Create a socket on top of OS-dependent "handle"
384
* (file descriptor on Unix). Returned socket is not reopenable to its
385
* default peer (SOCK_Reconnect may not specify zeros for the connection
386
* point). All timeouts are set to its default [infinite] values.
464
const STimeout* timeout,
466
const void* init_data,
472
* @sa SOCK_CreateOnTopEx()
475
eSCOT_KeepOnClose, /** Do not close "handle" on SOCK_Close() */
476
eSCOT_CloseOnClose /** Do close "handle" on SOCK_Close() */
480
/** [SERVER-side] Create a socket on top of OS-dependent "handle".
482
* Equivalent of SOCK_CreateOnTopEx(handle, handle_size, sock,
483
* 0, 0, eDefault, eSCOT_CloseOnClose).
485
* [in] OS-dependent "handle" to be converted
489
* [out] SOCK built on top of OS "handle"
490
* @sa SOCK_CreateOnTopEx()
492
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTop
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.
387
504
* SOCK_Close() will close the "handle" only if the "close_on_close"
388
505
* parameter is passed non-zero (eSCOT_CloseOnClose).
389
* Return eIO_Success on success; otherwise: eIO_Closed if the "handle" does
390
* not refer to an open socket [but e.g. to a normal file or a pipe];
391
* other error codes in case of other errors.
507
* [in] OS-dependent "handle" to be converted
511
* [out] SOCK built on top of OS "handle"
513
* [in] initial output data segment (ok NULL)
515
* [in] size of initial data segment (ok 0)
517
* [in] data logging for the resulting SOCK
519
* [in] if to keep "handle" in SOCK_Close()
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()
394
eSCOT_KeepOnClose, /* Do not close "handle" on SOCK_Close() */
395
eSCOT_CloseOnClose /* Do close "handle" on SOCK_Close() */
398
/* SOCK_CreateOnTopEx(handle, handle_size, sock,
399
0, 0, eDefault, eSCOT_CloseOnClose) */
400
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTop
401
(const void* handle, /* [in] OS-dependent "handle" to be converted */
402
size_t handle_size, /* [in] "handle" size */
403
SOCK* sock /* [out] SOCK built on top of OS "handle" */
406
526
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTopEx
407
(const void* handle, /* [in] OS-dependent "handle" to be converted */
408
size_t handle_size, /* [in] "handle" size */
409
SOCK* sock, /* [out] SOCK built on top of OS "handle" */
410
const void* init_data, /* [in] initial output data segment (ok NULL) */
411
size_t init_size, /* [in] size of initial data segment (ok 0) */
412
ESwitch log, /* [in] data logging for the resulting SOCK */
413
ESCOT_OnClose on_close /* [in] if to keep "handle" in SOCK_Close() */
530
const void* init_data,
533
ESCOT_OnClose on_close
417
/* [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
418
538
* it to another "host:port"; fail if it takes more than "timeout"
419
539
* (close() + connect() [+ select()])
421
541
* HINT: if "host" is NULL then connect to the same host address as before;
422
542
* if "port" is zero then connect to the same port # as before.
424
* NOTE1: "new" socket inherits the old I/O timeouts.
425
* NOTE2: the call is applicable to stream [not datagram] sockets only.
426
* 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
427
547
* connection to be established and to return immediately.
548
* @li <b>NOTE 4:</b> UNIX sockets can only be reconnected to the same file thus both
549
* host and port have to be passed as 0s.
551
* [in] handle of the socket to reconnect
553
* [in] host to connect to (can be NULL)
555
* [in] port to connect to (can be 0)
557
* [in] the connect timeout (infinite if NULL)
429
559
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Reconnect
430
(SOCK sock, /* [in] handle of the socket to reconnect */
431
const char* host, /* [in] host to connect to (can be NULL) */
432
unsigned short port, /* [in] port to connect to (can be 0) */
433
const STimeout* timeout /* [in] the connect timeout (infinite if NULL) */
563
const STimeout* timeout
437
/* Shutdown the connection in only one direction (specified by "direction").
567
/** Shutdown the connection in only one direction (specified by "direction").
438
568
* Later attempts to I/O (or to wait) in the shutdown direction will
439
569
* do nothing, and immediately return with "eIO_Closed" status.
440
570
* Pending data output can cause data transfer to the remote end (subject
441
571
* for eIO_Close timeout as previously set by SOCK_SetTimeout()).
442
572
* Cannot be applied to datagram sockets (eIO_InvalidArg results).
574
* [in] handle of the socket to shutdown
576
* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite
444
578
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Shutdown
445
(SOCK sock, /* [in] handle of the socket to shutdown */
446
EIO_Event how /* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
450
/* Close the connection, destroy relevant internal data.
584
/** Close the connection, destroy relevant internal data.
451
585
* The "sock" handle goes invalid after this function call, regardless
452
586
* of whether the call was successful or not.
453
* 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
454
588
* either all unsent data are sent, error flagged, or the timeout
456
* 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.
458
594
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Close(SOCK sock);
461
/* Close the connection, and conditionally destroy relevant internal data.
462
* 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
463
599
* either all unsent data are sent, error flagged, or the timeout
465
* NOTE2: if there is output pending, that output will be flushed.
466
* 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);
604
* [in] handle of the socket to close
606
* [in] =1 to destroy handle; =0 to keep handle
468
608
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CloseEx
469
(SOCK sock, /* [in] handle of the socket to close */
470
int/*bool*/ destroy /* [in] =1 to destroy handle; =0 to keep handle */
474
/* 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
475
615
* available or timeout expires (if "timeout" is NULL then assume it infinite).
476
616
* For a datagram socket, eIO_Closed is returned if the internally latched
477
617
* message was entirely read out, and eIO_Read was requested as the "event".
478
618
* Both eIO_Write and eIO_ReadWrite events always immediately succeed for
479
619
* the datagram socket.
623
* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite
625
* [in] Maximum time to wait for an event
481
627
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Wait
483
EIO_Event event, /* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
484
630
const STimeout* timeout
488
/* Block until at least one of the sockets enlisted in "polls" array
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 */
644
/** Block until at least one of the sockets enlisted in "polls" array
489
645
* (of size "n") becomes available for requested operation (event),
490
646
* or until timeout expires (wait indefinitely if timeout is passed NULL).
491
647
* Return eIO_Success if at least one socket was found ready; eIO_Timeout
492
648
* if timeout expired; eIO_Unknown if underlying system call(s) failed.
493
* 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
494
650
* in its "revent"; for a failing socket, eIO_Close is returned;
495
* NOTE2: This call may return eIO_InvalidArg if
651
* @li <b>NOTE 2:</b> This call may return eIO_InvalidArg if
496
652
* - parameters to the call are inconsistent;
497
653
* - a non-NULL socket polled with a bad "event" (eIO_Open, eIO_Close).
498
654
* With this return code, the calling program cannot rely on "revent"
499
655
* fields the "polls" array as they might not be properly updated.
500
* 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"
501
657
* are NULL, then the returned result is either
502
658
* eIO_Timeout (after the specified amount of time was spent idle), or
503
659
* eIO_Interrupted (if signal came while the waiting was in progress).
504
* 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
505
661
* message data latched since last message receive call (DSOCK_RecvMsg).
506
* NOTE5: This call allows intermixture of stream and datagram sockets.
507
* 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
508
664
* read-on-write and those with pending connection or output data.
666
* [in] # of SSOCK_Poll elems in "polls"
668
* [in|out] array of query/result structures
670
* [in] max time to wait (infinite if NULL)
672
* [out] # of ready sockets (may be NULL)
512
SOCK sock; /* [in] SOCK to poll (NULL if not to poll) */
513
EIO_Event event; /* [in] one of: eIO_Read, eIO_Write, eIO_ReadWrite */
514
EIO_Event revent; /* [out] one of: eIO_Open/Read/Write/ReadWrite/Close */
517
674
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Poll
518
(size_t n, /* [in] # of SSOCK_Poll elems in "polls" */
519
SSOCK_Poll polls[], /* [in|out] array of query/result structures */
520
const STimeout* timeout, /* [in] max time to wait (infinite if NULL) */
521
size_t* n_ready /* [out] # of ready sockets (may be NULL) */
677
const STimeout* timeout,
526
/* GENERIC POLLABLE INTERFACE, please see above for explanations
683
/** GENERIC POLLABLE INTERFACE, please see above for explanations
528
685
struct SPOLLABLE_tag;
529
686
typedef struct SPOLLABLE_tag* POLLABLE;
605
785
* eIO_Read[Persist] -- discard up to "size" bytes from internal buffer
606
786
* and socket (check "*n_read" to know how many).
608
* 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
609
789
* enough but some data available immediately from the internal buffer,
610
790
* then the call completes with eIO_Success status. For "peek", if
611
791
* not all requested data were available, the real I/O occurs to pick up
612
792
* additional data (if any) from the system. Keep this difference in
613
793
* mind when programming loops that heavily use "peek"s without "read"s.
614
* 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
615
795
* return value can be either of eIO_Success, eIO_Closed or
616
796
* eIO_Unknown depending on connection status of the socket.
800
* [out] data buffer to read to
802
* [in] max # of bytes to read to "buf"
804
* [out] # of bytes read (can be NULL)
806
* [in] how to read the data
618
808
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Read
620
void* buf, /* [out] data buffer to read to */
621
size_t size, /* [in] max # of bytes to read to "buf" */
622
size_t* n_read, /* [out] # of bytes read (can be NULL) */
623
EIO_ReadMethod how /* [in] how to read the data */
627
/* Push the specified data back to the socket input queue (in the socket's
818
* Read a line from SOCK. A line is terminated by either '\n' (with
819
* optional preceding '\r') or '\0'. Returned result is always '\0'-
820
* terminated and having '\r'(if any)'\n' stripped. *n_read (if 'n_read'
821
* passed non-NULL) contains the numbed of characters written into
822
* 'buf' (not counting the terminating '\0'). If 'buf', whose size is
823
* specified via 'size' parameter, is not big enough to contain the
824
* line, all 'size' bytes will be filled, with *n_read == size upon
825
* return. Note that there will be no terminating '\0' in this
826
* (and the only) case, which the caller can easily distinguish.
830
* [out] data buffer to read to
832
* [in] max # of bytes to read to "buf"
834
* [out] # of bytes read (can be NULL)
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).
841
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_ReadLine
849
/** Push the specified data back to the socket input queue (in the socket's
628
850
* internal read buffer). These can be any data, not necessarily the data
629
851
* previously read from the socket.
855
* [in] data to push back to the socket's local buffer
857
* [in] # of bytes (starting at "buf") to push back
631
859
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_PushBack
633
const void* buf, /* [in] data to push back to the socket's local buffer */
634
size_t size /* [in] # of bytes (starting at "buf") to push back */
638
/* Return (for the specified "direction" [eIO_Open to check for closed sock]):
870
* [in] one of: eIO_Open, eIO_Read, eIO_Write
872
* Return (for the specified "direction" [eIO_Open to check for closed sock]):
639
873
* eIO_Closed -- if the connection was shutdown by SOCK_Shutdown(), or
640
874
* (for "eIO_Read" only) if EOF was detected
641
875
* if "direction"==eIO_Open, this code means socket closed
653
887
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Status
655
EIO_Event direction /* [in] one of: eIO_Open, eIO_Read, eIO_Write */
659
/* Write "size" bytes from buffer "buf" to "sock".
660
* In "*n_written", return the number of bytes actually written.
661
* eIO_WritePlain -- write as many bytes as possible at once and return
893
/** Write "size" bytes from buffer "buf" to "sock".
897
* [in] data to write to the socket
899
* [in] # of bytes (starting at "buf") to write
901
* [out] # of written bytes (can be NULL)
903
* [in] eIO_WritePlain | eIO_WritePersist
905
* In "*n_written", return the number of bytes actually written.
906
* eIO_WritePlain -- write as many bytes as possible at once and return
662
907
* immediately; if no bytes can be written then wait
663
908
* at most WRITE timeout, try again and return.
664
* eIO_WritePersist -- write all data (doing an internal retry loop
909
* eIO_WritePersist -- write all data (doing an internal retry loop
665
910
* if necessary); if any single write attempt times out
666
911
* or fails then stop writing and return (error code).
667
* Return status: eIO_Success -- some bytes were written successfully [Plain]
912
* Return status: eIO_Success -- some bytes were written successfully [Plain]
668
913
* -- all bytes were written successfully [Persist]
669
914
* other code denotes an error, but some bytes might have
670
915
* been sent nevertheless (always check *n_written to know).
672
* 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
673
918
* were actually written to the socket. If no data could be written
674
919
* (and perhaps timeout expired) this call always returns an error.
675
* 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
676
921
* flag an error condition even if some data were actually written
677
922
* (see "the rule of thumb" in the comments for SOCK_Read() above).
678
* 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
679
924
* left in the socket, or eIO_Timeout if there are still data pending.
680
925
* In either case, "*n_written" is set to 0 on return.
682
927
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Write
684
const void* buf, /* [in] data to write to the socket */
685
size_t size, /* [in] # of bytes (starting at "buf") to write */
686
size_t* n_written, /* [out] # of written bytes (can be NULL) */
687
EIO_WriteMethod how /* [in] eIO_WritePlain | eIO_WritePersist */
691
/* If there is outstanding connection or output data pending, cancel it.
936
/** If there is outstanding connection or output data pending, cancel it.
692
937
* Mark the socket as if it has been shut down for both reading and writing.
693
938
* Break actual connection if any was established.
694
939
* Do not attempt to send anything upon SOCK_Close().
695
940
* This call is available for stream sockets only.
697
944
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Abort
702
/* Get host and port of the socket's peer.
703
* If "network_byte_order" is true(non-zero) then return the host/port in the
704
* network byte order; otherwise return them in the local host byte order.
949
/** Get host and port of the socket's peer.
953
* [out] the peer's host (can be NULL)
955
* [out] the peer's port (can be NULL)
957
* [in] host/port byte order
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.
706
962
extern NCBI_XCONNECT_EXPORT void SOCK_GetPeerAddress
708
unsigned int* host, /* [out] the peer's host (can be NULL) */
709
unsigned short* port, /* [out] the peer's port (can be NULL) */
710
ENH_ByteOrder byte_order /* [in] host/port byte order */
965
unsigned short* port,
966
ENH_ByteOrder byte_order
714
/* Get textual representation of the socket's peer.
970
/** Get textual representation of the socket's peer.
715
971
* For INET domain sockets, the result is of the form "aaa.bbb.ccc.ddd:ppppp";
716
972
* for UNIX domain socket, the result is the name of the socket's file.
717
* On success, return its "buf" argument; return 0 on error.
976
* [out] pointer to provided buffer to store the text to
978
* [in] usable size of the buffer above
980
* On success, return its "buf" argument; return 0 on error.
719
982
extern NCBI_XCONNECT_EXPORT char* SOCK_GetPeerAddressString
721
char* buf, /* [out] pointer to provided buffer to store the text to */
722
size_t buflen /* [in] usable size of the buffer above */
726
/* 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.
727
990
* FYI: on MS-Windows it will be "SOCKET", on other platforms -- "int".
994
* pointer to a memory area to put the OS handle at
996
* the exact(!) size of the expected OS handle
729
998
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_GetOSHandle
731
void* handle_buf, /* pointer to a memory area to put the OS handle at */
732
size_t handle_size /* the exact(!) size of the expected OS handle */
736
/* 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
737
1006
* from inside SOCK_Write(). If you want to automagically upread the data
738
1007
* (and cache it in the internal socket buffer) when the write operation
739
1008
* is not immediately available, call this func with "on_off" == eOn.
740
* Return prior setting.
742
1014
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWriteAPI
747
/* Control the reading-while-writing feature for socket "sock" individually.
1019
/** Control the reading-while-writing feature for socket "sock" individually.
748
1020
* To reset to the global default behavior (as set by
749
1021
* SOCK_SetReadOnWriteAPI), call this function with "on_off" == eDefault.
750
* Return prior setting.
1023
* [in] socket handle
752
1029
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWrite
798
1095
* buffers correspondingly.
1100
* [out] socket created
802
1102
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Create
803
(SOCK* sock /* [out] socket created */
1108
* [out] socket created
1110
* [in] whether to log data activity
807
1112
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_CreateEx
808
(SOCK* sock, /* [out] socket created */
809
ESwitch log /* [in] whether to log data activity*/
1119
* [in] SOCK from DSOCK_Create[Ex]()
1121
* [in] port to bind to (!=0)
813
1123
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Bind
814
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
815
unsigned short port /* [in] port to bind to (!=0) */
1130
* [in] SOCK from DSOCK_Create[Ex]()
819
1136
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Connect
820
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
821
const char* host, /* [in] peer host */
822
unsigned short port /* [in] peer port */
1144
* [in] SOCK from DSOCK_Create[Ex]()
1146
* [in] time to wait for message
826
1148
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_WaitMsg
827
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
828
const STimeout* timeout /* [in] time to wait for message */
1150
const STimeout* timeout
1155
* [in] SOCK from DSOCK_Create[Ex]()
1157
* [in] hostname or dotted IP
1159
* [in] port number, host byte order
1161
* [in] additional data to send
1163
* [in] size of additional data (bytes)
832
1165
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_SendMsg
833
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
834
const char* host, /* [in] hostname or dotted IP */
835
unsigned short port, /* [in] port number, host byte order*/
836
const void* data, /* [in] additional data to send */
837
size_t datalen /* [in] size of addtl data (bytes) */
1168
unsigned short port,
1175
* [in] SOCK from DSOCK_Create[Ex]()
1177
* [in] buf to store msg at,m.b.NULL
1179
* [in] buf length provided
1181
* [in] maximal expected message len
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
841
1189
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_RecvMsg
842
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
843
void* buf, /* [in] buf to store msg at,m.b.NULL*/
844
size_t buflen, /* [in] buf length provided */
845
size_t maxmsglen, /* [in] maximal expected message len*/
846
size_t* msglen, /* [out] actual msg size, may be NULL*/
847
unsigned int* sender_addr, /* [out] net byte order, may be NULL */
848
unsigned short* sender_port /* [out] host byte order, may be NULL*/
1195
unsigned int* sender_addr,
1196
unsigned short* sender_port
1201
* [in] SOCK from DSOCK_Create[Ex]()
1203
* [in] either of eIO_Read|eIO_Write
852
1205
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_WipeMsg
853
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
854
EIO_Event direction /* [in] either of eIO_Read|eIO_Write*/
1212
* [in] SOCK from DSOCK_Create[Ex]()
1214
* [in] set(1)/unset(0) bcast capab
858
1216
extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_SetBroadcast
859
(SOCK sock, /* [in] SOCK from DSOCK_Create[Ex]()*/
860
int/*bool*/ broadcast /* [in] set(1)/unset(0) bcast capab.*/
1218
int/**bool*/ broadcast
919
1315
#define SOCK_NetToHostLong SOCK_HostToNetLong
921
1321
extern NCBI_XCONNECT_EXPORT unsigned short SOCK_HostToNetShort
922
1322
(unsigned short value
925
1325
#define SOCK_NetToHostShort SOCK_HostToNetShort
928
#define SOCK_htonl SOCK_HostToNetLong
929
#define SOCK_ntohl SOCK_NetToHostLong
930
#define SOCK_htons SOCK_HostToNetShort
931
#define SOCK_ntohs SOCK_NetToHostShort
934
/* Return INET host address (in network byte order) of the
935
* specified host (or local host, if hostname is passed as NULL),
936
* which can be either domain name or an IP address in
937
* dotted notation (e.g. "123.45.67.89\0"). Return 0 on error.
938
* NOTE: "0.0.0.0" and "255.255.255.255" are considered invalid.
1328
/* Deprecated: Use SOCK_{Host|Net}To{Net|Host}{Long|Short}() instead */
1329
#ifndef NCBI_DEPRECATED
1330
# define NCBI_SOCK_DEPRECATED
1332
# define NCBI_SOCK_DEPRECATED NCBI_DEPRECATED
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
1344
* [in] return current host address if hostname is 0
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.
940
1352
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_gethostbyname
941
(const char* hostname /* [in] return current host address if hostname is 0 */
1353
(const char* hostname \
945
/* 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
946
1358
* the provided buffer with the name, which the address corresponds to
947
* (in case of multiple names the primary name is used). Return value 0
948
* means error, while success is denoted by the 'name' argument returned.
949
* Note that on error the name returned emptied (name[0] == '\0').
1359
* (in case of multiple names the primary name is used).
1361
* [in] host address in network byte order
1363
* [out] buffer to put the name to
1365
* [in] size (bytes) of the buffer above
1368
* means error, while success is denoted by the 'name' argument returned.
1369
* Note that on error the name returned emptied (name[0] == '\0').
951
1371
extern NCBI_XCONNECT_EXPORT char* SOCK_gethostbyaddr
952
(unsigned int addr, /* [in] host address in network byte order */
953
char* name, /* [out] buffer to put the name to */
954
size_t namelen /* [in] size (bytes) of the buffer above */
1380
* Loopback address (in network byte order).
1382
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_GetLoopbackAddress(void);
1385
/** Read (skipping leading blanks) "[host][:port]" from a string.
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.
1401
extern NCBI_XCONNECT_EXPORT const char* SOCK_StringToHostPort
1404
unsigned short* port
1408
/** Print host:port into provided buffer string, not to exceed 'buflen' size.
1409
* Suppress printing host if parameter 'host' is zero.
1419
* Number of bytes printed.
1421
extern NCBI_XCONNECT_EXPORT size_t SOCK_HostPortToString
1423
unsigned short port,
added
removed
connect/ncbi_socket.h
