VirtualBox

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

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.9 KB
Line 
1/** @file
2 * IPRT - TCP/IP.
3 */
4
5/*
6 * Copyright (C) 2006-2019 Oracle Corporation
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
26#ifndef IPRT_INCLUDED_tcp_h
27#define IPRT_INCLUDED_tcp_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34#include <iprt/thread.h>
35#include <iprt/net.h>
36#include <iprt/sg.h>
37#include <iprt/socket.h>
38
39#ifdef IN_RING0
40# error "There are no RTFile APIs available Ring-0 Host Context!"
41#endif
42
43
44RT_C_DECLS_BEGIN
45
46/** @defgroup grp_rt_tcp RTTcp - TCP/IP
47 * @ingroup grp_rt
48 * @{
49 */
50
51
52/**
53 * Serve a TCP Server connection.
54 *
55 * @returns iprt status code.
56 * @returns VERR_TCP_SERVER_STOP to terminate the server loop forcing
57 * the RTTcpCreateServer() call to return.
58 * @param hSocket The socket which the client is connected to. The call
59 * will close this socket.
60 * @param pvUser User argument.
61 */
62typedef DECLCALLBACK(int) FNRTTCPSERVE(RTSOCKET hSocket, void *pvUser);
63/** Pointer to a RTTCPSERVE(). */
64typedef FNRTTCPSERVE *PFNRTTCPSERVE;
65
66/**
67 * Create single connection at a time TCP Server in a separate thread.
68 *
69 * The thread will loop accepting connections and call pfnServe for
70 * each of the incoming connections in turn. The pfnServe function can
71 * return VERR_TCP_SERVER_STOP too terminate this loop. RTTcpServerDestroy()
72 * should be used to terminate the server.
73 *
74 * @returns iprt status code.
75 * @param pszAddress The address for creating a listening socket.
76 * If NULL or empty string the server is bound to all interfaces.
77 * @param uPort The port for creating a listening socket.
78 * @param enmType The thread type.
79 * @param pszThrdName The name of the worker thread.
80 * @param pfnServe The function which will serve a new client connection.
81 * @param pvUser User argument passed to pfnServe.
82 * @param ppServer Where to store the serverhandle.
83 */
84RTR3DECL(int) RTTcpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
85 PFNRTTCPSERVE pfnServe, void *pvUser, PPRTTCPSERVER ppServer);
86
87/**
88 * Create single connection at a time TCP Server.
89 * The caller must call RTTcpServerListen() to actually start the server.
90 *
91 * @returns iprt status code.
92 * @param pszAddress The address for creating a listening socket.
93 * If NULL the server is bound to all interfaces.
94 * @param uPort The port for creating a listening socket.
95 * @param ppServer Where to store the serverhandle.
96 */
97RTR3DECL(int) RTTcpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTTCPSERVER ppServer);
98
99/**
100 * Closes down and frees a TCP Server.
101 * This will also terminate any open connections to the server.
102 *
103 * @returns iprt status code.
104 * @param pServer Handle to the server.
105 */
106RTR3DECL(int) RTTcpServerDestroy(PRTTCPSERVER pServer);
107
108/**
109 * Listen for incoming connections.
110 *
111 * The function will loop accepting connections and call pfnServe for
112 * each of the incoming connections in turn. The pfnServe function can
113 * return VERR_TCP_SERVER_STOP too terminate this loop. A stopped server
114 * can only be destroyed.
115 *
116 * @returns iprt status code.
117 * @param pServer The server handle as returned from RTTcpServerCreateEx().
118 * @param pfnServe The function which will serve a new client connection.
119 * @param pvUser User argument passed to pfnServe.
120 */
121RTR3DECL(int) RTTcpServerListen(PRTTCPSERVER pServer, PFNRTTCPSERVE pfnServe, void *pvUser);
122
123/**
124 * Listen and accept one incoming connection.
125 *
126 * This is an alternative to RTTcpServerListen for the use the callbacks are not
127 * possible.
128 *
129 * @returns IPRT status code.
130 * @retval VERR_TCP_SERVER_SHUTDOWN if shut down by RTTcpServerShutdown.
131 * @retval VERR_INTERRUPTED if the listening was interrupted.
132 *
133 * @param pServer The server handle as returned from RTTcpServerCreateEx().
134 * @param phClientSocket Where to return the socket handle to the client
135 * connection (on success only). This must be closed
136 * by calling RTTcpServerDisconnectClient2().
137 */
138RTR3DECL(int) RTTcpServerListen2(PRTTCPSERVER pServer, PRTSOCKET phClientSocket);
139
140/**
141 * Terminate the open connection to the server.
142 *
143 * @returns iprt status code.
144 * @param pServer Handle to the server.
145 */
146RTR3DECL(int) RTTcpServerDisconnectClient(PRTTCPSERVER pServer);
147
148/**
149 * Terminates an open client connect when using RTTcpListen2
150 *
151 * @returns IPRT status code.
152 * @param hClientSocket The client socket handle. This will be invalid upon
153 * return, whether successful or not. NIL is quietly
154 * ignored (VINF_SUCCESS).
155 */
156RTR3DECL(int) RTTcpServerDisconnectClient2(RTSOCKET hClientSocket);
157
158/**
159 * Shuts down the server, leaving client connections open.
160 *
161 * @returns IPRT status code.
162 * @param pServer Handle to the server.
163 */
164RTR3DECL(int) RTTcpServerShutdown(PRTTCPSERVER pServer);
165
166/**
167 * Connect (as a client) to a TCP Server.
168 *
169 * @returns iprt status code.
170 * @param pszAddress The address to connect to.
171 * @param uPort The port to connect to.
172 * @param pSock Where to store the handle to the established connection.
173 */
174RTR3DECL(int) RTTcpClientConnect(const char *pszAddress, uint32_t uPort, PRTSOCKET pSock);
175
176/** Opaque pointer used by RTTcpClientConnectEx and RTTcpClientCancelConnect. */
177typedef struct RTTCPCLIENTCONNECTCANCEL *PRTTCPCLIENTCONNECTCANCEL;
178
179/**
180 * Connect (as a client) to a TCP Server, extended version.
181 *
182 * @returns iprt status code.
183 * @param pszAddress The address to connect to.
184 * @param uPort The port to connect to.
185 * @param pSock Where to store the handle to the established connection.
186 * @param cMillies Number of milliseconds to wait for the connect attempt to complete.
187 * Use RT_INDEFINITE_WAIT to wait for ever.
188 * Use RT_SOCKETCONNECT_DEFAULT_WAIT to wait for the default time
189 * configured on the running system.
190 * @param ppCancelCookie Where to store information for canceling the
191 * operation (from a different thread). Optional.
192 *
193 * The pointer _must_ be initialized to NULL before a
194 * series of connection attempts begins, i.e. at a time
195 * where there will be no RTTcpClientCancelConnect
196 * calls racing access. RTTcpClientCancelConnect will
197 * set it to a special non-NULL value that causes the
198 * current or/and next connect call to fail.
199 *
200 * @sa RTTcpClientCancelConnect
201 */
202RTR3DECL(int) RTTcpClientConnectEx(const char *pszAddress, uint32_t uPort, PRTSOCKET pSock,
203 RTMSINTERVAL cMillies, PRTTCPCLIENTCONNECTCANCEL volatile *ppCancelCookie);
204
205/**
206 * Cancels a RTTcpClientConnectEx call on a different thread.
207 *
208 * @returns iprt status code.
209 * @param ppCancelCookie The address of the cookie pointer shared with the
210 * connect call.
211 */
212RTR3DECL(int) RTTcpClientCancelConnect(PRTTCPCLIENTCONNECTCANCEL volatile *ppCancelCookie);
213
214/**
215 * Close a socket returned by RTTcpClientConnect().
216 *
217 * @returns iprt status code.
218 * @param hSocket Socket descriptor.
219 */
220RTR3DECL(int) RTTcpClientClose(RTSOCKET hSocket);
221
222/**
223 * Close a socket returned by RTTcpClientConnect().
224 *
225 * @returns iprt status code.
226 * @param hSocket The socket handle.
227 * @param fGracefulShutdown If true, try do a graceful shutdown of the
228 * outgoing pipe and draining any lingering input.
229 * This is sometimes better for the server side.
230 * If false, just close the connection without
231 * further ado.
232 */
233RTR3DECL(int) RTTcpClientCloseEx(RTSOCKET hSocket, bool fGracefulShutdown);
234
235/**
236 * Creates connected pair of TCP sockets.
237 *
238 * @returns IPRT status code.
239 * @param phServer Where to return the "server" side of the pair.
240 * @param phClient Where to return the "client" side of the pair.
241 * @param fFlags Reserved, must be zero.
242 *
243 * @note There is no server or client side, but we gotta call it something.
244 */
245RTR3DECL(int) RTTcpCreatePair(PRTSOCKET phServer, PRTSOCKET phClient, uint32_t fFlags);
246
247/**
248 * Receive data from a socket.
249 *
250 * @returns iprt status code.
251 * @param hSocket Socket descriptor.
252 * @param pvBuffer Where to put the data we read.
253 * @param cbBuffer Read buffer size.
254 * @param pcbRead Number of bytes read.
255 * If NULL the entire buffer will be filled upon successful return.
256 * If not NULL a partial read can be done successfully.
257 */
258RTR3DECL(int) RTTcpRead(RTSOCKET hSocket, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
259
260/**
261 * Send data to a socket.
262 *
263 * @returns iprt status code.
264 * @retval VERR_INTERRUPTED if interrupted before anything was written.
265 *
266 * @param hSocket Socket descriptor.
267 * @param pvBuffer Buffer to write data to socket.
268 * @param cbBuffer How much to write.
269 */
270RTR3DECL(int) RTTcpWrite(RTSOCKET hSocket, const void *pvBuffer, size_t cbBuffer);
271
272/**
273 * Flush socket write buffers.
274 *
275 * @returns iprt status code.
276 * @param hSocket Socket descriptor.
277 */
278RTR3DECL(int) RTTcpFlush(RTSOCKET hSocket);
279
280/**
281 * Enables or disables delaying sends to coalesce packets.
282 *
283 * The TCP/IP stack usually uses the Nagle algorithm (RFC 896) to implement the
284 * coalescing.
285 *
286 * @returns iprt status code.
287 * @param hSocket Socket descriptor.
288 * @param fEnable When set to true enables coalescing.
289 */
290RTR3DECL(int) RTTcpSetSendCoalescing(RTSOCKET hSocket, bool fEnable);
291
292/**
293 * Socket I/O multiplexing.
294 * Checks if the socket is ready for reading.
295 *
296 * @returns iprt status code.
297 * @param hSocket Socket descriptor.
298 * @param cMillies Number of milliseconds to wait for the socket.
299 * Use RT_INDEFINITE_WAIT to wait for ever.
300 */
301RTR3DECL(int) RTTcpSelectOne(RTSOCKET hSocket, RTMSINTERVAL cMillies);
302
303/**
304 * Socket I/O multiplexing
305 * Checks if the socket is ready for one of the given events.
306 *
307 * @returns iprt status code.
308 * @param hSocket Socket descriptor.
309 * @param fEvents Event mask to wait for.
310 * Use the RTSOCKET_EVT_* defines.
311 * @param pfEvents Where to store the event mask on return.
312 * @param cMillies Number of milliseconds to wait for the socket.
313 * Use RT_INDEFINITE_WAIT to wait for ever.
314 */
315RTR3DECL(int) RTTcpSelectOneEx(RTSOCKET hSocket, uint32_t fEvents, uint32_t *pfEvents, RTMSINTERVAL cMillies);
316
317#if 0 /* skipping these for now - RTTcpServer* handles this. */
318/**
319 * Listen for connection on a socket.
320 *
321 * @returns iprt status code.
322 * @param hSocket Socket descriptor.
323 * @param cBackLog The maximum length the queue of pending connections
324 * may grow to.
325 */
326RTR3DECL(int) RTTcpListen(RTSOCKET hSocket, int cBackLog);
327
328/**
329 * Accept a connection on a socket.
330 *
331 * @returns iprt status code.
332 * @param hSocket Socket descriptor.
333 * @param uPort The port for accepting connection.
334 * @param pSockAccepted Where to store the handle to the accepted connection.
335 */
336RTR3DECL(int) RTTcpAccept(RTSOCKET hSocket, unsigned uPort, PRTSOCKET pSockAccepted);
337
338#endif
339
340/**
341 * Gets the address of the local side.
342 *
343 * @returns IPRT status code.
344 * @param hSocket Socket descriptor.
345 * @param pAddr Where to store the local address on success.
346 */
347RTR3DECL(int) RTTcpGetLocalAddress(RTSOCKET hSocket, PRTNETADDR pAddr);
348
349/**
350 * Gets the address of the other party.
351 *
352 * @returns IPRT status code.
353 * @param hSocket Socket descriptor.
354 * @param pAddr Where to store the peer address on success.
355 */
356RTR3DECL(int) RTTcpGetPeerAddress(RTSOCKET hSocket, PRTNETADDR pAddr);
357
358/**
359 * Send data from a scatter/gather buffer to a socket.
360 *
361 * @returns iprt status code.
362 * @retval VERR_INTERRUPTED if interrupted before anything was written.
363 *
364 * @param hSocket Socket descriptor.
365 * @param pSgBuf Scatter/gather buffer to write data to socket.
366 */
367RTR3DECL(int) RTTcpSgWrite(RTSOCKET hSocket, PCRTSGBUF pSgBuf);
368
369
370/**
371 * Send data from multiple buffers to a socket.
372 *
373 * This is convenience wrapper around the RTSocketSgWrite and RTSgBufInit calls
374 * for lazy coders. The "L" in the function name is short for "list" just like
375 * in the execl libc API.
376 *
377 * @returns IPRT status code.
378 * @retval VERR_INTERRUPTED if interrupted before anything was written.
379 *
380 * @param hSocket The socket handle.
381 * @param cSegs The number of data segments in the following
382 * ellipsis.
383 * @param ... Pairs of buffer pointers (void const *) and buffer
384 * sizes (size_t). Make 101% sure the pointer is
385 * really size_t.
386 */
387RTR3DECL(int) RTTcpSgWriteL(RTSOCKET hSocket, size_t cSegs, ...);
388
389/**
390 * Send data from multiple buffers to a socket.
391 *
392 * This is convenience wrapper around the RTSocketSgWrite and RTSgBufInit calls
393 * for lazy coders. The "L" in the function name is short for "list" just like
394 * in the execl libc API.
395 *
396 * @returns IPRT status code.
397 * @retval VERR_INTERRUPTED if interrupted before anything was written.
398 *
399 * @param hSocket The socket handle.
400 * @param cSegs The number of data segments in the following
401 * argument list.
402 * @param va Pairs of buffer pointers (void const *) and buffer
403 * sizes (size_t). Make 101% sure the pointer is
404 * really size_t.
405 */
406RTR3DECL(int) RTTcpSgWriteLV(RTSOCKET hSocket, size_t cSegs, va_list va);
407
408/**
409 * Receive data from a socket.
410 *
411 * This version doesn't block if there is no data on the socket.
412 *
413 * @returns IPRT status code.
414 *
415 * @param hSocket Socket descriptor.
416 * @param pvBuffer Where to put the data we read.
417 * @param cbBuffer Read buffer size.
418 * @param pcbRead Number of bytes read.
419 */
420RTR3DECL(int) RTTcpReadNB(RTSOCKET hSocket, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
421
422/**
423 * Send data to a socket.
424 *
425 * This version doesn't block if there is not enough room for the message.
426 *
427 * @returns IPRT status code.
428 *
429 * @param hSocket Socket descriptor.
430 * @param pvBuffer Buffer to write data to socket.
431 * @param cbBuffer How much to write.
432 * @param pcbWritten Number of bytes written.
433 */
434RTR3DECL(int) RTTcpWriteNB(RTSOCKET hSocket, const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten);
435
436/**
437 * Send data from a scatter/gather buffer to a socket.
438 *
439 * This version doesn't block if there is not enough room for the message.
440 *
441 * @returns iprt status code.
442 * @retval VERR_INTERRUPTED if interrupted before anything was written.
443 *
444 * @param hSocket Socket descriptor.
445 * @param pSgBuf Scatter/gather buffer to write data to socket.
446 * @param pcbWritten Number of bytes written.
447 */
448RTR3DECL(int) RTTcpSgWriteNB(RTSOCKET hSocket, PCRTSGBUF pSgBuf, size_t *pcbWritten);
449
450
451/**
452 * Send data from multiple buffers to a socket.
453 *
454 * This version doesn't block if there is not enough room for the message.
455 * This is convenience wrapper around the RTSocketSgWrite and RTSgBufInit calls
456 * for lazy coders. The "L" in the function name is short for "list" just like
457 * in the execl libc API.
458 *
459 * @returns IPRT status code.
460 *
461 * @param hSocket The socket handle.
462 * @param cSegs The number of data segments in the following
463 * ellipsis.
464 * @param pcbWritten Number of bytes written.
465 * @param ... Pairs of buffer pointers (void const *) and buffer
466 * sizes (size_t). Make 101% sure the pointer is
467 * really size_t.
468 */
469RTR3DECL(int) RTTcpSgWriteLNB(RTSOCKET hSocket, size_t cSegs, size_t *pcbWritten, ...);
470
471/**
472 * Send data from multiple buffers to a socket.
473 *
474 * This version doesn't block if there is not enough room for the message.
475 * This is convenience wrapper around the RTSocketSgWrite and RTSgBufInit calls
476 * for lazy coders. The "L" in the function name is short for "list" just like
477 * in the execl libc API.
478 *
479 * @returns IPRT status code.
480 *
481 * @param hSocket The socket handle.
482 * @param cSegs The number of data segments in the following
483 * argument list.
484 * @param pcbWritten Number of bytes written.
485 * @param va Pairs of buffer pointers (void const *) and buffer
486 * sizes (size_t). Make 101% sure the pointer is
487 * really size_t.
488 */
489RTR3DECL(int) RTTcpSgWriteLVNB(RTSOCKET hSocket, size_t cSegs, size_t *pcbWritten, va_list va);
490
491/** @} */
492RT_C_DECLS_END
493
494#endif /* !IPRT_INCLUDED_tcp_h */
495
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use