ncbi_socket.h

ncbi源码

 ESwitch         log       /* [in]  whether to do logging on this socket     */
 );


/* [SERVER-side]  Create a socket on top of OS-dependent "handle"
 * (file descriptor on Unix). Returned socket is not reopenable to its
 * default peer (SOCK_Reconnect may not specify zeros for the connection
 * point).  All timeouts are set to its default [infinite] values.
 * SOCK_Close() will close the "handle" only if the "close_on_close"
 * parameter is passed non-zero (eSCOT_CloseOnClose).
 * Return eIO_Success on success; otherwise: eIO_Closed if the "handle" does
 * not refer to an open socket [but e.g. to a normal file or a pipe];
 * other error codes in case of other errors.
 */
typedef enum {
    eSCOT_KeepOnClose,    /* Do not close "handle" on SOCK_Close() */
    eSCOT_CloseOnClose    /* Do close "handle" on SOCK_Close() */
} ESCOT_OnClose;

/* SOCK_CreateOnTopEx(handle, handle_size, sock,
                      0, 0, eDefault, eSCOT_CloseOnClose) */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTop
(const void*   handle,      /* [in]  OS-dependent "handle" to be converted */
 size_t        handle_size, /* [in]  "handle" size                         */
 SOCK*         sock         /* [out] SOCK built on top of OS "handle"      */
 );

extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CreateOnTopEx
(const void*   handle,      /* [in]  OS-dependent "handle" to be converted */
 size_t        handle_size, /* [in]  "handle" size                         */
 SOCK*         sock,        /* [out] SOCK built on top of OS "handle"      */
 const void*   init_data,   /* [in]  initial output data segment (ok NULL) */
 size_t        init_size,   /* [in]  size of initial data segment (ok 0)   */
 ESwitch       log,         /* [in]  data logging for the resulting SOCK   */
 ESCOT_OnClose on_close     /* [in]  if to keep "handle" in SOCK_Close()   */
 );


/* [CLIENT-side]  Close the socket referred to by "sock" and then connect
 * it to another "host:port";  fail if it takes more than "timeout"
 * (close() + connect() [+ select()])
 *
 * HINT:  if "host" is NULL then connect to the same host address as before;
 *        if "port" is zero then connect to the same port # as before.
 *
 * NOTE1: "new" socket inherits the old I/O timeouts.
 * NOTE2: the call is applicable to stream [not datagram] sockets only.
 * NOTE3: "timeout"==NULL is infinite; "timeout"=={0,0} causes no wait for
 *        connection to be established and to return immediately.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Reconnect
(SOCK            sock,    /* [in] handle of the socket to reconnect      */
 const char*     host,    /* [in] host to connect to  (can be NULL)      */
 unsigned short  port,    /* [in] port to connect to  (can be 0)         */
 const STimeout* timeout  /* [in] the connect timeout (infinite if NULL) */
 );


/* Shutdown the connection in only one direction (specified by "direction").
 * Later attempts to I/O (or to wait) in the shutdown direction will
 * do nothing, and immediately return with "eIO_Closed" status.
 * Pending data output can cause data transfer to the remote end (subject
 * for eIO_Close timeout as previously set by SOCK_SetTimeout()).
 * Cannot be applied to datagram sockets (eIO_InvalidArg results).
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Shutdown
(SOCK      sock, /* [in] handle of the socket to shutdown            */
 EIO_Event how   /* [in] one of:  eIO_Read, eIO_Write, eIO_ReadWrite */
 );


/* Close the connection, destroy relevant internal data.
 * The "sock" handle goes invalid after this function call, regardless
 * of whether the call was successful or not.
 * NOTE1:  if eIO_Close timeout was specified (or NULL) then it blocks until
 *         either all unsent data are sent, error flagged, or the timeout
 *         expires.
 * NOTE2:  if there is output pending, that output will be flushed.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Close(SOCK sock);


/* Close the connection, and conditionally destroy relevant internal data.
 * NOTE1:  if eIO_Close timeout was specified (or NULL) then it blocks until
 *         either all unsent data are sent, error flagged, or the timeout
 *         expires.
 * NOTE2:  if there is output pending, that output will be flushed.
 * NOTE3:  SOCK_CloseEx(sock, 1) is equivalent to SOCK_Close(sock);
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_CloseEx
(SOCK        sock,    /* [in] handle of the socket to close           */
 int/*bool*/ destroy  /* [in] =1 to destroy handle; =0 to keep handle */
 );


/* Block on the socket until either read/write (dep. on the "event" arg) is
 * available or timeout expires (if "timeout" is NULL then assume it infinite).
 * For a datagram socket, eIO_Closed is returned if the internally latched
 * message was entirely read out, and eIO_Read was requested as the "event".
 * Both eIO_Write and eIO_ReadWrite events always immediately succeed for
 * the datagram socket.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Wait
(SOCK            sock,
 EIO_Event       event,  /* [in] one of:  eIO_Read, eIO_Write, eIO_ReadWrite */
 const STimeout* timeout
 );


/* Block until at least one of the sockets enlisted in "polls" array
 * (of size "n") becomes available for requested operation (event),
 * or until timeout expires (wait indefinitely if timeout is passed NULL).
 * Return eIO_Success if at least one socket was found ready; eIO_Timeout
 * if timeout expired; eIO_Unknown if underlying system call(s) failed.
 * NOTE1: For a socket found not ready for an operation, eIO_Open is returned
 *        in its "revent"; for a failing socket, eIO_Close is returned;
 * NOTE2: This call may return eIO_InvalidArg if
 *        - parameters to the call are inconsistent;
 *        - a non-NULL socket polled with a bad "event" (eIO_Open, eIO_Close).
 *        With this return code, the calling program cannot rely on "revent"
 *        fields the "polls" array as they might not be properly updated.
 * NOTE3: If either both "n" and "polls" are NULL, or all sockets in "polls"
 *        are NULL, then the returned result is either
 *        eIO_Timeout (after the specified amount of time was spent idle), or
 *        eIO_Interrupted (if signal came while the waiting was in progress).
 * NOTE4: For datagram sockets, the readiness for reading is determined by
 *        message data latched since last message receive call (DSOCK_RecvMsg).
 * NOTE5: This call allows intermixture of stream and datagram sockets.
 * NOTE6: This call can cause some socket I/O in those sockets marked for
 *        read-on-write and those with pending connection or output data.
 */

typedef struct {
    SOCK      sock;   /* [in]           SOCK to poll (NULL if not to poll)   */
    EIO_Event event;  /* [in]  one of:  eIO_Read, eIO_Write, eIO_ReadWrite   */
    EIO_Event revent; /* [out] one of:  eIO_Open/Read/Write/ReadWrite/Close  */
} SSOCK_Poll;

extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Poll
(size_t          n,         /* [in]      # of SSOCK_Poll elems in "polls"    */
 SSOCK_Poll      polls[],   /* [in|out]  array of query/result structures    */
 const STimeout* timeout,   /* [in]      max time to wait (infinite if NULL) */
 size_t*         n_ready    /* [out]     # of ready sockets  (may be NULL)   */
 );



/* GENERIC POLLABLE INTERFACE, please see above for explanations
 */
struct SPOLLABLE_tag;
typedef struct SPOLLABLE_tag* POLLABLE;

typedef struct {
    POLLABLE  poll;
    EIO_Event event;
    EIO_Event revent;
} SPOLLABLE_Poll;

extern NCBI_XCONNECT_EXPORT EIO_Status POLLABLE_Poll
(size_t          n,
 SPOLLABLE_Poll  polls[],
 const STimeout* timeout,
 size_t*         n_ready
 );


/* Return 0 if conversion cannot be made; otherwise converted handle */
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromSOCK (SOCK);
extern NCBI_XCONNECT_EXPORT POLLABLE POLLABLE_FromLSOCK(LSOCK);
extern NCBI_XCONNECT_EXPORT SOCK     POLLABLE_ToSOCK   (POLLABLE);
extern NCBI_XCONNECT_EXPORT LSOCK    POLLABLE_ToLSOCK  (POLLABLE);


/* Specify timeout for the connection i/o (see SOCK_[Read|Write|Close] funcs).
 * If "timeout" is NULL then set the timeout to be infinite;
 * NOTE: the default timeout is infinite (wait "ad infinitum" on I/O).
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_SetTimeout
(SOCK            sock,
 EIO_Event       event,   /* [in]  one of:  eIO_[Read/Write/ReadWrite/Close] */
 const STimeout* timeout  /* [in]  new timeout value to set                  */
 );


/* Get the connection's i/o timeout (or NULL, if the timeout is infinite).
 * NOTE1:  the returned timeout is guaranteed to be pointing to a valid
 *         (and correct) structure in memory at least until the SOCK is closed
 *         or SOCK_SetTimeout is called for this "sock".
 * NOTE2:  eIO_ReadWrite timeout is the least of eIO_Read and eIO_Write ones.
 */
extern NCBI_XCONNECT_EXPORT const STimeout* SOCK_GetTimeout
(SOCK      sock,
 EIO_Event event  /* [in]  one of:  eIO_[Read/Write/Close] */
 );


/* Read/peek up to "size" bytes from "sock" to the mem.buffer pointed by "buf".
 * In "*n_read", return the number of successfully read bytes.
 * Read method "how" can be either of the following:
 * eIO_ReadPlain   -- read as many as "size" bytes and return (eIO_Success);
 *                    if no data are readily available then wait at most
 *                    read timeout and return (eIO_Timeout) if no data still
 *                    could be got; eIO_Success if some data were obtained.
 * eIO_ReadPeek    -- same as "eIO_ReadPlain" but do not extract the data from
 *                    the socket (so that the next read operation will see the
 *                    data again), with one important exception noted below.
 * eIO_ReadPersist -- read exactly "size" bytes and return eIO_Success; if less
 *                    data received then return an error condition (including
 *                    eIO_Timeout).
 *
 * If there is no data available to read (also, if eIO_ReadPersist and cannot
 * read exactly "size" bytes) and the timeout(see SOCK_SetTimeout) is expired
 * then return eIO_Timeout.
 *
 * Both eIO_ReadPlain and eIO_ReadPeek return eIO_Success iff some data have
 * been read (perhaps within the time allowance specified by eIO_Read timeout).
 * Both mothods return any other code when no data at all were available.
 * eIO_ReadPersist differs from the other two methods as it can return an
 * error condition even if some data were actually obtained from the socket.
 * Hence, as a rule of thumb, an application should always check the number
 * of read bytes BEFORE checking the return status, which merely advises
 * whether it is okay to read again.
 *
 * As a special case, "buf" may passed as NULL:
 *   eIO_ReadPeek      -- read up to "size" bytes and store them
 *                        in internal buffer;
 *   eIO_Read[Persist] -- discard up to "size" bytes from internal buffer
 *                        and socket (check "*n_read" to know how many).
 *
 * NOTE1: "Read" and "peek" methods differ:  if "read" is performed and not
 *        enough but some data available immediately from the internal buffer,
 *        then the call completes with eIO_Success status.  For "peek", if
 *        not all requested data were available, the real I/O occurs to pick up
 *        additional data (if any) from the system. Keep this difference in
 *        mind when programming loops that heavily use "peek"s without "read"s.
 * NOTE2: If on input "size" == 0, then "*n_read" is set to 0, and the
 *        return value can be either of eIO_Success, eIO_Closed or
 *        eIO_Unknown depending on connection status of the socket.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Read
(SOCK           sock,
 void*          buf,    /* [out] data buffer to read to          */
 size_t         size,   /* [in]  max # of bytes to read to "buf" */
 size_t*        n_read, /* [out] # of bytes read  (can be NULL)  */
 EIO_ReadMethod how     /* [in]  how to read the data            */
 );


/* Push the specified data back to the socket input queue (in the socket's
 * internal read buffer). These can be any data, not necessarily the data
 * previously read from the socket.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_PushBack
(SOCK        sock,
 const void* buf,  /* [in] data to push back to the socket's local buffer */
 size_t      size  /* [in] # of bytes (starting at "buf") to push back    */
 );


/* Return (for the specified "direction" [eIO_Open to check for closed sock]):
 *   eIO_Closed     -- if the connection was shutdown by SOCK_Shutdown(), or
 *                     (for "eIO_Read" only) if EOF was detected
 *                     if "direction"==eIO_Open, this code means socket closed
 *   eIO_Unknown    -- if an error was detected during the last I/O
 *   eIO_InvalidArg -- if "direction" is not one of:  Open, Read, Write
 *   eIO_Timeout    -- if the socket is not yet actually connected
 *   eIO_Success    -- otherwise (incl. eIO_Timeout on last I/O)
 *
 * NOTE:  The SOCK_Read() and SOCK_Wait(eIO_Read) will not return any error
 *        as long as there is any unread (buffered) data left.
 *        Thus, when you are "peeking" data instead of actually reading it,
 *        then this is the only "non-destructive" way to check whether EOF
 *        or an error has actually occurred on read.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Status
(SOCK      sock,
 EIO_Event direction  /* [in] one of:  eIO_Open, eIO_Read, eIO_Write */
 );


/* Write "size" bytes from buffer "buf" to "sock".
 * In "*n_written", return the number of bytes actually written.
 * eIO_WritePlain   --  write as many bytes as possible at once and return
 *                      immediately; if no bytes can be written then wait
 *                      at most WRITE timeout, try again and return.
 * eIO_WritePersist --  write all data (doing an internal retry loop
 *                      if necessary); if any single write attempt times out
 *                      or fails then stop writing and return (error code).
 * Return status: eIO_Success -- some bytes were written successfully  [Plain]
 *                            -- all bytes were written successfully [Persist]
 *                other code denotes an error, but some bytes might have
 *                been sent nevertheless (always check *n_written to know).
 *
 * NOTE1: With eIO_WritePlain the call returns eIO_Success iff some data
 *        were actually written to the socket. If no data could be written
 *        (and perhaps timeout expired) this call always returns an error.
 * NOTE2: eIO_WritePlain and eIO_WritePersist differs that the latter can
 *        flag an error condition even if some data were actually written
 *        (see "the rule of thumb" in the comments for SOCK_Read() above).
 * NOTE3: if "size"==0, return value can be eIO_Success if no pending data
 *        left in the socket, or eIO_Timeout if there are still data pending.
 *        In either case, "*n_written" is set to 0 on return.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Write
(SOCK            sock,
 const void*     buf,       /* [in]  data to write to the socket             */
 size_t          size,      /* [in]  # of bytes (starting at "buf") to write */
 size_t*         n_written, /* [out] # of written bytes (can be NULL)        */
 EIO_WriteMethod how        /* [in]  eIO_WritePlain | eIO_WritePersist       */
 );


/* If there is outstanding connection or output data pending, cancel it.
 * Mark the socket as if it has been shut down for both reading and writing.
 * Break actual connection if any was established.
 * Do not attempt to send anything upon SOCK_Close().
 * This call is available for stream sockets only.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_Abort
(SOCK sock
 );


/* Get host and port of the socket's peer.
 * If "network_byte_order" is true(non-zero) then return the host/port in the
 * network byte order; otherwise return them in the local host byte order.
 */
extern NCBI_XCONNECT_EXPORT void SOCK_GetPeerAddress
(SOCK            sock,
 unsigned int*   host,                /* [out] the peer's host (can be NULL) */
 unsigned short* port,                /* [out] the peer's port (can be NULL) */
 ENH_ByteOrder   byte_order           /* [in]  host/port byte order          */
 );


/* Get textual representation of the socket's peer.
 * For INET domain sockets, the result is of the form "aaa.bbb.ccc.ddd:ppppp";
 * for UNIX domain socket, the result is the name of the socket's file.
 * On success, return its "buf" argument; return 0 on error.
 */
extern NCBI_XCONNECT_EXPORT char* SOCK_GetPeerAddressString
(SOCK   sock,
 char*  buf,        /* [out] pointer to provided buffer to store the text to */
 size_t buflen      /* [in]  usable size of the buffer above                 */
 );


/* Get an OS-dependent native socket handle to use by platform-specific API.
 * FYI:  on MS-Windows it will be "SOCKET", on other platforms -- "int".
 */
extern NCBI_XCONNECT_EXPORT EIO_Status SOCK_GetOSHandle
(SOCK   sock,
 void*  handle_buf,  /* pointer to a memory area to put the OS handle at */
 size_t handle_size  /* the exact(!) size of the expected OS handle      */
 );


/* By default ("on_off" == eDefault,eOff), sockets will not try to read data
 * from inside SOCK_Write(). If you want to automagically upread the data
 * (and cache it in the internal socket buffer) when the write operation
 * is not immediately available, call this func with "on_off" == eOn.
 * Return prior setting.
 */
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWriteAPI
(ESwitch on_off
 );


/* Control the reading-while-writing feature for socket "sock" individually.
 * To reset to the global default behavior (as set by
 * SOCK_SetReadOnWriteAPI), call this function with "on_off" == eDefault.
 * Return prior setting.
 */
extern NCBI_XCONNECT_EXPORT ESwitch SOCK_SetReadOnWrite
(SOCK    sock,
 ESwitch on_off
 );