Adding attached files to ADTFDAT recordings

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' of a recorder, these files will be attached to each recording. Please see ADTFDAT File Recorder for further properties regarding attached files handling.

Extracting attached files from ADTFDAT recordings

There are multiple ways to extract files from ADTFDAT recordings.

Extraction via Interface Call

The local interface ExtractAttachedFiles and the RPC interface 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.

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 in your Properties (all kinds of Properties, but especially for Properties of Type cFilename, cFilepath, cFilenameList, and cFilepathList.

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.

Advanced Information

Creating Files and Configuration "on the fly"

If the Property 'cache_attachment_archive' of the recorder is set to false, then the recorder will read the configuration and attach the files each time a recording is closed. This happens after the kernel signal PreFileClosed (see adtf::services::ant::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.

Mind that all this happens asynchronously to the Stop call. So use the GetTimeRange method to choose data to your liking.

Archive Format

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 tool:

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

and then open the archive with your preferred archiver.

Table of Contents