This chapter covers the following topics:
To develop applications using the .NET APIs, the following set of modules and tools are required:
The Outside In Technology (OIT) developer's redistributable modules for your product
Visual Studio 2010 or later
NET Framework 4.0 or later
The API libraries:
outsidein.dll - The .NET libraries to access the Outside In technologies
oilink.dll and oilink.exe- The bridge modules between .NET and the C-APIs
Google.ProtocolBuffers.dll - The cross language binary serialization provider
There are two steps in developing applications using the APIs. In the first step, you would need to configure the environment to create your application (typical programming tasks not directly related to these APIs) and in the second step you would generate code to utilize the functionality of these libraries.
To set up the environment to create a .NET application, you would need to add a reference to the Outside In library. In order to use the Outside In components in your application, you need to reference outsidein.dll. (This can be done by using the Add Reference dialog box in Visual Studio.)
The sample application included with the SDK, wv_sample_exporter_cs, is a minimal demonstration of how to use this API.
All the functionality required to perform a conversion is provided in an Exporter object. The basic process of exporting a file involves the following tasks:
To obtain access to the Outside In functionality, you should call the utility function in the "OutsideIn" class. This will provide you an instance of an Exporter Object.
Exporter exporter = OutsideIn.OutsideIn.NewLocalExporter();
If the Outside In binaries (including oilink.exe) are located in a directory other than the one from which outsidein.dll was loaded, the OutsideIn class may need to be told where to find them. (Otherwise you may see an OutsideInException indicating that oilink.exe could not be found.) You can specify the location of the binaries by setting the static property OutsideIn.InstallLocation to the path of the directory where they are installed. This property should only be set once. This property is only available in the .NET APIs in version 8.5.0.1 and beyond.
The Outside In API is highly configurable, and presents numerous options to fine-tune the way a document is exported. Each option has a "set" and "get" method to set or retrieve the currently set value.
exporter.SetPerformExtendedFI(true); int timezoneOffset = exporter.GetTimeZoneOffset();
You are required to specify the source file and the destination file. This is done similarly to setting options using "set" methods.
exporter.SetSourceFile(inputFilename); exporter.SetDestinationFile(outputFilename);
There are other options that can be set at this time to specify the way to handle the input file, such as providing a SourceFormat to provide a mechanism to handle the input file in a different format than that which it is identified as.
The API also supports opening certain types of embedded documents from within an input file. For example, a .zip file may contain a number of embedded documents; and an email message saved as a .msg file may contain attachments. The API provides the means of opening these types of embedded documents. This can be done by opening the parent document and then the embedded document can be opened through this exporter object.
// subdocId is the sequential number of the node in the archive file Exporter exporterNode = exporter.NewTreeNodeExporter(subdocId);
In this step, you specify the output format.
exporter.SetDestinationFormat(FileFormat.FI_HTML5);
Outside In Technology provides callbacks that allow the developer to intervene at critical points in the export process. To respond to these callbacks, you have to subscribe to any messages that you are interested in by overriding the message handlers from the Callback class. After creating an object of this class, set the callback option to this object and the messages will be passed to your object.
class CallbackHandler : Callback
{
… // implementation of messages to handle - described in the API documentation
}
CallbackHandler callback = new CallbackHandler();
exporter.SetCallbackHandler(callback);
Support for redirected I/O is supported through .NET Streams. Streams that are readable and seekable can be used as input files, while streams that are readable, writable and seekable can be used for output.
Using streams is very similar to using standard I/O in the .NET API. To use streams, the stream object is passed as a parameter to the "SetSourceFile" or "SetDestinationFile". When using Output streams, handling callbacks is mandatory when secondary files are expected to be generated.