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

/* $Id: AudioTestService.h 90918 2021-08-26 15:29:25Z vboxsync $ */
/** @file
 * AudioTestService - Audio test execution server, Public Header.
 */

/*
 * Copyright (C) 2021 Oracle Corporation
 *
 * This file is part of VirtualBox Open Source Edition (OSE), as
 * available from http://www.virtualbox.org. This file is free software;
 * you can redistribute it and/or modify it under the terms of the GNU
 * General Public License (GPL) as published by the Free Software
 * Foundation, in version 2 as it comes in the "COPYING" file of the
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
 */

#ifndef VBOX_INCLUDED_SRC_Audio_AudioTestService_h
#define VBOX_INCLUDED_SRC_Audio_AudioTestService_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif

#include <iprt/tcp.h>

#include "AudioTestServiceInternal.h"

extern const PCATSTRANSPORT g_apTransports[];
extern const size_t         g_cTransports;

/** Default TCP/IP bind port the guest ATS (Audio Test Service) is listening on. */
#define ATS_TCP_DEF_BIND_PORT_GUEST                6042
/** Default TCP/IP bind port the host ATS is listening on. */
#define ATS_TCP_DEF_BIND_PORT_HOST                 6052
/** Default TCP/IP ATS bind port the ValidationKit Audio Driver ATS is listening on. */
#define ATS_TCP_DEF_BIND_PORT_VALKIT               6062
/** Default TCP/IP port the guest ATS is connecting to. */
#define ATS_TCP_DEF_CONNECT_PORT_GUEST              ATS_TCP_DEF_BIND_PORT_HOST
/** Default TCP/IP port the host ATS is connecting to the guest (needs NAT port forwarding). */
#define ATS_TCP_DEF_CONNECT_PORT_HOST_PORT_FWD     6072
/** Default TCP/IP port the host ATS is connecting to. */
#define ATS_TCP_DEF_CONNECT_PORT_VALKIT            ATS_TCP_DEF_BIND_PORT_VALKIT
/** Default TCP/IP address the host is connecting to. */
#define ATS_TCP_DEF_CONNECT_HOST_ADDR_STR          "127.0.0.1"
/** Default TCP/IP address the guest ATS connects to when
 *  running in client mode (reversed mode, needed for NATed VMs). */
#define ATS_TCP_DEF_CONNECT_GUEST_STR              "10.0.2.2"

/**
 * Structure for keeping an Audio Test Service (ATS) callback table.
 */
typedef struct ATSCALLBACKS
{
    /**
     * Tells the implementation that a new client connected. Optional.
     *
     * @param   pvUser          User-supplied pointer to context data. Optional.
     */
    DECLR3CALLBACKMEMBER(int, pfnHowdy, (void const *pvUser));

    /**
     * Tells the implementation that a client disconnected. Optional.
     *
     * @param   pvUser          User-supplied pointer to context data. Optional.
     */
    DECLR3CALLBACKMEMBER(int, pfnBye, (void const *pvUser));

    /**
     * Begins a test set. Optional.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pszTag          Tag of test set to begin.
     */
    DECLR3CALLBACKMEMBER(int, pfnTestSetBegin, (void const *pvUser, const char *pszTag));

    /**
     * Ends the current test set. Optional.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pszTag          Tag of test set to end.
     */
    DECLR3CALLBACKMEMBER(int, pfnTestSetEnd,   (void const *pvUser, const char *pszTag));

    /**
     * Marks the begin of sending a test set. Optional.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pszTag          Tag of test set to begin sending.
     */
    DECLR3CALLBACKMEMBER(int, pfnTestSetSendBegin, (void const *pvUser, const char *pszTag));

    /**
     * Reads data from a test set for sending it.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pszTag          Tag of test set to begin sending.
     * @param   pvBuf           Where to store the read test set data.
     * @param   cbBuf           Size of \a pvBuf (in bytes).
     * @param   pcbRead         Where to return the amount of read data in bytes. Optional and can be NULL.
     */
    DECLR3CALLBACKMEMBER(int, pfnTestSetSendRead,  (void const *pvUser, const char *pszTag, void *pvBuf, size_t cbBuf, size_t *pcbRead));

    /**
     * Marks the end of sending a test set. Optional.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pszTag          Tag of test set to end sending.
     */
    DECLR3CALLBACKMEMBER(int, pfnTestSetSendEnd,   (void const *pvUser, const char *pszTag));

    /**
     * Plays a test tone.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pToneParms      Tone parameters to use for playback.
     */
    DECLR3CALLBACKMEMBER(int, pfnTonePlay, (void const *pvUser, PAUDIOTESTTONEPARMS pToneParms));

    /**
     * Records a test tone.
     *
     * @returns VBox status code.
     * @param   pvUser          User-supplied pointer to context data. Optional.
     * @param   pToneParms      Tone parameters to use for recording.
     */
    DECLR3CALLBACKMEMBER(int, pfnToneRecord, (void const *pvUser, PAUDIOTESTTONEPARMS pToneParms));

    /** Pointer to opaque user-provided context data. */
    void const *pvUser;
} ATSCALLBACKS;
/** Pointer to a const ATS callbacks table. */
typedef const struct ATSCALLBACKS *PCATSCALLBACKS;

/**
 * Structure for keeping an Audio Test Service (ATS) instance.
 */
typedef struct ATSSERVER
{
    /** Pointer to the selected transport layer. */
    PCATSTRANSPORT       pTransport;
    /** Pointer to the transport instance. */
    PATSTRANSPORTINST    pTransportInst;
    /** The callbacks table. */
    ATSCALLBACKS         Callbacks;
    /** Whether server is in started state or not. */
    bool volatile        fStarted;
    /** Whether to terminate or not. */
    bool volatile        fTerminate;
    /** The main thread's poll set to handle new clients. */
    RTPOLLSET            hPollSet;
    /** Pipe for communicating with the serving thread about new clients. - read end */
    RTPIPE               hPipeR;
    /** Pipe for communicating with the serving thread about new clients. - write end */
    RTPIPE               hPipeW;
    /** Main thread waiting for connections. */
    RTTHREAD             hThreadMain;
    /** Thread serving connected clients. */
    RTTHREAD             hThreadServing;
    /** Critical section protecting the list of new clients. */
    RTCRITSECT           CritSectClients;
    /** List of new clients waiting to be picked up by the client worker thread. */
    RTLISTANCHOR         LstClientsNew;
} ATSSERVER;
/** Pointer to an Audio Test Service (ATS) instance. */
typedef ATSSERVER *PATSSERVER;

int AudioTestSvcInit(PATSSERVER pThis, PCATSCALLBACKS pCallbacks);
int AudioTestSvcDestroy(PATSSERVER pThis);
int AudioTestSvcHandleOption(PATSSERVER pThis, int ch, PCRTGETOPTUNION pVal);
int AudioTestSvcStart(PATSSERVER pThis);
int AudioTestSvcStop(PATSSERVER pThis);

/**
 * Enumeration for the server connection mode.
 * Only applies to certain transport implementation like TCP/IP.
 */
typedef enum ATSCONNMODE
{
    /** Both: Uses parallel client and server connection methods (via threads). */
    ATSCONNMODE_BOTH = 0,
    /** Client only: Connects to a server. */
    ATSCONNMODE_CLIENT,
    /** Server only: Listens for new incoming client connections. */
    ATSCONNMODE_SERVER,
    /** 32bit hack. */
    ATSCONNMODE_32BIT_HACK = 0x7fffffff
} ATSCONNMODE;

/** TCP/IP options for the ATS server.
 *  @todo Make this more abstract later. */
enum ATSTCPOPT
{
    ATSTCPOPT_CONN_MODE = 5000,
    ATSTCPOPT_BIND_ADDRESS,
    ATSTCPOPT_BIND_PORT,
    ATSTCPOPT_CONNECT_ADDRESS,
    ATSTCPOPT_CONNECT_PORT
};

#endif /* !VBOX_INCLUDED_SRC_Audio_AudioTestService_h */