1 | /* $Id: AudioTestService.h 106061 2024-09-16 14:03:52Z vboxsync $ */
|
---|
2 | /** @file
|
---|
3 | * AudioTestService - Audio test execution server, Public Header.
|
---|
4 | */
|
---|
5 |
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2021-2024 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 |
|
---|