Name
hw_TranslateFileNameExt -- translate a virtual file name with extended options (V6.0)
Synopsis
int ok = hw_TranslateFileNameExt(STRPTR name, struct hwTranslateFileInfo
             *tf, struct hwTagList *tags);
Function
This function does the same as hw_TranslateFileName() but supports additional options. Like hw_TranslateFileName(), it can be used to translate a virtual file specification into a physical file name. Hollywood supports special virtual file specifications in order to be able to load files that have been linked to other files, for example applets or executables. Only Hollywood functions like hw_FOpen() will be able to deal with these special virtual file name specifications transparently. If you pass them to a function like fopen() instead, it will fail to open the file. That's why you should always use the functions from DOSBase when dealing with files. See File IO information for details.

If you cannot use the functions from DOSBase to do your file IO for some particular reason, you can use hw_TranslateFileNameExt() to break down a virtual file specification into a physical one. You'll have to pass a pointer to a struct hwTranslateFileInfo structure to this function. struct hwTranslateFileInfo looks like this:

 
struct hwTranslateFileInfo
{
    STRPTR File;       // [in/out]
    int FileLen;       // [in]
    STRPTR FileExt;    // [in/out]
    int FileExtLen;    // [in]
    STRPTR RealFile;   // [in/out]
    int RealFileLen;   // [in]
    APTR MemoryBlock;  // [out]
    DOSINT64 Offset;   // [out]
    DOSINT64 Length;   // [out]
};

Here's a description of the individual structure members:

File:
If this is non-NULL, Hollywood will copy the name of the virtual file to this string buffer. You will also have to provide the size of this buffer in the FileLen argument.

FileLen:
If File is non-NULL, you'll have to set this member to the size of the buffer passed in File.

FileExt:
If this is non-NULL, Hollywood will copy the extension of the virtual file to this string buffer. You will also have to provide the size of this buffer in the FileExtLen argument.

FileExtLen:
If FileExt is non-NULL, you'll have to set this member to the size of the buffer passed in FileExt.

RealFile:
If this is non-NULL, Hollywood will copy the name of the file that contains the virtual file to this string buffer. For example, there might be a virtual file named intro.png inside the physical file gamedata.bin at offset 1048576 from the start of the file taking up 65536 bytes inside gamedata.bin. In case the virtual file doesn't have a container file but is stored within a memory block, Hollywood will set this member to an empty string and will store a pointer to the memory block that contains the virtual file in MemoryBlock. Note that if you set RealFile, you will also have to provide the size of the buffer in the RealFileLen argument.

RealFileLen:
If RealFile is non-NULL, you'll have to set this member to the size of the buffer passed in RealFile.

MemoryBlock:
In case the virtual file doesn't have a container file but is stored within a memory block, Hollywood will set this structure member to a pointer to the memory block that contains the virtual file.

Offset:
Hollywood will store the offset of the virtual file inside the container file here. This is always 0 in case the virtual file is memory-based.

Length:
Hollywood will store the length of the virtual file here.

You can use hw_ChunkToFile() to easily save a virtual file to a physical file. See hw_ChunkToFile for details.

This function is thread-safe.

Designer compatibility
Unsupported

Inputs
name
file name specification containing a virtual file
tf
pointer to a struct hwTranslateFileInfo initialized as described above
tags
reserved for future use, pass NULL for now
Results
ok
True on success, False otherwise
Show TOC