VirtualBox

Changeset 89043 in vbox for trunk


Ignore:
Timestamp:
May 14, 2021 12:59:51 PM (4 years ago)
Author:
vboxsync
Message:

Audio/ValKit: Docs update, use intermediate path in AudioTestPathCreateTemp(). bugref:10008

Location:
trunk/src/VBox/Devices/Audio
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Devices/Audio/AudioTest.cpp

    r89014 r89043  
    4848*   Defines                                                                                                                      *
    4949*********************************************************************************************************************************/
    50 /** The test manifest file. */
     50/** The test manifest file name. */
    5151#define AUDIOTEST_MANIFEST_FILE_STR "vkat_manifest.ini"
     52/** The current test manifest version. */
    5253#define AUDIOTEST_MANIFEST_VER      1
    5354
     55/** Test manifest header name. */
    5456#define AUDIOTEST_INI_SEC_HDR_STR   "header"
    5557
    … …  
    267269}
    268270
     271/**
     272 * Writes string data to a test set manifest.
     273 *
     274 * @returns VBox status code.
     275 * @param   pSet                Test set to write manifest for.
     276 * @param   pszFormat           Format string to write.
     277 * @param   args                Variable arguments for \a pszFormat.
     278 */
    269279static int audioTestManifestWriteV(PAUDIOTESTSET pSet, const char *pszFormat, va_list args)
    270280{
    … …  
    282292}
    283293
     294/**
     295 * Writes a terminated string line to a test set manifest.
     296 * Convenience function.
     297 *
     298 * @returns VBox status code.
     299 * @param   pSet                Test set to write manifest for.
     300 * @param   pszFormat           Format string to write.
     301 * @param   args                Variable arguments for \a pszFormat.
     302 */
    284303static int audioTestManifestWriteLn(PAUDIOTESTSET pSet, const char *pszFormat, ...)
    285304{
    … …  
    299318}
    300319
     320/**
     321 * Writes a section entry to a test set manifest.
     322 *
     323 * @returns VBox status code.
     324 * @param   pSet                Test set to write manifest for.
     325 * @param   pszFormat           Format string of section to write.
     326 * @param   args                Variable arguments for \a pszFormat.
     327 */
    301328static int audioTestManifestWriteSection(PAUDIOTESTSET pSet, const char *pszFormat, ...)
    302329{
    … …  
    319346}
    320347
     348/**
     349 * Initializes an audio test set, internal function.
     350 * @param   pSet                Test set to initialize.
     351 */
    321352static void audioTestSetInitInternal(PAUDIOTESTSET pSet)
    322353{
    … …  
    324355}
    325356
     357/**
     358 * Returns whether a test set's manifest file is open (and thus ready) or not.
     359 *
     360 * @returns \c true if open (and ready), or \c false if not.
     361 * @retval  VERR_
     362 * @param   pSet                Test set to return open status for.
     363 */
    326364static bool audioTestManifestIsOpen(PAUDIOTESTSET pSet)
    327365{
    … …  
    336374}
    337375
     376/**
     377 * Initializes an audio test error description.
     378 *
     379 * @param   pErr                Test error description to initialize.
     380 */
    338381static void audioTestErrorDescInit(PAUDIOTESTERRORDESC pErr)
    339382{
    … …  
    342385}
    343386
     387/**
     388 * Destroys an audio test error description.
     389 *
     390 * @param   pErr                Test error description to destroy.
     391 */
    344392void AudioTestErrorDescDestroy(PAUDIOTESTERRORDESC pErr)
    345393{
    … …  
    361409}
    362410
     411/**
     412 * Returns if an audio test error description contains any errors or not.
     413 *
     414 * @returns \c true if it contains errors, or \c false if not.
     415 *
     416 * @param   pErr                Test error description to return error status for.
     417 */
    363418bool AudioTestErrorDescFailed(PAUDIOTESTERRORDESC pErr)
    364419{
    … …  
    372427}
    373428
    374 static int audioTestErrorDescAddV(PAUDIOTESTERRORDESC pErr, int rc, const char *pszFormat, va_list args)
     429/**
     430 * Adds a single error entry to an audio test error description, va_list version.
     431 *
     432 * @returns VBox status code.
     433 * @param   pErr                Test error description to add entry for.
     434 * @param   rc                  Result code of entry to add.
     435 * @param   pszDesc             Error description format string to add.
     436 * @param   args                Optional format arguments of \a pszDesc to add.
     437 */
     438static int audioTestErrorDescAddV(PAUDIOTESTERRORDESC pErr, int rc, const char *pszDesc, va_list args)
    375439{
    376440    PAUDIOTESTERRORENTRY pEntry = (PAUDIOTESTERRORENTRY)RTMemAlloc(sizeof(AUDIOTESTERRORENTRY));
    377441    AssertReturn(pEntry, VERR_NO_MEMORY);
    378442
    379     if (RTStrPrintf2V(pEntry->szDesc, sizeof(pEntry->szDesc), pszFormat, args) < 0)
     443    if (RTStrPrintf2V(pEntry->szDesc, sizeof(pEntry->szDesc), pszDesc, args) < 0)
    380444        AssertFailedReturn(VERR_BUFFER_OVERFLOW);
    381445
    … …  
    389453}
    390454
    391 static int audioTestErrorDescAdd(PAUDIOTESTERRORDESC pErr, const char *pszFormat, ...)
     455/**
     456 * Adds a single error entry to an audio test error description, va_list version.
     457 *
     458 * @returns VBox status code.
     459 * @param   pErr                Test error description to add entry for.
     460 * @param   pszDesc             Error description format string to add.
     461 * @param   ...                 Optional format arguments of \a pszDesc to add.
     462 */
     463static int audioTestErrorDescAdd(PAUDIOTESTERRORDESC pErr, const char *pszDesc, ...)
     464{
     465    va_list va;
     466    va_start(va, pszDesc);
     467
     468    int rc = audioTestErrorDescAddV(pErr, VERR_GENERAL_FAILURE /** @todo Fudge! */, pszDesc, va);
     469
     470    va_end(va);
     471    return rc;
     472}
     473
     474#if 0
     475static int audioTestErrorDescAddRc(PAUDIOTESTERRORDESC pErr, int rc, const char *pszFormat, ...)
    392476{
    393477    va_list va;
    394478    va_start(va, pszFormat);
    395479
    396     int rc = audioTestErrorDescAddV(pErr, VERR_GENERAL_FAILURE /** @todo Fudge! */, pszFormat, va);
    397 
    398     va_end(va);
    399     return rc;
    400 }
    401 
    402 #if 0
    403 static int audioTestErrorDescAddRc(PAUDIOTESTERRORDESC pErr, int rc, const char *pszFormat, ...)
    404 {
    405     va_list va;
    406     va_start(va, pszFormat);
    407 
    408480    int rc2 = audioTestErrorDescAddV(pErr, rc, pszFormat, va);
    409481
    … …  
    413485#endif
    414486
     487/**
     488 * Creates a new temporary directory with a specific (test) tag.
     489 *
     490 * @returns VBox status code.
     491 * @param   pszPath             Where to return the path of the created directory on success.
     492 * @param   cbPath              Size (in bytes) of \a pszPath.
     493 * @param   pszTag              Tag name to use for directory creation.
     494 */
    415495int AudioTestPathCreateTemp(char *pszPath, size_t cbPath, const char *pszTag)
    416496{
    417     int rc = RTPathTemp(pszPath, cbPath);
     497    char szPath[RTPATH_MAX];
     498
     499    int rc = RTPathTemp(szPath, sizeof(szPath));
    418500    AssertRCReturn(rc, rc);
    419     rc = AudioTestPathCreate(pszPath, cbPath, pszTag);
     501    rc = AudioTestPathCreate(szPath, sizeof(szPath), pszTag);
    420502    AssertRCReturn(rc, rc);
    421503
    422     return rc;
    423 }
    424 
     504    return RTStrCopy(pszPath, cbPath, szPath);
     505}
     506
     507/**
     508 * Creates a new audio test set.
     509 *
     510 * @returns VBox status code.
     511 * @param   pSet                Test set to create.
     512 * @param   pszPath             Absolute path to use for the test set's temporary directory.
     513 *                              If NULL, the OS' temporary directory will be used.
     514 * @param   pszTag              Tag name to use for this test set.
     515 */
    425516int AudioTestSetCreate(PAUDIOTESTSET pSet, const char *pszPath, const char *pszTag)
    426517{
    … …  
    495586}
    496587
     588/**
     589 * Destroys a test set.
     590 *
     591 * @param   pSet                Test set to destroy.
     592 */
    497593void AudioTestSetDestroy(PAUDIOTESTSET pSet)
    498594{
    … …  
    507603}
    508604
     605/**
     606 * Opens an existing audio test set.
     607 *
     608 * @returns VBox status code.
     609 * @param   pSet                Test set to open.
     610 * @param   pszPath             Absolute path of the test set to open.
     611 */
    509612int AudioTestSetOpen(PAUDIOTESTSET pSet, const char *pszPath)
    510613{
    … …  
    532635}
    533636
     637/**
     638 * Closes an opened audio test set.
     639 *
     640 * @param   pSet                Test set to close.
     641 */
    534642void AudioTestSetClose(PAUDIOTESTSET pSet)
    535643{
    … …  
    537645}
    538646
     647/**
     648 * Packs an audio test so that it's ready for transmission.
     649 *
     650 * @returns VBox status code.
     651 * @param   pSet                Test set to pack.
     652 * @param   pszOutDir           Where to store the packed test set.
     653 */
    539654int AudioTestSetPack(PAUDIOTESTSET pSet, const char *pszOutDir)
    540655{
    … …  
    547662}
    548663
     664/**
     665 * Unpacks a formerly packed audio test set.
     666 *
     667 * @returns VBox status code.
     668 * @param   pszFile             Test set file to unpack.
     669 * @param   pszOutDir           Directory where to unpack the test set into.
     670 *                              If the directory does not exist it will be created.
     671 */
    549672int AudioTestSetUnpack(const char *pszFile, const char *pszOutDir)
    550673{
    … …  
    556679}
    557680
     681/**
     682 * Verifies an opened audio test set.
     683 *
     684 * @returns VBox status code.
     685 * @param   pSet                Test set to verify.
     686 * @param   pszTag              Tag to use for verification purpose.
     687 * @param   pErrDesc            Where to return the test verification errors.
     688 *
     689 * @note    Test verification errors have to be checked for errors, regardless of the
     690 *          actual return code.
     691 */
    558692int AudioTestSetVerify(PAUDIOTESTSET pSet, const char *pszTag, PAUDIOTESTERRORDESC pErrDesc)
    559693{

  • trunk/src/VBox/Devices/Audio/AudioTest.h

    r89019 r89043  
    2424#endif
    2525
     26/** Prefix for audio test (set) directories. */
    2627#define AUDIOTEST_PATH_PREFIX_STR "audio-test-"
    2728
    … …  
    120121    AUDIOTESTTYPE_INVALID = 0,
    121122    /** Play a test tone. */
    122     AUDIOTESTTYPE_TESTTONE
     123    AUDIOTESTTYPE_TESTTONE,
     124        /** The usual 32-bit hack. */
     125    AUDIOTESTTYPE_32BIT_HACK = 0x7fffffff
    123126} AUDIOTESTTYPE;
    124127
    … …  
    188191typedef struct AUDIOTESTERRORDESC
    189192{
     193    /** List entries containing the (FIFO-style) errors of type AUDIOTESTERRORENTRY. */
    190194    RTLISTANCHOR     List;
     195    /** Number of errors in the list. */
    191196    uint32_t         cErrors;
    192197} AUDIOTESTERRORDESC;
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette