VirtualBox

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

Last change on this file since 87623 was 85121, checked in by vboxsync, 4 years ago

iprt/cdefs.h: Refactored the typedef use of DECLCALLBACK as well as DECLCALLBACKMEMBER to wrap the whole expression, similar to the DECLR?CALLBACKMEMBER macros. This allows adding a throw() at the end when compiling with the VC++ compiler to indicate that the callbacks won't throw anything, so we can stop supressing the C5039 warning about passing functions that can potential throw C++ exceptions to extern C code that can't necessarily cope with such (unwind,++). Introduced a few _EX variations that allows specifying different/no calling convention too, as that's handy when dynamically resolving host APIs. Fixed numerous places missing DECLCALLBACK and such. Left two angry @todos regarding use of CreateThread. bugref:9794

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.9 KB
Line 
1/** @file
2 * IPRT - UDP/IP.
3 */
4
5/*
6 * Copyright (C) 2006-2020 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_udp_h
27#define IPRT_INCLUDED_udp_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_udp RTUdp - UDP/IP
47 * @ingroup grp_rt
48 * @{
49 */
50
51
52/**
53 * Handle incoming UDP datagrams.
54 *
55 * @returns iprt status code.
56 * @returns VERR_UDP_SERVER_STOP to terminate the server loop forcing
57 * the RTUdpCreateServer() call to return.
58 * @param Sock The socket on which the datagram needs to be received.
59 * @param pvUser User argument.
60 */
61typedef DECLCALLBACKTYPE(int, FNRTUDPSERVE,(RTSOCKET Sock, void *pvUser));
62/** Pointer to a RTUDPSERVE(). */
63typedef FNRTUDPSERVE *PFNRTUDPSERVE;
64
65/**
66 * Create single datagram at a time UDP Server in a separate thread.
67 *
68 * The thread will loop accepting datagrams and call pfnServe for
69 * each of the incoming datagrams in turn. The pfnServe function can
70 * return VERR_UDP_SERVER_STOP too terminate this loop. RTUdpServerDestroy()
71 * should be used to terminate the server.
72 *
73 * @returns iprt status code.
74 * @param pszAddress The address for creating a datagram socket.
75 * If NULL or empty string the server is bound to all interfaces.
76 * @param uPort The port for creating a datagram socket.
77 * @param enmType The thread type.
78 * @param pszThrdName The name of the worker thread.
79 * @param pfnServe The function which will handle incoming datagrams.
80 * @param pvUser User argument passed to pfnServe.
81 * @param ppServer Where to store the serverhandle.
82 */
83RTR3DECL(int) RTUdpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
84 PFNRTUDPSERVE pfnServe, void *pvUser, PPRTUDPSERVER ppServer);
85
86/**
87 * Create single datagram at a time UDP Server.
88 * The caller must call RTUdpServerReceive() to actually start the server.
89 *
90 * @returns iprt status code.
91 * @param pszAddress The address for creating a datagram socket.
92 * If NULL the server is bound to all interfaces.
93 * @param uPort The port for creating a datagram socket.
94 * @param ppServer Where to store the serverhandle.
95 */
96RTR3DECL(int) RTUdpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTUDPSERVER ppServer);
97
98/**
99 * Shuts down the server.
100 *
101 * @returns IPRT status code.
102 * @param pServer Handle to the server.
103 */
104RTR3DECL(int) RTUdpServerShutdown(PRTUDPSERVER pServer);
105
106/**
107 * Closes down and frees a UDP Server.
108 *
109 * @returns iprt status code.
110 * @param pServer Handle to the server.
111 */
112RTR3DECL(int) RTUdpServerDestroy(PRTUDPSERVER pServer);
113
114/**
115 * Listen for incoming datagrams.
116 *
117 * The function will loop waiting for datagrams and call pfnServe for
118 * each of the incoming datagrams in turn. The pfnServe function can
119 * return VERR_UDP_SERVER_STOP too terminate this loop. A stopped server
120 * can only be destroyed.
121 *
122 * @returns iprt status code.
123 * @param pServer The server handle as returned from RTUdpServerCreateEx().
124 * @param pfnServe The function which will handle incoming datagrams.
125 * @param pvUser User argument passed to pfnServe.
126 */
127RTR3DECL(int) RTUdpServerListen(PRTUDPSERVER pServer, PFNRTUDPSERVE pfnServe, void *pvUser);
128
129/**
130 * Receive data from a socket.
131 *
132 * @returns iprt status code.
133 * @param Sock Socket descriptor.
134 * @param pvBuffer Where to put the data we read.
135 * @param cbBuffer Read buffer size.
136 * @param pcbRead Number of bytes read. Must be non-NULL.
137 * @param pSrcAddr The network address to read from.
138 */
139RTR3DECL(int) RTUdpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead, PRTNETADDR pSrcAddr);
140
141/**
142 * Send data to a socket.
143 *
144 * @returns iprt status code.
145 * @retval VERR_INTERRUPTED if interrupted before anything was written.
146 *
147 * @param pServer Handle to the server.
148 * @param pvBuffer Buffer to write data to socket.
149 * @param cbBuffer How much to write.
150 * @param pDstAddr Destination address.
151 */
152RTR3DECL(int) RTUdpWrite(PRTUDPSERVER pServer, const void *pvBuffer,
153 size_t cbBuffer, PCRTNETADDR pDstAddr);
154
155/**
156 * Create and connect a data socket.
157 *
158 * @returns iprt status code.
159 * @param pszAddress The address to connect to.
160 * @param uPort The port to connect to.
161 * @param pLocalAddr The local address to bind this socket to, can be
162 * NULL.
163 * @param pSock Where to store the handle to the established connection.
164 */
165RTR3DECL(int) RTUdpCreateClientSocket(const char *pszAddress, uint32_t uPort, PRTNETADDR pLocalAddr, PRTSOCKET pSock);
166
167/** @} */
168RT_C_DECLS_END
169
170#endif /* !IPRT_INCLUDED_udp_h */
171
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