[1] | 1 | /** @file
|
---|
[37196] | 2 | * IPRT - UDP/IP.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[76553] | 6 | * Copyright (C) 2006-2019 Oracle Corporation
|
---|
[1] | 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
|
---|
[5999] | 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.
|
---|
[1] | 24 | */
|
---|
| 25 |
|
---|
[76557] | 26 | #ifndef IPRT_INCLUDED_udp_h
|
---|
| 27 | #define IPRT_INCLUDED_udp_h
|
---|
[76507] | 28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 29 | # pragma once
|
---|
| 30 | #endif
|
---|
[1] | 31 |
|
---|
| 32 | #include <iprt/cdefs.h>
|
---|
| 33 | #include <iprt/types.h>
|
---|
| 34 | #include <iprt/thread.h>
|
---|
[26588] | 35 | #include <iprt/net.h>
|
---|
[30270] | 36 | #include <iprt/sg.h>
|
---|
[32276] | 37 | #include <iprt/socket.h>
|
---|
[1] | 38 |
|
---|
| 39 | #ifdef IN_RING0
|
---|
| 40 | # error "There are no RTFile APIs available Ring-0 Host Context!"
|
---|
| 41 | #endif
|
---|
| 42 |
|
---|
| 43 |
|
---|
[20374] | 44 | RT_C_DECLS_BEGIN
|
---|
[1] | 45 |
|
---|
[37196] | 46 | /** @defgroup grp_rt_udp RTUdp - UDP/IP
|
---|
[1] | 47 | * @ingroup grp_rt
|
---|
| 48 | * @{
|
---|
| 49 | */
|
---|
| 50 |
|
---|
| 51 |
|
---|
| 52 | /**
|
---|
[37196] | 53 | * Handle incoming UDP datagrams.
|
---|
[1] | 54 | *
|
---|
| 55 | * @returns iprt status code.
|
---|
[37196] | 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.
|
---|
[1] | 59 | * @param pvUser User argument.
|
---|
| 60 | */
|
---|
[37196] | 61 | typedef DECLCALLBACK(int) FNRTUDPSERVE(RTSOCKET Sock, void *pvUser);
|
---|
| 62 | /** Pointer to a RTUDPSERVE(). */
|
---|
| 63 | typedef FNRTUDPSERVE *PFNRTUDPSERVE;
|
---|
[1] | 64 |
|
---|
| 65 | /**
|
---|
[37196] | 66 | * Create single datagram at a time UDP Server in a separate thread.
|
---|
[1] | 67 | *
|
---|
[37196] | 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()
|
---|
[1] | 71 | * should be used to terminate the server.
|
---|
| 72 | *
|
---|
| 73 | * @returns iprt status code.
|
---|
[37196] | 74 | * @param pszAddress The address for creating a datagram socket.
|
---|
[1] | 75 | * If NULL or empty string the server is bound to all interfaces.
|
---|
[37196] | 76 | * @param uPort The port for creating a datagram socket.
|
---|
[1] | 77 | * @param enmType The thread type.
|
---|
| 78 | * @param pszThrdName The name of the worker thread.
|
---|
[37196] | 79 | * @param pfnServe The function which will handle incoming datagrams.
|
---|
[1] | 80 | * @param pvUser User argument passed to pfnServe.
|
---|
| 81 | * @param ppServer Where to store the serverhandle.
|
---|
| 82 | */
|
---|
[37196] | 83 | RTR3DECL(int) RTUdpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
|
---|
| 84 | PFNRTUDPSERVE pfnServe, void *pvUser, PPRTUDPSERVER ppServer);
|
---|
[1] | 85 |
|
---|
| 86 | /**
|
---|
[37196] | 87 | * Create single datagram at a time UDP Server.
|
---|
| 88 | * The caller must call RTUdpServerReceive() to actually start the server.
|
---|
[1] | 89 | *
|
---|
| 90 | * @returns iprt status code.
|
---|
[37196] | 91 | * @param pszAddress The address for creating a datagram socket.
|
---|
[1] | 92 | * If NULL the server is bound to all interfaces.
|
---|
[37196] | 93 | * @param uPort The port for creating a datagram socket.
|
---|
[1] | 94 | * @param ppServer Where to store the serverhandle.
|
---|
| 95 | */
|
---|
[37196] | 96 | RTR3DECL(int) RTUdpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTUDPSERVER ppServer);
|
---|
[1] | 97 |
|
---|
| 98 | /**
|
---|
[37196] | 99 | * Shuts down the server.
|
---|
[1] | 100 | *
|
---|
[37196] | 101 | * @returns IPRT status code.
|
---|
[1] | 102 | * @param pServer Handle to the server.
|
---|
| 103 | */
|
---|
[37196] | 104 | RTR3DECL(int) RTUdpServerShutdown(PRTUDPSERVER pServer);
|
---|
[1] | 105 |
|
---|
| 106 | /**
|
---|
[37196] | 107 | * Closes down and frees a UDP Server.
|
---|
[1] | 108 | *
|
---|
| 109 | * @returns iprt status code.
|
---|
[932] | 110 | * @param pServer Handle to the server.
|
---|
| 111 | */
|
---|
[37196] | 112 | RTR3DECL(int) RTUdpServerDestroy(PRTUDPSERVER pServer);
|
---|
[932] | 113 |
|
---|
| 114 | /**
|
---|
[37196] | 115 | * Listen for incoming datagrams.
|
---|
[27787] | 116 | *
|
---|
[37196] | 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.
|
---|
[23625] | 121 | *
|
---|
[1] | 122 | * @returns iprt status code.
|
---|
[37196] | 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.
|
---|
[1] | 126 | */
|
---|
[37196] | 127 | RTR3DECL(int) RTUdpServerListen(PRTUDPSERVER pServer, PFNRTUDPSERVE pfnServe, void *pvUser);
|
---|
[1] | 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.
|
---|
[37196] | 136 | * @param pcbRead Number of bytes read. Must be non-NULL.
|
---|
[57944] | 137 | * @param pSrcAddr The network address to read from.
|
---|
[1] | 138 | */
|
---|
[37196] | 139 | RTR3DECL(int) RTUdpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead, PRTNETADDR pSrcAddr);
|
---|
[1] | 140 |
|
---|
| 141 | /**
|
---|
[27497] | 142 | * Send data to a socket.
|
---|
[1] | 143 | *
|
---|
| 144 | * @returns iprt status code.
|
---|
[26683] | 145 | * @retval VERR_INTERRUPTED if interrupted before anything was written.
|
---|
| 146 | *
|
---|
[37196] | 147 | * @param pServer Handle to the server.
|
---|
[1] | 148 | * @param pvBuffer Buffer to write data to socket.
|
---|
| 149 | * @param cbBuffer How much to write.
|
---|
[37196] | 150 | * @param pDstAddr Destination address.
|
---|
[1] | 151 | */
|
---|
[37196] | 152 | RTR3DECL(int) RTUdpWrite(PRTUDPSERVER pServer, const void *pvBuffer,
|
---|
| 153 | size_t cbBuffer, PCRTNETADDR pDstAddr);
|
---|
[1] | 154 |
|
---|
[57955] | 155 | /**
|
---|
| 156 | * Create and connect a data socket.
|
---|
| 157 | *
|
---|
| 158 | * @returns iprt status code.
|
---|
[57957] | 159 | * @param pszAddress The address to connect to.
|
---|
| 160 | * @param uPort The port to connect to.
|
---|
[57970] | 161 | * @param pLocalAddr The local address to bind this socket to, can be
|
---|
| 162 | * NULL.
|
---|
[57957] | 163 | * @param pSock Where to store the handle to the established connection.
|
---|
[57955] | 164 | */
|
---|
[57970] | 165 | RTR3DECL(int) RTUdpCreateClientSocket(const char *pszAddress, uint32_t uPort, PRTNETADDR pLocalAddr, PRTSOCKET pSock);
|
---|
[57955] | 166 |
|
---|
[1] | 167 | /** @} */
|
---|
[20374] | 168 | RT_C_DECLS_END
|
---|
[1] | 169 |
|
---|
[76585] | 170 | #endif /* !IPRT_INCLUDED_udp_h */
|
---|
[1] | 171 |
|
---|