Name
FOpen -- open a file (V6.0)
Synopsis
APTR handle = FOpen(STRPTR name, int mode, struct hwTagList *tags);
Function
This function is called for every file that Hollywood opens. Your FOpen() implementation has to check whether your plugin wants to handle this file or not. If your plugin wants to handle this file, your FOpen() implementation needs to open it and return a handle to Hollywood. Otherwise FOpen() must return NULL. The handle returned by this function is an opaque data type only your plugin knows about. Hollywood will pass this handle to you whenever it wants to do IO on this file.

The second parameter specifies whether Hollywood wants to open this file for reading and/or writing. It can be one of the following values:

HWFOPENMODE_READ_NEW:
File should be opened for reading. FOpen() must fail if file doesn't exist.

HWFOPENMODE_WRITE:
File should be opened for writing. If it doesn't exist, FOpen() has to create it first.

HWFOPENMODE_READWRITE:
File should be opened for reading and writing.

Additionally, Hollywood will pass a tag list to your implementation in parameter 3. This tag list can contain the following items:

HWFOPENTAG_FLAGS:
This tag allows you to report certain flags about the file back to Hollywood. The pData member of this tag will be set to a pointer to a ULONG. You may then set one or more of the following flags in this ULONG to inform Hollywood about the properties of this file. The following flags are currently recognized:

HWFOPENFLAGS_STREAMING:
Setting this flag tells Hollywood that the file is being streamed from a network source. If this flag is set, Hollywood will try to avoid operations that are inefficient on streaming sources like excessive seeking operations.

HWFOPENFLAGS_NOSEEK:
Setting this flag tells Hollywood that the file cannot be seeked. Note that if you set this flag, you will still have to implement the FSeek() function but it only needs to support rewinding (i.e. reverting the read/write cursor to the beginning of the file) and querying the current file cursor position. Note that if you set HWFOPENFLAGS_NOSEEK several file format handlers which depend on the seek functionality might stop working. Plugins may choose to work-around this problem by setting the HWFOPENMODE_EMULATESEEK flag when calling hw_FOpen(). See hw_FOpen for details.

HWFOPENTAG_CHUNKFILE:
If you've set the HWCLAFAFLAGS_CHUNKLOADER flag to indicate that your file adapter supports opening of virtual files that do not exist physically but only as parts of other files, you can use this tag to find out the path to the real file that contains the virtual file. If Hollywood passes the HWFOPENTAG_CHUNKFILE tag to your FOpen() implementation, the pData member will be set to a string containing the path to the real file Hollywood wants you to open, but keep in mind that Hollywood wants you to look at a part of this file only. This part is described by the HWFOPENTAG_CHUNKOFFSET and HWFOPENTAG_CHUNKLENGTH tags which are always passed alongside HWFOPENTAG_CHUNKFILE. HWFOPENTAG_CHUNKOFFSET specifies the offset where the virtual file inside the file passed in HWFOPENTAG_CHUNKFILE starts and HWFOPENTAG_CHUNKLENGTH specifies its length. Your file adapter implementation must remap all accesses to the virtual file to the physical file specified in HWFOPENTAG_CHUNKFILE then, i.e. if the user calls FSeek() to seek to the beginning of the file, your implementation of FSeek() must actually seek to the position specified in HWFOPENTAG_CHUNKOFFSET and so on. You only need to implement support for HWFOPENTAG_CHUNKFILE if you set LinkMode to HWSTATLKMODE_CONTAINER in FStat(). Otherwise, it's not necessary to implement HWFOPENTAG_CHUNKFILE. See FStat for details.

HWFOPENTAG_CHUNKMEMORY:
This is similar to HWFOPENTAG_CHUNKFILE except that the pData member of this tag doesn't point to a string containing a file path but to a memory block containing the data of the virtual file. You can look at the HWFOPENTAG_CHUNKLENGTH to find out the size of the memory block. HWFOPENTAG_CHUNKOFFSET is not used for this tag. See above for more information.

HWFOPENTAG_CHUNKOFFSET:
If HWFOPENTAG_CHUNKFILE is set, the iData member of this tag will be set to the starting offset of the virtual file inside the physical file specified in HWFOPENTAG_CHUNKFILE.

HWFOPENTAG_CHUNKLENGTH:
If either HWFOPENTAG_CHUNKFILE or HWFOPENTAG_CHUNKMEMORY is set, the iData member of this tag will be set to the length of the virtual file in bytes.

This function must be implemented in a thread-safe manner.

Inputs
name
file to open
mode
desired access mode (see above)
tags
tag list with additional options (see above)
Results
handle
handle to refer to this file later or NULL if your plugin doesn't want to handle this file
Show TOC