hw_TranslateFileName -- translate a virtual file name (V5.3)
int ok = hw_TranslateFileName(STRPTR name, STRPTR buf, int bufsize,
             ULONG *offset, ULONG *size);
This function 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_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.

Designer compatibility

file name specification containing either a virtual or a physical file
memory buffer to receive the physical file
size of the memory buffer
pointer to a ULONG to receive the offset in bytes where the virtual file starts within the physical file returned in buf
pointer to a ULONG to receive the size in bytes of the virtual file
True on success, False otherwise

Show TOC