VirtualBox

source: vbox/trunk/include/iprt/tcp.h@ 26201

Last change on this file since 26201 was 25724, checked in by vboxsync, 15 years ago

iprt: Use RTMSINTERVAL for timeouts. Fixed missing timeout underflow checks in two RTFileAioCtxWait implementations.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.6 KB
Line 
1/** @file
2 * IPRT - TCP/IP.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_tcp_h
31#define ___iprt_tcp_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35#include <iprt/thread.h>
36
37#ifdef IN_RING0
38# error "There are no RTFile APIs available Ring-0 Host Context!"
39#endif
40
41
42RT_C_DECLS_BEGIN
43
44/** @defgroup grp_rt_tcp RTTcp - TCP/IP
45 * @ingroup grp_rt
46 * @{
47 */
48
49
50/**
51 * Serve a TCP Server connection.
52 *
53 * @returns iprt status code.
54 * @returns VERR_TCP_SERVER_STOP to terminate the server loop forcing
55 * the RTTcpCreateServer() call to return.
56 * @param Sock The socket which the client is connected to.
57 * The call will close this socket.
58 * @param pvUser User argument.
59 */
60typedef DECLCALLBACK(int) FNRTTCPSERVE(RTSOCKET Sock, void *pvUser);
61/** Pointer to a RTTCPSERVE(). */
62typedef FNRTTCPSERVE *PFNRTTCPSERVE;
63
64/** Pointer to a RTTCPSERVER handle. */
65typedef struct RTTCPSERVER *PRTTCPSERVER;
66/** Pointer to a RTTCPSERVER handle. */
67typedef PRTTCPSERVER *PPRTTCPSERVER;
68
69/**
70 * Create single connection at a time TCP Server in a separate thread.
71 *
72 * The thread will loop accepting connections and call pfnServe for
73 * each of the incoming connections in turn. The pfnServe function can
74 * return VERR_TCP_SERVER_STOP too terminate this loop. RTTcpServerDestroy()
75 * should be used to terminate the server.
76 *
77 * @returns iprt status code.
78 * @param pszAddress The address for creating a listening socket.
79 * If NULL or empty string the server is bound to all interfaces.
80 * @param uPort The port for creating a listening socket.
81 * @param enmType The thread type.
82 * @param pszThrdName The name of the worker thread.
83 * @param pfnServe The function which will serve a new client connection.
84 * @param pvUser User argument passed to pfnServe.
85 * @param ppServer Where to store the serverhandle.
86 */
87RTR3DECL(int) RTTcpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
88 PFNRTTCPSERVE pfnServe, void *pvUser, PPRTTCPSERVER ppServer);
89
90/**
91 * Create single connection at a time TCP Server.
92 * The caller must call RTTcpServerListen() to actually start the server.
93 *
94 * @returns iprt status code.
95 * @param pszAddress The address for creating a listening socket.
96 * If NULL the server is bound to all interfaces.
97 * @param uPort The port for creating a listening socket.
98 * @param ppServer Where to store the serverhandle.
99 */
100RTR3DECL(int) RTTcpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTTCPSERVER ppServer);
101
102/**
103 * Closes down and frees a TCP Server.
104 * This will also terminate any open connections to the server.
105 *
106 * @returns iprt status code.
107 * @param pServer Handle to the server.
108 */
109RTR3DECL(int) RTTcpServerDestroy(PRTTCPSERVER pServer);
110
111/**
112 * Listen for incoming connections.
113 *
114 * The function will loop accepting connections and call pfnServe for
115 * each of the incoming connections in turn. The pfnServe function can
116 * return VERR_TCP_SERVER_STOP too terminate this loop. A stopped server
117 * can only be destroyed.
118 *
119 * @returns iprt status code.
120 * @param pServer The server handle as returned from RTTcpServerCreateEx().
121 * @param pfnServe The function which will serve a new client connection.
122 * @param pvUser User argument passed to pfnServe.
123 */
124RTR3DECL(int) RTTcpServerListen(PRTTCPSERVER pServer, PFNRTTCPSERVE pfnServe, void *pvUser);
125
126/**
127 * Terminate the open connection to the server.
128 *
129 * @returns iprt status code.
130 * @param pServer Handle to the server.
131 */
132RTR3DECL(int) RTTcpServerDisconnectClient(PRTTCPSERVER pServer);
133
134/**
135 * Shuts down the server, leaving client connections open.
136 *
137 * @returns IPRT status code.
138 * @param pServer Handle to the server.
139 */
140RTR3DECL(int) RTTcpServerShutdown(PRTTCPSERVER pServer);
141
142/**
143 * Connect (as a client) to a TCP Server.
144 *
145 * @returns iprt status code.
146 * @param pszAddress The address to connect to.
147 * @param uPort The port to connect to.
148 * @param pSock Where to store the handle to the established connection.
149 */
150RTR3DECL(int) RTTcpClientConnect(const char *pszAddress, uint32_t uPort, PRTSOCKET pSock);
151
152/**
153 * Close a socket returned by RTTcpClientConnect().
154 *
155 * @returns iprt status code.
156 * @param Sock Socket descriptor.
157 */
158RTR3DECL(int) RTTcpClientClose(RTSOCKET Sock);
159
160/**
161 * Receive data from a socket.
162 *
163 * @returns iprt status code.
164 * @param Sock Socket descriptor.
165 * @param pvBuffer Where to put the data we read.
166 * @param cbBuffer Read buffer size.
167 * @param pcbRead Number of bytes read.
168 * If NULL the entire buffer will be filled upon successful return.
169 * If not NULL a partial read can be done successfully.
170 */
171RTR3DECL(int) RTTcpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
172
173/**
174 * Send data from a socket.
175 *
176 * @returns iprt status code.
177 * @param Sock Socket descriptor.
178 * @param pvBuffer Buffer to write data to socket.
179 * @param cbBuffer How much to write.
180 */
181RTR3DECL(int) RTTcpWrite(RTSOCKET Sock, const void *pvBuffer, size_t cbBuffer);
182
183/**
184 * Flush socket write buffers.
185 *
186 * @returns iprt status code.
187 * @param Sock Socket descriptor.
188 */
189RTR3DECL(int) RTTcpFlush(RTSOCKET Sock);
190
191/**
192 * Socket I/O multiplexing.
193 * Checks if the socket is ready for reading.
194 *
195 * @returns iprt status code.
196 * @param Sock Socket descriptor.
197 * @param cMillies Number of milliseconds to wait for the socket.
198 * Use RT_INDEFINITE_WAIT to wait for ever.
199 */
200RTR3DECL(int) RTTcpSelectOne(RTSOCKET Sock, RTMSINTERVAL cMillies);
201
202
203#if 0 /* skipping these for now - RTTcpServer* handles this. */
204/**
205 * Listen for connection on a socket.
206 *
207 * @returns iprt status code.
208 * @param Sock Socket descriptor.
209 * @param cBackLog The maximum length the queue of pending connections
210 * may grow to.
211 */
212RTR3DECL(int) RTTcpListen(RTSOCKET Sock, int cBackLog);
213
214/**
215 * Accept a connection on a socket.
216 *
217 * @returns iprt status code.
218 * @param Sock Socket descriptor.
219 * @param uPort The port for accepting connection.
220 * @param pSockAccepted Where to store the handle to the accepted connection.
221 */
222RTR3DECL(int) RTTcpAccept(RTSOCKET Sock, unsigned uPort, PRTSOCKET pSockAccepted);
223
224#endif
225
226
227/** @} */
228RT_C_DECLS_END
229
230#endif
231
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette