Description

To add additional files to an .adtfdat recording, the Attached Files mechanism can be used.
This is an extension within the .adtfdat file to store required content for playback (e.g. databases, descriptions).
Use this mechanism to make the file self-contained for any playback or post-processing scenerio.

Adding attached files

The Recorder can attach files to .adtfdat recordings based on a XML configuration file.
The XSD describing the format can be found at ./doc/xsd/xmlbinding/adtfxsdattachments/adtfxsdattachments.xsd

Let's take a look at the following example:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<attachments xmlns="adtf/xsd/attachments">
    <file_version>
        <major>1</major>
        <minor>0</minor>
    </file_version>
 
    <!-- add a file by relative or absolute path -->
    <path>
        <source>folder1/file1.txt</source>
        <!-- this is the location within the archive -->
        <destination>file1.txt</destination>
        <!-- tags can be used to reference files via macros after extraction -->
        <tags>
            <tag>file1</tag>
            <!-- you can add multiple tags to each entry -->
            <tag>files</tag>
        </tags>
    </path>
 
    <!-- add a folder recursively -->
    <path>
        <source>folder2/subfolder1</source>
        <destination>some/where/else</destination>
        <tags>
            <tag>subfolder1</tag>
        </tags>
    </path>
 
    <!-- add files by wildcard -->
    <path>
        <source>folder3/*.txt</source>
        <!-- mind the trailing slash, this way the filenames names will be appended -->
        <destination>text/files/from_folder3/</destination>
        <!-- multiple files will be seperated by ';' within a resolved tag value -->
        <tags>
            <tag>text_file_folder</tag>
        </tags>
    </path>
 
    <!-- add folders by wildcard -->
    <path>
        <source>folder3/*/subfolder2</source>
        <destination>wildcard_folder</destination>
        <tags>
            <tag>subfolder2</tag>
        </tags>
    </path>
 
    <!-- add a file with content directly from this file -->
    <embedded_file>
        <content>Hello, world!</content>
        <destination>hello.txt</destination>
        <tags>
            <tag>hello</tag>
            <tag>files</tag>
        </tags>
    </embedded_file>
 
    <!-- add a tag with a given value -->
    <embedded_value>
        <content>OUTATIME</content>
        <tags>
            <tag>license_plate</tag>
        </tags>
    </embedded_value>
</attachments>

By specifing this file in the property attachment_configuration_file, these files will be attached to each recording. Please see Recorder for further properties regarding attached files handling.

Creating Files and Configuration "on the fly"

If the Property cache_attachment_archive of the Recorder is set to false, then it will read the configuration and attach the files each time a recording is closed.
This happens after the kernel signal PreFileClosed (see adtf::services::IRecordingSignal) has been processed by all recipients.
This way you can create files that should be attached or even (re-)create the configuration during handling of this signal.

Warning: Mind that all this happens asynchronously to the adtf::services::IRecorder::Stop call.
So use the adtf::services::IRecordingFile::GetTimeRange method to choose data to your liking.

Extracting attached files

There are multiple ways to extract files from .adtfdat recordings:

Extraction via Interface Call

The local interface adtf::services::IPlayer::ExtractAttachedFiles and the rpc interface adtf::remote::IPlayer::ExtractAttachedFiles allows a user to extract files at any given time.

Extraction via Property

If there is an .adtfdat recording specified in the extract_attached_files_from property of the Playback Service, then the files will be extracted during service initialization.

Note: Mind that you also need to specify the extraction_destination_directory property in this case.

Manual Extraction

The files are stored as a tar.gz archive within the attached_files extension of an ADTFDAT file.
So the files can easily be extracted with the help of the adtf_dattool:

adtf_dattool --export recording.adtfdat --extension attached_files --output attached_files.tar.gz

and then open the archive with your preferred archiver.

Accessing Extracted Files

To access extracted files you can use the tags via macros.
The Playback Service will define a macro in the form of $(AF:<tag_name>) for each tag.
If a tag is referenced by multiple files the macro will resolve to a semi-colon seperated list.
This way you can use these macros within your properties.

Using our example above the following macros would be available:

$(AF:file1) with the path to file1.txt
$(AF:hello) with the path to hello.txt
$(AF:subfolder1) with the path to some/where/else
$(AF:subfolder2) with the path to wildcard_folder
$(AF:text_file_folder) with the path to text/files/from_folder3
$(AF:files) a ; seperated list of file1.txt and hello.txt
$(AF:license_plate) with the string OUTATIME

Note: In order for this to work in service properties, make sure that the Playback Service is initialized before the services where you are using these macros in the Properties.

Table of Contents