int ok = hw_TranslateFileName(STRPTR name, STRPTR buf, int bufsize,
ULONG *offset, ULONG *size);
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_TranslateFileName() to break down a virtual file specification
into a physical one. You'll then be able to open the virtual file using functions like
fopen() as well. Hollywood's virtual files are always part of a physical file or
memory block. hw_TranslateFileName() only supports the first type, i.e. virtual files
that are part of a physical file. If you want your plugin to be able to handle memory
block-based virtual files as well, you will have to use the hw_TranslateFileNameExt()
function which has been available since Hollywood 6.0.
hw_TranslateFileName() will return the name of the physical container file as well as the
offset and size of the virtual file within that physical file. 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.
If the specified name does not describe a virtual file, hw_TranslateFileName() will
return 0xFFFFFFFF in both offset and size and simply copy the specified file name
to the buffer specified in parameter 2.
Note that this function does not support all features of Hollywood's virtual files. If you need fine-tuned control over virtual file specification analysis, you might want to use hw_TranslateFileNameExt() instead. See hw_TranslateFileNameExt for details.
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.
ULONG to receive the offset in bytes where the virtual file
starts within the physical file returned in bufULONG to receive the size in bytes of the virtual fileTrue on success, False otherwise