VirtualBox

source: vbox/trunk/src/VBox/Devices/Audio/AudioTestService.h

Last change on this file was 106061, checked in by vboxsync, 3 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.0 KB
Line 
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
38extern const PCATSTRANSPORT g_apTransports[];
39extern 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 */
62typedef 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. */
148typedef const struct ATSCALLBACKS *PCATSCALLBACKS;
149
150/**
151 * Structure for keeping an Audio Test Service (ATS) instance.
152 */
153typedef 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. */
181typedef ATSSERVER *PATSSERVER;
182
183int AudioTestSvcInit(PATSSERVER pThis, PCATSCALLBACKS pCallbacks);
184int AudioTestSvcDestroy(PATSSERVER pThis);
185int AudioTestSvcHandleOption(PATSSERVER pThis, int ch, PCRTGETOPTUNION pVal);
186int AudioTestSvcStart(PATSSERVER pThis);
187int AudioTestSvcStop(PATSSERVER pThis);
188
189/**
190 * Enumeration for the server connection mode.
191 * Only applies to certain transport implementation like TCP/IP.
192 */
193typedef 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. */
207enum 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
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