Adds file inspection callback and example code

[val-ms]

libclamav callbacks can be used to access embedded file content at each
layer of extraction during the course of a scan. The existing callbacks
only provide access to the file descriptor and a guess at the file type.

This patch adds a new callback for the purposes of file/archive
inspection that provides additional insight into the embedded file.
This includes:

• ancestors: an array of parent file names
• parent file size: the size of the direct parent layer
• file name: current layer's filename, if any.
• file buffer (pointer)
• file size: size of file buffer
• file type: just a guess at the current file's type
• file descriptor: may be -1 if the layer is in-memory only.
• layer attributes: a flag field. see LAYER_ATTRIBUTE_* defines in clamav.h

Two new example apps are added that are automatically built when
compiling under CMake:

• ex2 demonstrates the prescan callback.
• ex3 demonstrates the new file inspection callback.

The examples are now installed if enabled, so you can test them in the
Docker image, and so that they'll be colocated with the DLLs so you can
test them on Windows. The installed examples should also be able to find
the UnRAR library at run time, without having to set LD_LIBRARY_PATH.

This commit also sets the fmap->name in an fmap-scan using the basname
of the provided filename if the caller provided the filename and the
provided fmap does not have the name set.

[val-ms]

This PR was replicated from an internal backlogged PR. It is pending additional research & testing. I'm not yet certain this new API offers the best parameters. Will have to work with other teams to demonstrate its value.

[val-ms]

I forgot to note that to test the example program ex3, you need to tell it where to load libclamunrar_iface for RAR support to work. Eg:

LD_LIBRARY_PATH=/home/micasnyd/workspace/clamav/build/libclamunrar_iface ./examples/ex3_file_inspection ~/Downloads/test-files.zip

[val-ms]

Some issues identified in review so far:

• need parent filename with cl_scanmap() / cl_scanmap_callback().
  • right now the original filename appears to be lost with the scanmap API.
• need recursion depth parameter in callback.
• give information if the parent file is encrypted which will be useful if any decryption / password guessing capabilities are added.

[val-ms]

I've updated this PR once more, making it so the "is normalized" and "was encrypted" booleans are provided in an attributes flag field that may be extended without breaking the API.
I've also changed the "parents" parameter to an "ancestors" parameter that is now an array of filenames. the filenames may be NULL for layers that don't have names.

I'm content with how this works now. Ready for review.

[shutton]

Not familiar enough to follow the logic, so mainly commenting on style.

Also need to consider the risk level of this feature for 0.105. Presumably regression testing should vet it, but...

[val-ms]

Just rebased to update it.

[shutton]

Ship it!

[val-ms]

Test results look good. Merging.

This new callback API will likely be annotated as "unstable" in the upcoming feature release in case we are required to adjust the parameters in the next feature release.