int ok = FStat(APTR handle, ULONG flags, struct hwos_StatStruct *st,
                   struct hwTagList *tags);

struct hwos_StatStruct { int Type; // [out] DOSINT64 Size; // [out] ULONG Flags; // [out] struct hwos_DateStruct Time; // [out] struct hwos_DateStruct LastAccessTime; // [out] struct hwos_DateStruct CreationTime; // [out] STRPTR FullPath; // [out] STRPTR Comment; // [out] int LinkMode; // [out] STRPTR Container; // [out] };

Your FStat() implementation needs to write the following information to the individual structure members:

Type:

This must always be set to HWSTATTYPE_FILE.

Size:

This must be set to the size of the file in bytes or -1 if the size is not known, maybe because the file is being streamed from a network source.

Flags:

Combination of flags describing the file system object attributes. See File attributes for a list of supported attributes.

Time:

Time stamp indicating when this file system object was last modified. This information is optional. Do not touch this member if you don't have this time information.

LastAccessTime:

Time stamp indicating when this file system object was last accessed. This information is optional. Do not touch this member if you don't have this time information.

CreationTime:

Time stamp indicating when this file system object was created. This information is optional. Do not touch this member if you don't have this time information.

FullPath:

Fully qualified path to the file. This must be provided. If the HWSTATFLAGS_ALLOCSTRINGS flag is not set, you can set this to a static string buffer which must stay valid until the next call to FStat(). If HWSTATFLAGS_ALLOCSTRINGS has been set, you need to allocate a string buffer using hw_TrackedAlloc().

Comment:

Comment stored for this file in the file system. Set this to NULL if you do not have this information or the file system doesn't support storage of comments. If the HWSTATFLAGS_ALLOCSTRINGS flag is not set, you can set this to a static string buffer which must stay valid until the next call to Stat(). If HWSTATFLAGS_ALLOCSTRINGS has been set, you need to allocate a string buffer using hw_TrackedAlloc().

LinkMode:

This member has to be set to the link mode to use when Hollywood needs to link this file into an applet or executable. This can be one of the following pre-defined link modes:

HWSTATLKMODE_NORMAL:

Normal link mode. This means that all data is simply read from the file and is written to the applet or executable. Consequently, your file adapter is no longer necessary when running the compiled applet or executable since the data has already been converted to its raw form. Thus, if you use HWSTATLKMODE_NORMAL, the compiled applet or executable won't require your file adapter plugin any more. Also, your file adapter won't be called at all when the user runs the compiled applet or executable because Hollywood has already obtained the raw data from the file adapter during linking stage.

HWSTATLKMODE_NONE:

This file should never be linked to applets or executables. If you use this link mode, Hollywood will not link the file and just keep the original reference that was specified in the Hollywood script, whatever it may be. This can be useful when writing a file adapter that streams data from a network source like an HTTP server. It wouldn't make sense then for the Hollywood linker to always download the whole file and link it to your applet or executable. Instead, just the URL specification should be linked so that the data is streamed from this URL when the user runs the compiled applet or executable. In that case HWSTATLKMODE_NONE is the right choice since it skips linking for this file altogether.

HWSTATLKMODE_CONTAINER:

This link mode allows you to specify a container file that should be linked instead of the current file. Imagine you are writing a file adapter that can load a compressed file format like gzip. If you used HWSTATLKMODE_NORMAL now, Hollywood would always link the uncompressed data to the applet or executable. However, you might want to make Hollywood link the compressed data instead. This can be achieved by setting the link mode to HWSTATLKMODE_CONTAINER and then setting the Container member of this structure to the file that contains the compressed data. When setting LinkMode to HWSTATLKMODE_CONTAINER, Hollywood will always link the file specified in Container instead of the current file. Please note that if you use HWSTATLKMODE_CONTAINER, your implementation of FOpen() has to support the HWFOPENTAG_CHUNKXXX tags and you have to set the HWCLAFAFLAGS_CHUNKLOADER flag using hw_ConfigureLoaderAdapter(). See FOpen for details.

Container:

If you set LinkMode to HWSTATLKMODE_CONTAINER, you need to set this member to a path to a file that should be linked instead of the current file when Hollywood is in linking mode. This can be used for fine-tuned control over Hollywood's linker. See above for more information. The string buffer you use to pass a container file to Hollywood must stay valid until the next call to FStat(). Note that HWSTATFLAGS_ALLOCSTRINGS (see below) doesn't affect Container. It must always use a static string buffer. If link mode isn't set to HWSTATLKMODE_CONTAINER, set this member to NULL.

The following flags are supported by FStat():

HWSTATFLAGS_ALLOCSTRINGS:

If this flag is set, FStat() must not use static string buffers for the FullPath and Comment structure members but allocate new private string buffers for them. Hollywood will then call hw_TrackedFree() on these buffers once it is done with them. This flag is often set when FStat() is used in a multithreaded setup.

FStat() has to return True on success or False on failure.

This function must be implemented in a thread-safe manner if the HWSTATFLAGS_ALLOCSTRINGS flag is set.

handle

file handle returned by FOpen()

flags

additional flags (see above)

st

pointer to a struct hwos_StatStruct for storing information about the file

tags

reserved for future use (currently NULL)

ok

True to indicate success, False on failure