13 Introduction to the .NET API

This chapter is an introduction to the .NET API for XML Export. Outside In .NET is a set of class libraries and Windows DLLs that provides developers an easy interface to create .NET applications using Outside In Technology.

The following topics are covered:

13.1 Requirements

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.

13.2 Getting Started

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.

13.2.1 Configuring your Environment

To setup the environment to create a .NET application, you would need to add references to all the libraries. In order to use the Outside In components in your application, the following component should be referenced: outsidein.dll. (This can be done by using the Add Reference dialog box in Visual Studio.)

13.2.2 Generate Code

The sample application included with the SDK, OITsample, 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:

Create an Exporter object. 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.
Configure the export. 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.
Set the source and primary destination files. You are required to specify the source file and the destination file. This is done similar to setting options using "set" methods.
Set the output type. In this step, you specify the output format.
(Optional) Provide a callback handler. The Outside In Technology provides callbacks that allow the developer to intervene at critical points in the export process. To respond to these callbacks, you would 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.
Run the export. After all the previous steps are completed, you can produce the desired output.

13.2.2.1 Create an Exporter Object

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();

13.2.2.2 Configure the Output

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();

13.2.2.3 Set the Source and Primary Destination Files

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);

13.2.2.4 Set the Output Type

In this step, you specify the output format.

exporter.SetDestinationFormat(FileFormat.FI_HTML5);

13.2.2.5 Provide a Callback Handler

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 next section
 
}
 
CallbackHandler callback = new CallbackHandler();
 
exporter.SetCallbackHandler(callback);

13.2.2.6 Run the Export

After all the previous steps are completed, you can produce the desired output.

exporter.Export();

13.2.3 Redirected I/O Support in .NET

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.