VirtualBox

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

Last change on this file since 75155 was 69105, checked in by vboxsync, 7 years ago

include/iprt/: (C) year

  • 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-2017 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_udp_h
27#define ___iprt_udp_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/thread.h>
32#include <iprt/net.h>
33#include <iprt/sg.h>
34#include <iprt/socket.h>
35
36#ifdef IN_RING0
37# error "There are no RTFile APIs available Ring-0 Host Context!"
38#endif
39
40
41RT_C_DECLS_BEGIN
42
43/** @defgroup grp_rt_udp RTUdp - UDP/IP
44 * @ingroup grp_rt
45 * @{
46 */
47
48
49/**
50 * Handle incoming UDP datagrams.
51 *
52 * @returns iprt status code.
53 * @returns VERR_UDP_SERVER_STOP to terminate the server loop forcing
54 * the RTUdpCreateServer() call to return.
55 * @param Sock The socket on which the datagram needs to be received.
56 * @param pvUser User argument.
57 */
58typedef DECLCALLBACK(int) FNRTUDPSERVE(RTSOCKET Sock, void *pvUser);
59/** Pointer to a RTUDPSERVE(). */
60typedef FNRTUDPSERVE *PFNRTUDPSERVE;
61
62/**
63 * Create single datagram at a time UDP Server in a separate thread.
64 *
65 * The thread will loop accepting datagrams and call pfnServe for
66 * each of the incoming datagrams in turn. The pfnServe function can
67 * return VERR_UDP_SERVER_STOP too terminate this loop. RTUdpServerDestroy()
68 * should be used to terminate the server.
69 *
70 * @returns iprt status code.
71 * @param pszAddress The address for creating a datagram socket.
72 * If NULL or empty string the server is bound to all interfaces.
73 * @param uPort The port for creating a datagram socket.
74 * @param enmType The thread type.
75 * @param pszThrdName The name of the worker thread.
76 * @param pfnServe The function which will handle incoming datagrams.
77 * @param pvUser User argument passed to pfnServe.
78 * @param ppServer Where to store the serverhandle.
79 */
80RTR3DECL(int) RTUdpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
81 PFNRTUDPSERVE pfnServe, void *pvUser, PPRTUDPSERVER ppServer);
82
83/**
84 * Create single datagram at a time UDP Server.
85 * The caller must call RTUdpServerReceive() to actually start the server.
86 *
87 * @returns iprt status code.
88 * @param pszAddress The address for creating a datagram socket.
89 * If NULL the server is bound to all interfaces.
90 * @param uPort The port for creating a datagram socket.
91 * @param ppServer Where to store the serverhandle.
92 */
93RTR3DECL(int) RTUdpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTUDPSERVER ppServer);
94
95/**
96 * Shuts down the server.
97 *
98 * @returns IPRT status code.
99 * @param pServer Handle to the server.
100 */
101RTR3DECL(int) RTUdpServerShutdown(PRTUDPSERVER pServer);
102
103/**
104 * Closes down and frees a UDP Server.
105 *
106 * @returns iprt status code.
107 * @param pServer Handle to the server.
108 */
109RTR3DECL(int) RTUdpServerDestroy(PRTUDPSERVER pServer);
110
111/**
112 * Listen for incoming datagrams.
113 *
114 * The function will loop waiting for datagrams and call pfnServe for
115 * each of the incoming datagrams in turn. The pfnServe function can
116 * return VERR_UDP_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 RTUdpServerCreateEx().
121 * @param pfnServe The function which will handle incoming datagrams.
122 * @param pvUser User argument passed to pfnServe.
123 */
124RTR3DECL(int) RTUdpServerListen(PRTUDPSERVER pServer, PFNRTUDPSERVE pfnServe, void *pvUser);
125
126/**
127 * Receive data from a socket.
128 *
129 * @returns iprt status code.
130 * @param Sock Socket descriptor.
131 * @param pvBuffer Where to put the data we read.
132 * @param cbBuffer Read buffer size.
133 * @param pcbRead Number of bytes read. Must be non-NULL.
134 * @param pSrcAddr The network address to read from.
135 */
136RTR3DECL(int) RTUdpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead, PRTNETADDR pSrcAddr);
137
138/**
139 * Send data to a socket.
140 *
141 * @returns iprt status code.
142 * @retval VERR_INTERRUPTED if interrupted before anything was written.
143 *
144 * @param pServer Handle to the server.
145 * @param pvBuffer Buffer to write data to socket.
146 * @param cbBuffer How much to write.
147 * @param pDstAddr Destination address.
148 */
149RTR3DECL(int) RTUdpWrite(PRTUDPSERVER pServer, const void *pvBuffer,
150 size_t cbBuffer, PCRTNETADDR pDstAddr);
151
152/**
153 * Create and connect a data socket.
154 *
155 * @returns iprt status code.
156 * @param pszAddress The address to connect to.
157 * @param uPort The port to connect to.
158 * @param pLocalAddr The local address to bind this socket to, can be
159 * NULL.
160 * @param pSock Where to store the handle to the established connection.
161 */
162RTR3DECL(int) RTUdpCreateClientSocket(const char *pszAddress, uint32_t uPort, PRTNETADDR pLocalAddr, PRTSOCKET pSock);
163
164/** @} */
165RT_C_DECLS_END
166
167#endif
168
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