VirtualBox

source: vbox/trunk/include/iprt/udp.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 KB
Line 
1/** @file
2 * IPRT - UDP/IP.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_udp_h
37#define IPRT_INCLUDED_udp_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/thread.h>
45#include <iprt/net.h>
46#include <iprt/sg.h>
47#include <iprt/socket.h>
48
49#ifdef IN_RING0
50# error "There are no RTFile APIs available Ring-0 Host Context!"
51#endif
52
53
54RT_C_DECLS_BEGIN
55
56/** @defgroup grp_rt_udp RTUdp - UDP/IP
57 * @ingroup grp_rt
58 * @{
59 */
60
61
62/**
63 * Handle incoming UDP datagrams.
64 *
65 * @returns iprt status code.
66 * @returns VERR_UDP_SERVER_STOP to terminate the server loop forcing
67 * the RTUdpCreateServer() call to return.
68 * @param Sock The socket on which the datagram needs to be received.
69 * @param pvUser User argument.
70 */
71typedef DECLCALLBACKTYPE(int, FNRTUDPSERVE,(RTSOCKET Sock, void *pvUser));
72/** Pointer to a RTUDPSERVE(). */
73typedef FNRTUDPSERVE *PFNRTUDPSERVE;
74
75/**
76 * Create single datagram at a time UDP Server in a separate thread.
77 *
78 * The thread will loop accepting datagrams and call pfnServe for
79 * each of the incoming datagrams in turn. The pfnServe function can
80 * return VERR_UDP_SERVER_STOP too terminate this loop. RTUdpServerDestroy()
81 * should be used to terminate the server.
82 *
83 * @returns iprt status code.
84 * @param pszAddress The address for creating a datagram socket.
85 * If NULL or empty string the server is bound to all interfaces.
86 * @param uPort The port for creating a datagram socket.
87 * @param enmType The thread type.
88 * @param pszThrdName The name of the worker thread.
89 * @param pfnServe The function which will handle incoming datagrams.
90 * @param pvUser User argument passed to pfnServe.
91 * @param ppServer Where to store the serverhandle.
92 */
93RTR3DECL(int) RTUdpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
94 PFNRTUDPSERVE pfnServe, void *pvUser, PPRTUDPSERVER ppServer);
95
96/**
97 * Create single datagram at a time UDP Server.
98 * The caller must call RTUdpServerReceive() to actually start the server.
99 *
100 * @returns iprt status code.
101 * @param pszAddress The address for creating a datagram socket.
102 * If NULL the server is bound to all interfaces.
103 * @param uPort The port for creating a datagram socket.
104 * @param ppServer Where to store the serverhandle.
105 */
106RTR3DECL(int) RTUdpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTUDPSERVER ppServer);
107
108/**
109 * Shuts down the server.
110 *
111 * @returns IPRT status code.
112 * @param pServer Handle to the server.
113 */
114RTR3DECL(int) RTUdpServerShutdown(PRTUDPSERVER pServer);
115
116/**
117 * Closes down and frees a UDP Server.
118 *
119 * @returns iprt status code.
120 * @param pServer Handle to the server.
121 */
122RTR3DECL(int) RTUdpServerDestroy(PRTUDPSERVER pServer);
123
124/**
125 * Listen for incoming datagrams.
126 *
127 * The function will loop waiting for datagrams and call pfnServe for
128 * each of the incoming datagrams in turn. The pfnServe function can
129 * return VERR_UDP_SERVER_STOP too terminate this loop. A stopped server
130 * can only be destroyed.
131 *
132 * @returns iprt status code.
133 * @param pServer The server handle as returned from RTUdpServerCreateEx().
134 * @param pfnServe The function which will handle incoming datagrams.
135 * @param pvUser User argument passed to pfnServe.
136 */
137RTR3DECL(int) RTUdpServerListen(PRTUDPSERVER pServer, PFNRTUDPSERVE pfnServe, void *pvUser);
138
139/**
140 * Receive data from a socket.
141 *
142 * @returns iprt status code.
143 * @param Sock Socket descriptor.
144 * @param pvBuffer Where to put the data we read.
145 * @param cbBuffer Read buffer size.
146 * @param pcbRead Number of bytes read. Must be non-NULL.
147 * @param pSrcAddr The network address to read from.
148 */
149RTR3DECL(int) RTUdpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead, PRTNETADDR pSrcAddr);
150
151/**
152 * Send data to a socket.
153 *
154 * @returns iprt status code.
155 * @retval VERR_INTERRUPTED if interrupted before anything was written.
156 *
157 * @param pServer Handle to the server.
158 * @param pvBuffer Buffer to write data to socket.
159 * @param cbBuffer How much to write.
160 * @param pDstAddr Destination address.
161 */
162RTR3DECL(int) RTUdpWrite(PRTUDPSERVER pServer, const void *pvBuffer,
163 size_t cbBuffer, PCRTNETADDR pDstAddr);
164
165/**
166 * Create and connect a data socket.
167 *
168 * @returns iprt status code.
169 * @param pszAddress The address to connect to.
170 * @param uPort The port to connect to.
171 * @param pLocalAddr The local address to bind this socket to, can be
172 * NULL.
173 * @param pSock Where to store the handle to the established connection.
174 */
175RTR3DECL(int) RTUdpCreateClientSocket(const char *pszAddress, uint32_t uPort, PRTNETADDR pLocalAddr, PRTSOCKET pSock);
176
177/**
178 * Create a data socket acting as a server.
179 *
180 * @returns iprt status code.
181 * @param pszAddress The address to connect to.
182 * @param uPort The port to connect to.
183 * @param pSock Where to store the handle to the established connection.
184 */
185RTR3DECL(int) RTUdpCreateServerSocket(const char *pszAddress, uint32_t uPort, PRTSOCKET pSock);
186
187/** @} */
188RT_C_DECLS_END
189
190#endif /* !IPRT_INCLUDED_udp_h */
191
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