tcp.h revision 5b281ba489ca18f0380d7efc7a5108b606cce449
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/** @file
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync * IPRT - TCP/IP.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync */
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/*
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
c58f1213e628a545081c70e26c6b67a841cff880vboxsync *
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * available from http://www.virtualbox.org. This file is free software;
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * you can redistribute it and/or modify it under the terms of the GNU
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync *
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * The contents of this file may alternatively be used under the terms
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * of the Common Development and Distribution License Version 1.0
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * VirtualBox OSE distribution, in which case the provisions of the
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * CDDL are applicable instead of those of the GPL.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync *
19edb133387698f301b529248daa3719fe0d7389vboxsync * You may elect to license modified versions of this file under the
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync * terms and conditions of either the GPL or the CDDL or both.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync *
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * additional information or have any questions.
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync */
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync#ifndef ___iprt_tcp_h
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync#define ___iprt_tcp_h
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync#include <iprt/cdefs.h>
19edb133387698f301b529248daa3719fe0d7389vboxsync#include <iprt/types.h>
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync#include <iprt/thread.h>
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync#ifdef IN_RING0
039cd2c4871a00e51af909222a34695d9cec3000vboxsync# error "There are no RTFile APIs available Ring-0 Host Context!"
039cd2c4871a00e51af909222a34695d9cec3000vboxsync#endif
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync__BEGIN_DECLS
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/** @defgroup grp_rt_tcp RTTcp - TCP/IP
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @ingroup grp_rt
19edb133387698f301b529248daa3719fe0d7389vboxsync * @{
19edb133387698f301b529248daa3719fe0d7389vboxsync */
19edb133387698f301b529248daa3719fe0d7389vboxsync
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/**
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * Serve a TCP Server connection.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync *
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @returns iprt status code.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @returns VERR_TCP_SERVER_STOP to terminate the server loop forcing
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * the RTTcpCreateServer() call to return.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @param Sock The socket which the client is connected to.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * The call will close this socket.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @param pvUser User argument.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync */
039cd2c4871a00e51af909222a34695d9cec3000vboxsynctypedef DECLCALLBACK(int) FNRTTCPSERVE(RTSOCKET Sock, void *pvUser);
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/** Pointer to a RTTCPSERVE(). */
c161379f4055372228230517aa1700c47e3b9b7fvboxsynctypedef FNRTTCPSERVE *PFNRTTCPSERVE;
c161379f4055372228230517aa1700c47e3b9b7fvboxsync
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync/** Pointer to a RTTCPSERVER handle. */
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsynctypedef struct RTTCPSERVER *PRTTCPSERVER;
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync/** Pointer to a RTTCPSERVER handle. */
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsynctypedef PRTTCPSERVER *PPRTTCPSERVER;
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync/**
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * Create single connection at a time TCP Server in a separate thread.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync *
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * The thread will loop accepting connections and call pfnServe for
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * each of the incoming connections in turn. The pfnServe function can
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * return VERR_TCP_SERVER_STOP too terminate this loop. RTTcpServerDestroy()
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * should be used to terminate the server.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync *
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @returns iprt status code.
cce0081609f23d8da22c27c496afd6037716643cvboxsync * @param pszAddress The address for creating a listening socket.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * If NULL or empty string the server is bound to all interfaces.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param uPort The port for creating a listening socket.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param enmType The thread type.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pszThrdName The name of the worker thread.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pfnServe The function which will serve a new client connection.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pvUser User argument passed to pfnServe.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param ppServer Where to store the serverhandle.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync */
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsyncRTR3DECL(int) RTTcpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
039cd2c4871a00e51af909222a34695d9cec3000vboxsync PFNRTTCPSERVE pfnServe, void *pvUser, PPRTTCPSERVER ppServer);
943a094c1ebbdb66dfc1f35de71bfc23fb4eb1f4vboxsync
da46e47d18df400d98d0fa231743083377526fd3vboxsync/**
da46e47d18df400d98d0fa231743083377526fd3vboxsync * Create single connection at a time TCP Server.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * The caller must call RTTcpServerListen() to actually start the server.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync *
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @returns iprt status code.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @param pszAddress The address for creating a listening socket.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * If NULL the server is bound to all interfaces.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @param uPort The port for creating a listening socket.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @param ppServer Where to store the serverhandle.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync */
039cd2c4871a00e51af909222a34695d9cec3000vboxsyncRTR3DECL(int) RTTcpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTTCPSERVER ppServer);
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/**
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * Closes down and frees a TCP Server.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * This will also terminate any open connections to the server.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync *
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @returns iprt status code.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pServer Handle to the server.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync */
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsyncRTR3DECL(int) RTTcpServerDestroy(PRTTCPSERVER pServer);
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync/**
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * Listen for incoming connections.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync *
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * The function will loop accepting connections and call pfnServe for
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * each of the incoming connections in turn. The pfnServe function can
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * return VERR_TCP_SERVER_STOP too terminate this loop. A stopped server
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * can only be destroyed.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync *
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @returns iprt status code.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pServer The server handle as returned from RTTcpServerCreateEx().
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pfnServe The function which will serve a new client connection.
30e6672eae531c74fca0d2e7c3cdb11e5ce03f48vboxsync * @param pvUser User argument passed to pfnServe.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync */
039cd2c4871a00e51af909222a34695d9cec3000vboxsyncRTR3DECL(int) RTTcpServerListen(PRTTCPSERVER pServer, PFNRTTCPSERVE pfnServe, void *pvUser);
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
039cd2c4871a00e51af909222a34695d9cec3000vboxsync/**
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * Terminate the open connection to the server.
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync *
039cd2c4871a00e51af909222a34695d9cec3000vboxsync * @returns iprt status code.
b51cedf2af5c5e6fb04d36789233a9d6ffa54eacvboxsync * @param pServer Handle to the server.
039cd2c4871a00e51af909222a34695d9cec3000vboxsync */
039cd2c4871a00e51af909222a34695d9cec3000vboxsyncRTR3DECL(int) RTTcpServerDisconnectClient(PRTTCPSERVER pServer);
039cd2c4871a00e51af909222a34695d9cec3000vboxsync
/**
* Connect (as a client) to a TCP Server.
*
* @returns iprt status code.
* @param pszAddress The address to connect to.
* @param uPort The port to connect to.
* @param pSock Where to store the handle to the established connection.
*/
RTR3DECL(int) RTTcpClientConnect(const char *pszAddress, uint32_t uPort, PRTSOCKET pSock);
/**
* Close a socket returned by RTTcpClientConnect().
*
* @returns iprt status code.
* @param Sock Socket descriptor.
*/
RTR3DECL(int) RTTcpClientClose(RTSOCKET Sock);
/**
* Receive data from a socket.
*
* @returns iprt status code.
* @param Sock Socket descriptor.
* @param pvBuffer Where to put the data we read.
* @param cbBuffer Read buffer size.
* @param pcbRead Number of bytes read.
* If NULL the entire buffer will be filled upon successful return.
* If not NULL a partial read can be done successfully.
*/
RTR3DECL(int) RTTcpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
/**
* Send data from a socket.
*
* @returns iprt status code.
* @param Sock Socket descriptor.
* @param pvBuffer Buffer to write data to socket.
* @param cbBuffer How much to write.
*/
RTR3DECL(int) RTTcpWrite(RTSOCKET Sock, const void *pvBuffer, size_t cbBuffer);
/**
* Flush socket write buffers.
*
* @returns iprt status code.
* @param Sock Socket descriptor.
*/
RTR3DECL(int) RTTcpFlush(RTSOCKET Sock);
/**
* Socket I/O multiplexing.
* Checks if the socket is ready for reading.
*
* @returns iprt status code.
* @param Sock Socket descriptor.
* @param cMillies Number of milliseconds to wait for the socket.
* Use RT_INDEFINITE_WAIT to wait for ever.
*/
RTR3DECL(int) RTTcpSelectOne(RTSOCKET Sock, unsigned cMillies);
#if 0 /* skipping these for now - RTTcpServer* handles this. */
/**
* Listen for connection on a socket.
*
* @returns iprt status code.
* @param Sock Socket descriptor.
* @param cBackLog The maximum length the queue of pending connections
* may grow to.
*/
RTR3DECL(int) RTTcpListen(RTSOCKET Sock, int cBackLog);
/**
* Accept a connection on a socket.
*
* @returns iprt status code.
* @param Sock Socket descriptor.
* @param uPort The port for accepting connection.
* @param pSockAccepted Where to store the handle to the accepted connection.
*/
RTR3DECL(int) RTTcpAccept(RTSOCKET Sock, unsigned uPort, PRTSOCKET pSockAccepted);
#endif
/** @} */
__END_DECLS
#endif