APTR handle = FOpen(STRPTR name, int mode, struct hwTagList *tags);
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:
FOpen()
must fail if file doesn't exist.
HWFOPENMODE_WRITE:
FOpen()
has to create it
first.
HWFOPENMODE_READWRITE:
Additionally, Hollywood will pass a tag list to your implementation in parameter 3. This tag list can contain the following items:
HWFOPENTAG_FLAGS:
pData
member of this tag
will be set to a pointer to a ULONG
which contains the flags Hollywood wants to
pass to your plugin. Your plugin may then also set one or more of the following flags
in this ULONG
to inform Hollywood about the properties of the file. Flags marked
as [in]
may be set by Hollywood whereas flags marked as [out]
can
be set by your plugin. The following flags are currently defined:
HWFOPENFLAGS_STREAMING: [out]
HWFOPENFLAGS_NOSEEK: [out]
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.
HWFOPENFLAGS_WONTSEEK: [in]
HWFOPENFLAGS_WONTSEEK
is set, Hollywood can still call FSeek()
to query the current cursor position, to query the file size by seeking to position 0 with mode
set to HWFSEEKMODE_END
or to rewind the file back to 0 so your plugin must be able to handle
those situation. (V10.0)
HWFOPENTAG_CHUNKFILE:
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:
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:
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:
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.
HWFOPENTAG_USERTAGS:
pData
will point to a struct hwUserTagList
containing
a list of user tags passed by the Hollywood script. User tags are a way of
passing additional information from Hollywood scripts to plugin functions.
See User tags for details. (V10.0)
HWFOPENTAG_FORMAT:
pData
will point
to a pointer to a string pointer, i.e. STRPTR*
. Your plugin can set pData
to a null-terminated string containing a format description of the file. Hollywood scripts
will then be able to get this format name by querying the #ATTRFORMAT
attribute on #FILE
.
Note that the string pointer you write to pData
must stay valid for as long as the
file is open. (V10.0)
This function must be implemented in a thread-safe manner.
NULL
if your plugin doesn't
want to handle this file