Understanding the Litgen.dll Interface Interactions
ILITWriter is the main Litgen.dll interface. The creation of a book is driven here. The four types of content
that go into a .lit (publication metadata, CSS stylesheets, text, and images) are accepted by hosts created
by ILITWriter.
Note: The source files must be fully parsed before you run them through Litgen.dll.
The only source files parsed by Litgen.dll are the CSS files.
There can be several dependencies between the different types of content. For example, Litgen.dll must have
already received all the CSS referenced from some textual content before it can correctly process and
encode that content. However, the manifest specified in the metadata can be in any order. (Note that the
spine, not the manifest, determines the sequence of text content. See the OEB specification for more
details.)
Therefore, Litgen.dll needs to dictate the order in which the content streams are submitted. This
order may be radically different than the order in which they were presented in the metadata. After
presenting the metadata, the tool must ask Litgen.dll which streams to present, one at a time. The following
sequence illustrates this concept.
Note: Litgen.dll can be used in a multi-threaded environment, but
multiple threads must not attempt to access Litgen.dll concurrently.
To create a book, the basic sequence of operations is:
- Initialize COM by calling CoInitialize() or CoInitializeEx().
- Load Litgen.dll and create the main interface (ILITWriter) using the CreateWriter() export.
For more information, see CreateWriter Method.
- Register the object to receive message using the following step:
- Call Create() to start the .lit file generation.
- Process the metadata using the following steps:
- Call GetPackageHost()
to get an ILITParserHost.
- Parse the publication metadata, typically the package file, into this host.
Note: Depending on the application, this might be as simple as parsing an OEB package
file (.opf). Alternately, you may need to synthesize the publication data from some other
form of metadata.
- When completed, call
Finish() on
the host, then release the host.
Note: Unlike other hosts, this host does not support the ILITHost methods.
- Process all CSS streams using the following steps:
- Call GetNextCSSHost()
in a loop.
Note: Each time you call this, it gives you an ILITCSSHost to
receive CSS content. You can call ILITHost methods, particularly
GetFilename(), to discover which CSS data to stream in.
- Write() this stream and Finish()
as described in ILITCSSHost's documentation, and release the host.
When there is no more CSS to be handled,
GetNextCSSHost() returns S_FALSE, indicating that the caller must begin processing content streams.
- Process all text streams using the following steps:
- Call GetNextContentHost()
in a loop.
This method gives you an ILITParserHost (the same interface type that was used for the metadata,
though the implementation is, of course, very different) to receive a single content stream.
- Call GetFilename() to find out which stream is expected; parse that stream into the host.
Note: Depending on the application, this may be as simple as parsing an OEB document file, or it may
be a proprietary conversion.
- When completed, call Finish() on the host, then release it.
Note: GetNextContentHost() returns S_FALSE when there are no more text streams, indicating that the caller
must begin processing image streams.
- Process all image streams using the following steps:
- Call GetNextImageHost()
in a loop.
This method gives you an ILITImageHost to receive a single image stream.
- Call GetFilename() to find out which stream is expected,
Write() the data from
that stream into the host, then release the host.
GetNextImageHost() returns S_FALSE when all images are processed.
- Call ILITWriter::Finish() to finalize the file.
Caution: The sequence of operations is enforced; if one of these methods is called out of order, it will return
E_UNEXPECTED.
If any failure is returned from any Litgen.dll method, it is the caller's responsibility to call
Fail(),
so that Litgen.dll can clean up its internal state and delete the incomplete file. If the tool needs to terminate production of a book,
Fail() can be called at any time. After calling Fail(), the ILITWriter should be
released.
Note: Litgen.dll will remain stable. You can immediately call CreateWriter() and start over, if required.
© 2000 Microsoft Corporation. All rights reserved. Terms of use.