1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
/* $Id: AudioTestServiceInternal.h $ */
/** @file
* AudioTestService - Audio test execution server, Internal Header.
*/
/*
* Copyright (C) 2021-2023 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* SPDX-License-Identifier: GPL-3.0-only
*/
#ifndef VBOX_INCLUDED_SRC_Audio_AudioTestServiceInternal_h
#define VBOX_INCLUDED_SRC_Audio_AudioTestServiceInternal_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/getopt.h>
#include <iprt/stream.h>
#include "AudioTestServiceProtocol.h"
RT_C_DECLS_BEGIN
/** Opaque ATS transport layer specific client data. */
typedef struct ATSTRANSPORTCLIENT *PATSTRANSPORTCLIENT;
typedef PATSTRANSPORTCLIENT *PPATSTRANSPORTCLIENT;
/** Opaque ATS transport specific instance data. */
typedef struct ATSTRANSPORTINST *PATSTRANSPORTINST;
typedef PATSTRANSPORTINST *PPATSTRANSPORTINST;
/**
* Transport layer descriptor.
*/
typedef struct ATSTRANSPORT
{
/** The name. */
char szName[16];
/** The description. */
const char *pszDesc;
/** Pointer to an array of options. */
PCRTGETOPTDEF paOpts;
/** The number of options in the array. */
size_t cOpts;
/**
* Print the usage information for this transport layer.
*
* @param pStream The stream to print the usage info to.
*
* @remarks This is only required if TXSTRANSPORT::cOpts is greater than 0.
*/
DECLR3CALLBACKMEMBER(void, pfnUsage,(PRTSTREAM pStream));
/**
* Creates a transport instance.
*
* @returns IPRT status code. On errors, the transport layer shall call
* RTMsgError to display the error details to the user.
* @param ppThis Where to return the created transport instance on success.
*/
DECLR3CALLBACKMEMBER(int, pfnCreate, (PPATSTRANSPORTINST ppThis));
/**
* Destroys a transport instance.
*
* On errors, the transport layer shall call RTMsgError to display the error
* details to the user.
*
* @returns IPRT status code. On errors, the transport layer shall call
* RTMsgError to display the error details to the user.
* @param pThis The transport instance.
* The pointer will be invalid on return.
*/
DECLR3CALLBACKMEMBER(int, pfnDestroy, (PATSTRANSPORTINST pThis));
/**
* Handle an option.
*
* When encountering an options that is not part of the base options, we'll call
* this method for each transport layer until one handles it.
*
* @retval VINF_SUCCESS if handled.
* @retval VERR_TRY_AGAIN if not handled.
* @retval VERR_INVALID_PARAMETER if we should exit with a non-zero status.
*
* @param pThis Transport instance to set options for.
* @param ch The short option value.
* @param pVal Pointer to the value union.
*
* @remarks This is only required if TXSTRANSPORT::cOpts is greater than 0.
*/
DECLR3CALLBACKMEMBER(int, pfnOption,(PATSTRANSPORTINST pThis, int ch, PCRTGETOPTUNION pVal));
/**
* Starts a transport instance.
*
* @returns IPRT status code. On errors, the transport layer shall call
* RTMsgError to display the error details to the user.
* @param pThis Transport instance to initialize.
*/
DECLR3CALLBACKMEMBER(int, pfnStart, (PATSTRANSPORTINST pThis));
/**
* Stops a transport instance, closing and freeing resources.
*
* On errors, the transport layer shall call RTMsgError to display the error
* details to the user.
*
* @param pThis The transport instance.
*/
DECLR3CALLBACKMEMBER(void, pfnStop, (PATSTRANSPORTINST pThis));
/**
* Waits for a new client to connect and returns the client specific data on
* success.
*
* @returns VBox status code.
* @param pThis The transport instance.
* @param msTimeout Timeout (in ms) waiting for a connection to be established.
* Use RT_INDEFINITE_WAIT to wait indefinitely.
* This might or might not be supported by the specific transport implementation.
* @param pfFromServer Returns \c true if the returned client is from a remote server (called a reverse connection),
* or \c false if not (regular client). Optional and can be NULL.
* @param ppClientNew Where to return the allocated client on success.
* Must be destroyed with pfnDisconnect() when done.
*/
DECLR3CALLBACKMEMBER(int, pfnWaitForConnect, (PATSTRANSPORTINST pThis, RTMSINTERVAL msTimeout, bool *pfFromServer, PPATSTRANSPORTCLIENT ppClientNew));
/**
* Disconnects a client and frees up its resources.
*
* @param pThis The transport instance.
* @param pClient Client to disconnect.
* The pointer will be invalid after calling.
*/
DECLR3CALLBACKMEMBER(void, pfnDisconnect, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient));
/**
* Polls for incoming packets.
*
* @returns true if there are pending packets, false if there isn't.
* @param pThis The transport instance.
* @param pClient The client to poll for data.
*/
DECLR3CALLBACKMEMBER(bool, pfnPollIn, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient));
/**
* Adds any pollable handles to the poll set.
*
* @returns IPRT status code.
* @param pThis The transport instance.
* @param hPollSet The poll set to add them to.
* @param pClient The transport client structure.
* @param idStart The handle ID to start at.
*/
DECLR3CALLBACKMEMBER(int, pfnPollSetAdd, (PATSTRANSPORTINST pThis, RTPOLLSET hPollSet, PATSTRANSPORTCLIENT pClient, uint32_t idStart));
/**
* Removes the given client frmo the given pollset.
*
* @returns IPRT status code.
* @param pThis The transport instance.
* @param hPollSet The poll set to remove from.
* @param pClient The transport client structure.
* @param idStart The handle ID to remove.
*/
DECLR3CALLBACKMEMBER(int, pfnPollSetRemove, (PATSTRANSPORTINST pThis, RTPOLLSET hPollSet, PATSTRANSPORTCLIENT pClient, uint32_t idStart));
/**
* Receives an incoming packet.
*
* This will block until the data becomes available or we're interrupted by a
* signal or something.
*
* @returns IPRT status code. On error conditions other than VERR_INTERRUPTED,
* the current operation will be aborted when applicable. When
* interrupted, the transport layer will store the data until the next
* receive call.
*
* @param pThis The transport instance.
* @param pClient The transport client structure.
* @param ppPktHdr Where to return the pointer to the packet we've
* read. This is allocated from the heap using
* RTMemAlloc (w/ ATSPKT_ALIGNMENT) and must be
* free by calling RTMemFree.
*/
DECLR3CALLBACKMEMBER(int, pfnRecvPkt, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient, PPATSPKTHDR ppPktHdr));
/**
* Sends an outgoing packet.
*
* This will block until the data has been written.
*
* @returns IPRT status code.
* @retval VERR_INTERRUPTED if interrupted before anything was sent.
*
* @param pThis The transport instance.
* @param pClient The transport client structure.
* @param pPktHdr The packet to send. The size is given by
* aligning the size in the header by
* ATSPKT_ALIGNMENT.
*/
DECLR3CALLBACKMEMBER(int, pfnSendPkt, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient, PCATSPKTHDR pPktHdr));
/**
* Sends a babble packet and disconnects the client (if applicable).
*
* @param pThis The transport instance.
* @param pClient The transport client structure.
* @param pPktHdr The packet to send. The size is given by
* aligning the size in the header by
* ATSPKT_ALIGNMENT.
* @param cMsSendTimeout The send timeout measured in milliseconds.
*/
DECLR3CALLBACKMEMBER(void, pfnBabble, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient, PCATSPKTHDR pPktHdr, RTMSINTERVAL cMsSendTimeout));
/**
* Notification about a client HOWDY.
*
* @param pThis The transport instance.
* @param pClient The transport client structure.
*/
DECLR3CALLBACKMEMBER(void, pfnNotifyHowdy, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient));
/**
* Notification about a client BYE.
*
* For connection oriented transport layers, it would be good to disconnect the
* client at this point.
*
* @param pThis The transport instance.
* @param pClient The transport client structure.
*/
DECLR3CALLBACKMEMBER(void, pfnNotifyBye, (PATSTRANSPORTINST pThis, PATSTRANSPORTCLIENT pClient));
/**
* Notification about a REBOOT or SHUTDOWN.
*
* For connection oriented transport layers, stop listening for and
* accepting at this point.
*
* @param pThis The transport instance.
*/
DECLR3CALLBACKMEMBER(void, pfnNotifyReboot, (PATSTRANSPORTINST pThis));
/** Non-zero end marker. */
uint32_t u32EndMarker;
} ATSTRANSPORT;
/** Pointer to a const transport layer descriptor. */
typedef const struct ATSTRANSPORT *PCATSTRANSPORT;
extern ATSTRANSPORT const g_TcpTransport;
RT_C_DECLS_END
#endif /* !VBOX_INCLUDED_SRC_Audio_AudioTestServiceInternal_h */
|
