| 1 | /* $Id: AudioTestService.h 98103 2023-01-17 14:15:46Z vboxsync $ */
|
|---|
| 2 | /** @file
|
|---|
| 3 | * AudioTestService - Audio test execution server, Public Header.
|
|---|
| 4 | */
|
|---|
| 5 |
|
|---|
| 6 | /*
|
|---|
| 7 | * Copyright (C) 2021-2023 Oracle and/or its affiliates.
|
|---|
| 8 | *
|
|---|
| 9 | * This file is part of VirtualBox base platform packages, as
|
|---|
| 10 | * available from https://www.virtualbox.org.
|
|---|
| 11 | *
|
|---|
| 12 | * This program is free software; you can redistribute it and/or
|
|---|
| 13 | * modify it under the terms of the GNU General Public License
|
|---|
| 14 | * as published by the Free Software Foundation, in version 3 of the
|
|---|
| 15 | * License.
|
|---|
| 16 | *
|
|---|
| 17 | * This program is distributed in the hope that it will be useful, but
|
|---|
| 18 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
|---|
| 19 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|---|
| 20 | * General Public License for more details.
|
|---|
| 21 | *
|
|---|
| 22 | * You should have received a copy of the GNU General Public License
|
|---|
| 23 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
|---|
| 24 | *
|
|---|
| 25 | * SPDX-License-Identifier: GPL-3.0-only
|
|---|
| 26 | */
|
|---|
| 27 |
|
|---|
| 28 | #ifndef VBOX_INCLUDED_SRC_Audio_AudioTestService_h
|
|---|
| 29 | #define VBOX_INCLUDED_SRC_Audio_AudioTestService_h
|
|---|
| 30 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
|---|
| 31 | # pragma once
|
|---|
| 32 | #endif
|
|---|
| 33 |
|
|---|
| 34 | #include <iprt/tcp.h>
|
|---|
| 35 |
|
|---|
| 36 | #include "AudioTestServiceInternal.h"
|
|---|
| 37 |
|
|---|
| 38 | extern const PCATSTRANSPORT g_apTransports[];
|
|---|
| 39 | extern const size_t g_cTransports;
|
|---|
| 40 |
|
|---|
| 41 | /** Default TCP/IP bind port the guest ATS (Audio Test Service) is listening on. */
|
|---|
| 42 | #define ATS_TCP_DEF_BIND_PORT_GUEST 6042
|
|---|
| 43 | /** Default TCP/IP bind port the host ATS is listening on. */
|
|---|
| 44 | #define ATS_TCP_DEF_BIND_PORT_HOST 6052
|
|---|
| 45 | /** Default TCP/IP ATS bind port the ValidationKit Audio Driver ATS is listening on. */
|
|---|
| 46 | #define ATS_TCP_DEF_BIND_PORT_VALKIT 6062
|
|---|
| 47 | /** Default TCP/IP port the guest ATS is connecting to. */
|
|---|
| 48 | #define ATS_TCP_DEF_CONNECT_PORT_GUEST ATS_TCP_DEF_BIND_PORT_HOST
|
|---|
| 49 | /** Default TCP/IP port the host ATS is connecting to the guest (needs NAT port forwarding). */
|
|---|
| 50 | #define ATS_TCP_DEF_CONNECT_PORT_HOST_PORT_FWD 6072
|
|---|
| 51 | /** Default TCP/IP port the host ATS is connecting to. */
|
|---|
| 52 | #define ATS_TCP_DEF_CONNECT_PORT_VALKIT ATS_TCP_DEF_BIND_PORT_VALKIT
|
|---|
| 53 | /** Default TCP/IP address the host is connecting to. */
|
|---|
| 54 | #define ATS_TCP_DEF_CONNECT_HOST_ADDR_STR "127.0.0.1"
|
|---|
| 55 | /** Default TCP/IP address the guest ATS connects to when
|
|---|
| 56 | * running in client mode (reversed mode, needed for NATed VMs). */
|
|---|
| 57 | #define ATS_TCP_DEF_CONNECT_GUEST_STR "10.0.2.2"
|
|---|
| 58 |
|
|---|
| 59 | /**
|
|---|
| 60 | * Structure for keeping an Audio Test Service (ATS) callback table.
|
|---|
| 61 | */
|
|---|
| 62 | typedef struct ATSCALLBACKS
|
|---|
| 63 | {
|
|---|
| 64 | /**
|
|---|
| 65 | * Tells the implementation that a new client connected. Optional.
|
|---|
| 66 | *
|
|---|
| 67 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 68 | */
|
|---|
| 69 | DECLR3CALLBACKMEMBER(int, pfnHowdy, (void const *pvUser));
|
|---|
| 70 |
|
|---|
| 71 | /**
|
|---|
| 72 | * Tells the implementation that a client disconnected. Optional.
|
|---|
| 73 | *
|
|---|
| 74 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 75 | */
|
|---|
| 76 | DECLR3CALLBACKMEMBER(int, pfnBye, (void const *pvUser));
|
|---|
| 77 |
|
|---|
| 78 | /**
|
|---|
| 79 | * Begins a test set. Optional.
|
|---|
| 80 | *
|
|---|
| 81 | * @returns VBox status code.
|
|---|
| 82 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 83 | * @param pszTag Tag of test set to begin.
|
|---|
| 84 | */
|
|---|
| 85 | DECLR3CALLBACKMEMBER(int, pfnTestSetBegin, (void const *pvUser, const char *pszTag));
|
|---|
| 86 |
|
|---|
| 87 | /**
|
|---|
| 88 | * Ends the current test set. Optional.
|
|---|
| 89 | *
|
|---|
| 90 | * @returns VBox status code.
|
|---|
| 91 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 92 | * @param pszTag Tag of test set to end.
|
|---|
| 93 | */
|
|---|
| 94 | DECLR3CALLBACKMEMBER(int, pfnTestSetEnd, (void const *pvUser, const char *pszTag));
|
|---|
| 95 |
|
|---|
| 96 | /**
|
|---|
| 97 | * Marks the begin of sending a test set. Optional.
|
|---|
| 98 | *
|
|---|
| 99 | * @returns VBox status code.
|
|---|
| 100 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 101 | * @param pszTag Tag of test set to begin sending.
|
|---|
| 102 | */
|
|---|
| 103 | DECLR3CALLBACKMEMBER(int, pfnTestSetSendBegin, (void const *pvUser, const char *pszTag));
|
|---|
| 104 |
|
|---|
| 105 | /**
|
|---|
| 106 | * Reads data from a test set for sending it.
|
|---|
| 107 | *
|
|---|
| 108 | * @returns VBox status code.
|
|---|
| 109 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 110 | * @param pszTag Tag of test set to begin sending.
|
|---|
| 111 | * @param pvBuf Where to store the read test set data.
|
|---|
| 112 | * @param cbBuf Size of \a pvBuf (in bytes).
|
|---|
| 113 | * @param pcbRead Where to return the amount of read data in bytes. Optional and can be NULL.
|
|---|
| 114 | */
|
|---|
| 115 | DECLR3CALLBACKMEMBER(int, pfnTestSetSendRead, (void const *pvUser, const char *pszTag, void *pvBuf, size_t cbBuf, size_t *pcbRead));
|
|---|
| 116 |
|
|---|
| 117 | /**
|
|---|
| 118 | * Marks the end of sending a test set. Optional.
|
|---|
| 119 | *
|
|---|
| 120 | * @returns VBox status code.
|
|---|
| 121 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 122 | * @param pszTag Tag of test set to end sending.
|
|---|
| 123 | */
|
|---|
| 124 | DECLR3CALLBACKMEMBER(int, pfnTestSetSendEnd, (void const *pvUser, const char *pszTag));
|
|---|
| 125 |
|
|---|
| 126 | /**
|
|---|
| 127 | * Plays a test tone.
|
|---|
| 128 | *
|
|---|
| 129 | * @returns VBox status code.
|
|---|
| 130 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 131 | * @param pToneParms Tone parameters to use for playback.
|
|---|
| 132 | */
|
|---|
| 133 | DECLR3CALLBACKMEMBER(int, pfnTonePlay, (void const *pvUser, PAUDIOTESTTONEPARMS pToneParms));
|
|---|
| 134 |
|
|---|
| 135 | /**
|
|---|
| 136 | * Records a test tone.
|
|---|
| 137 | *
|
|---|
| 138 | * @returns VBox status code.
|
|---|
| 139 | * @param pvUser User-supplied pointer to context data. Optional.
|
|---|
| 140 | * @param pToneParms Tone parameters to use for recording.
|
|---|
| 141 | */
|
|---|
| 142 | DECLR3CALLBACKMEMBER(int, pfnToneRecord, (void const *pvUser, PAUDIOTESTTONEPARMS pToneParms));
|
|---|
| 143 |
|
|---|
| 144 | /** Pointer to opaque user-provided context data. */
|
|---|
| 145 | void const *pvUser;
|
|---|
| 146 | } ATSCALLBACKS;
|
|---|
| 147 | /** Pointer to a const ATS callbacks table. */
|
|---|
| 148 | typedef const struct ATSCALLBACKS *PCATSCALLBACKS;
|
|---|
| 149 |
|
|---|
| 150 | /**
|
|---|
| 151 | * Structure for keeping an Audio Test Service (ATS) instance.
|
|---|
| 152 | */
|
|---|
| 153 | typedef struct ATSSERVER
|
|---|
| 154 | {
|
|---|
| 155 | /** Pointer to the selected transport layer. */
|
|---|
| 156 | PCATSTRANSPORT pTransport;
|
|---|
| 157 | /** Pointer to the transport instance. */
|
|---|
| 158 | PATSTRANSPORTINST pTransportInst;
|
|---|
| 159 | /** The callbacks table. */
|
|---|
| 160 | ATSCALLBACKS Callbacks;
|
|---|
| 161 | /** Whether server is in started state or not. */
|
|---|
| 162 | bool volatile fStarted;
|
|---|
| 163 | /** Whether to terminate or not. */
|
|---|
| 164 | bool volatile fTerminate;
|
|---|
| 165 | /** The main thread's poll set to handle new clients. */
|
|---|
| 166 | RTPOLLSET hPollSet;
|
|---|
| 167 | /** Pipe for communicating with the serving thread about new clients. - read end */
|
|---|
| 168 | RTPIPE hPipeR;
|
|---|
| 169 | /** Pipe for communicating with the serving thread about new clients. - write end */
|
|---|
| 170 | RTPIPE hPipeW;
|
|---|
| 171 | /** Main thread waiting for connections. */
|
|---|
| 172 | RTTHREAD hThreadMain;
|
|---|
| 173 | /** Thread serving connected clients. */
|
|---|
| 174 | RTTHREAD hThreadServing;
|
|---|
| 175 | /** Critical section protecting the list of new clients. */
|
|---|
| 176 | RTCRITSECT CritSectClients;
|
|---|
| 177 | /** List of new clients waiting to be picked up by the client worker thread. */
|
|---|
| 178 | RTLISTANCHOR LstClientsNew;
|
|---|
| 179 | } ATSSERVER;
|
|---|
| 180 | /** Pointer to an Audio Test Service (ATS) instance. */
|
|---|
| 181 | typedef ATSSERVER *PATSSERVER;
|
|---|
| 182 |
|
|---|
| 183 | int AudioTestSvcInit(PATSSERVER pThis, PCATSCALLBACKS pCallbacks);
|
|---|
| 184 | int AudioTestSvcDestroy(PATSSERVER pThis);
|
|---|
| 185 | int AudioTestSvcHandleOption(PATSSERVER pThis, int ch, PCRTGETOPTUNION pVal);
|
|---|
| 186 | int AudioTestSvcStart(PATSSERVER pThis);
|
|---|
| 187 | int AudioTestSvcStop(PATSSERVER pThis);
|
|---|
| 188 |
|
|---|
| 189 | /**
|
|---|
| 190 | * Enumeration for the server connection mode.
|
|---|
| 191 | * Only applies to certain transport implementation like TCP/IP.
|
|---|
| 192 | */
|
|---|
| 193 | typedef enum ATSCONNMODE
|
|---|
| 194 | {
|
|---|
| 195 | /** Both: Uses parallel client and server connection methods (via threads). */
|
|---|
| 196 | ATSCONNMODE_BOTH = 0,
|
|---|
| 197 | /** Client only: Connects to a server. */
|
|---|
| 198 | ATSCONNMODE_CLIENT,
|
|---|
| 199 | /** Server only: Listens for new incoming client connections. */
|
|---|
| 200 | ATSCONNMODE_SERVER,
|
|---|
| 201 | /** 32bit hack. */
|
|---|
| 202 | ATSCONNMODE_32BIT_HACK = 0x7fffffff
|
|---|
| 203 | } ATSCONNMODE;
|
|---|
| 204 |
|
|---|
| 205 | /** TCP/IP options for the ATS server.
|
|---|
| 206 | * @todo Make this more abstract later. */
|
|---|
| 207 | enum ATSTCPOPT
|
|---|
| 208 | {
|
|---|
| 209 | ATSTCPOPT_CONN_MODE = 5000,
|
|---|
| 210 | ATSTCPOPT_BIND_ADDRESS,
|
|---|
| 211 | ATSTCPOPT_BIND_PORT,
|
|---|
| 212 | ATSTCPOPT_CONNECT_ADDRESS,
|
|---|
| 213 | ATSTCPOPT_CONNECT_PORT
|
|---|
| 214 | };
|
|---|
| 215 |
|
|---|
| 216 | #endif /* !VBOX_INCLUDED_SRC_Audio_AudioTestService_h */
|
|---|
| 217 |
|
|---|
