IMPORTANT NOTICE - Apr-30-2009:
This .NET implementation of Okapi is no longer actively developed.
Instead, a NEW JAVA IMPLEMENTATION IS AVAILABLE and is being actively developed.
The material on this Web site is for archive propose. Some applications of the old .NET implementation (e.g. Olifant) will be maintained to some degree until they have a replacement in the Java project.

Okapi Framework

Utility Set Interface Specification

Revision information: Version 1.1
       This revision: [Not available yet]
   Previous revision: [Not available]
     Latest revision: http://okapi.sourceforge.net/IUtilitySet.html

- Document Status
- Overview
- Usage
- Methods

Document Status

This document is a stable specification. Feedback about the content of this document is encouraged. Send your comments to the Okapi Framework administrator, or alternatively to post them in the Okapi Tools users group.

DISCLAIMER: Parts of the documents are generated automatically from the source code documentation of Okapi's implementation of the specification. Because the generation tool is not completely working yet, this may result in incomplete or broken text or links in this document. See the source code documentation of the interface for complete text.

Overview

The Okapi Utility Set Interface is an object model that allow to access in a common way different utilities that provide very different functionalities. This way, a program can easily be set up to call various utilities and even be ready to call utilities that do not exist yet.

Other related specifications:

Usage

The IUtilitySet interface provides a common way of accessing utilities.

Just after creating an object that implements IUtilitySet, you should call the IUtilitySet.Initialize method. At this point you can query how many utilities are available in the set with IUtilitySet.GetUtilityCount, retrieve their identifier with IUtilitySet.GetUtilityIdentifier, and their description with IUtilitySet.GetUtilityDescription.

You can query which utility is currently active using IUtilitySet.GetCurrentUtility, and specify the one to activate by calling IUtilitySet.SetCurrentUtility.

Once the utility that you are going to use is set, you can query it to know what types of data it needs and provide the data: The IUtilitySet.GetInputListCount method indicates how many input lists need to be populated, and IUtilitySet.GetInputListType what type of input (i.e. source or target). Use IUtilitySet.ResetFileLists to empty the lists, and IUtilitySet.AddInput to add new input files. The IUtilitySet.NeedOutput method tells you if the utility needs output information. If so, you can specify that information with IUtilitySet.AddOutput.

The IUtilitySet.SetLanguages method specify the source and target langauges to use. The IUtilitySet.NeedRoot method indicates if you need to specify a root, which you can do with IUtilitySet.SetRoot.

In addition to the generic input data, some utility have options. The method IUtilitySet.HasOptions allows you to check this. IUtilitySet.SetOptions and IUtilitySet.GetOptions sets and gets these parameters, IUtilitySet.SetDefaultOptions resets the options to their default values, and IUtilitySet.EditOptions allows you to modify the options using the editor provided by the utility itself.

Once all options and data are set, call the IUtilitySet.Execute method to excute the utility.

After the process is completed, you can use IUtilitySet.GetLastOutputFolder to retrieve the name of the last output folder used by the utility.

Methods

The Filter Interface provides the following methods:

IUtilitySet.Initialize	Initializes the filter object.
IUtilitySet.GetInterfaceVersion	Gets the version of the IUtilitySet interface the object implements.
IUtilitySet.GetIdentifier	Gets the identifier of the utility set.
IUtilitySet.GetUtilityCount	Gets the number of utilities the set offers.
IUtilitySet.GetCurrentUtility	Gets the identifier of the utility currently active.
IUtilitySet.SetCurrentUtility	Sets the utility currently active.
IUtilitySet.GetUtilityIdentifier	Gets the identifier of a specified utility of the set.
IUtilitySet.GetUtilityDescription	Gets the description of a specified utility.
IUtilitySet.HasOptions	Indicates whether the current utility supports options.
IUtilitySet.SetDefaultOptions	Sets the options of the current utility to their defaults values.
IUtilitySet.GetOptions	Gets the current options of the current utility.
IUtilitySet.SetOptions	Sets the options of the current utility.
IUtilitySet.GetOption	Gets the value of the specified option for the current utility.
IUtilitySet.SetOption	Sets the value for the specified option of the current utility.
IUtilitySet.EditOptions	Edits the current options of the current utility.
IUtilitySet.ResetFileLists	Resets all the lists of input and output files.
IUtilitySet.SetLanguages	Sets the input and output languages.
IUtilitySet.GetOutputLanguage	Gets the current output language.
IUtilitySet.GetInputListCount	Get the number of input lists needed for the current utility.
IUtilitySet.NeedRoot	Queries whether the current utility needs to have a root defined for a specific input list.
IUtilitySet.SetRoot	Sets the root for a specified input list.
IUtilitySet.GetRoot	Gets the current root for a specified input list.
IUtilitySet.GetInputListType	Gets the type of input associated with a specified input list.
IUtilitySet.AddInput	Adds a file to a specified input list.
IUtilitySet.NeedOutput	Indicates whether the current utility needs output files.
IUtilitySet.AddOutput	Adds an output file to the list.
IUtilitySet.NeedOutputEncoding	Indicates whether the current utility needs a default output encoding.
IUtilitySet.Execute	Executes the current utility with the current options and parameters.
IUtilitySet.GetLastOutputFolder	Gets the path of the last output folder.

IUtilitySet.Initialize

Initializes the filter object.

Parameters

Okapi.Library.Base.ILog

p_Log

The log object to use.

Remarks

This method must be called first after the creation of the object.

IUtilitySet.GetInterfaceVersion

Gets the version of the IUtilitySet interface the object implements.

Return

The version of the IUtilitySet interface.

IUtilitySet.GetIdentifier

Gets the identifier of the utility set.

Return

The string that identify the utility set.

Remarks

Use this method to retrieve the identifier of the utility set.

IUtilitySet.GetUtilityCount

Gets the number of utilities the set offers.

Return

The number of utility the set offers.

Remarks

Each utility set must offer at least one utility. Use the IUtilitySet.GetCurrentUtility property to set or retrieve the one currently active.

IUtilitySet.GetCurrentUtility

Gets the identifier of the utility currently active.

Return

The string of the identifier for the current utility.

Remarks

A utility set has only one utility active at a time. Use this method to query which one is currently active.

IUtilitySet.SetCurrentUtility

Sets the utility currently active.

Parameters

String

p_sIdentifier

Remarks

A utility set has only one utility active at a time. Use this method to specify which one is currently active.

IUtilitySet.GetUtilityIdentifier

Gets the identifier of a specified utility of the set.

Parameters

Integer p_nIndex Index of the utility to look-up. The value must be between 0 and IUtilitySet.GetUtilityCount - 1.

Return

The string that identify the specified utility.

Remarks

Use this method to retrieve the identifier of a specified utility. Each utility must have an identifier unique withing the utility set.

IUtilitySet.GetUtilityDescription

Gets the description of a specified utility.

Parameters

Integer p_nIndex Index of the utility to look-up. The value must be between 0 and IUtilitySet.GetUtilityCount - 1.

Return

The description of the specified utility.

Remarks

Use this method to get the short description of a specified utility.

IUtilitySet.HasOptions

Indicates whether the current utility supports options.

Return

True if the current utility supports options, false if not.

Remarks

If this property is true, the current utility uses option. You can set or retrieve the string representation of the options using the IUtilitySet.GetOptions method. You can reset the options to their defailt values by calling the IUtilitySet.SetDefaultOptions method.

IUtilitySet.SetDefaultOptions

Sets the options of the current utility to their defaults values.

Remarks

This method resets the options for the current utility to their default values. You can set or retrieve the string representation of the options using the IUtilitySet.SetOptions and IUtilitySet.SetOptions methods.

IUtilitySet.GetOptions

Gets the current options of the current utility.

Return

The string representation of the current options of the current utility.

Remarks

Use this method to retrieve the string representation of the current options of the current utility. The string can be used for storage for example.

IUtilitySet.SetOptions

Sets the options of the current utility.

Parameters

String

p_sValue

The string representation of the options.

Remarks

The format of the string representation of the options for a given utility are entirely up to the implementer of the utility. The only requirement is that it must be compatible with XML 1.0. That is that no characters prohibited in XML 1.0 are present in the string. The string does not need to be escaped for XML.

If p_sValue is or empty, the options are set to their default values. Calling SetOption(""); or SetOption(null); is the same as calling SetDefaultOptions();.

IUtilitySet.GetOption

Gets the value of the specified option for the current utility.

Parameters

String

p_sName

Name of the option to retrieve. This name is not case sensitive.

Return

The string value of the specified option for the current utility. Returns null if there was no option of that name.

Remarks

Use this method to retrieve individual option values.

IUtilitySet.SetOption

Sets the value for the specified option of the current utility.

Parameters

String	p_sName	Name of the option to set. This name is not case sensitive.
String	p_sValue	The string representation of the value.

Remarks

The value of must be compatible with XML 1.0. That is that no characters prohibited in XML 1.0 are present in the string. The string does not need to be escaped for XML.

If p_sValue is or empty, the option is set to an empty string.

IUtilitySet.EditOptions

Edits the current options of the current utility.

Parameters

System.Boolean

p_bPriorExecution

Indicator if the utility will be executed just after the call to the method.

Return

True is the editing was successful. False if the user cancelled the edit or if an error occurred.

Remarks

Use IUtilitySet.SetOptions or IUtilitySet.SetDefaultOptions to set the options before calling this method. You can the use IUtilitySet.GetOptions to retrieve the options after a successful edit.

The p_bPriorExecution parameter allows you to provide a different user interface (such as an "Execute" button instead of an "OK" button) if the calling program intend to execute the utility just after the method is called. The method itself should not run the utility.

IUtilitySet.ResetFileLists

Resets all the lists of input and output files.

IUtilitySet.SetLanguages

Sets the input and output languages.

Parameters

String	p_sInputLanguage	The code of the input language. The code must be an RFC3066 tag.
String	p_sOutputLanguage	The code of the output language. The code must be an RFC3066 tag.

IUtilitySet.GetOutputLanguage

Gets the current output language.

Return

The RFC3066 code of the current output language.

IUtilitySet.GetInputListCount

Get the number of input lists needed for the current utility.

Return

The number of input lists needed for the current utility.

Remarks

Note that some utilities may not require an input list.

IUtilitySet.NeedRoot

Queries whether the current utility needs to have a root defined for a specific input list.

Parameters

Integer

p_nInputList

Index of the specified input list. The index is zero-based.

Return

True if the current utility requires a root to be set for the specified input list.

Remarks

You can use the IUtilitySet.SetRoot method to specify the root. IUtilitySet.GetCurrentUtility

IUtilitySet.SetRoot

Sets the root for a specified input list.

Parameters

Integer	p_nInputList	Index of the specified input list. The index is zero-based.
String	p_sRoot	path root to set.

Remarks

Use the method to set the root for a specified input list. A call to the IUtilitySet.NeedRoot method will tell you if a root is required. IUtilitySet.NeedRoot

IUtilitySet.GetRoot

Gets the current root for a specified input list.

Parameters

Integer

p_nInputList

Index of the specified input list. The index is zero-based.

Return

The root of the specified input list.

IUtilitySet.GetInputListType

Gets the type of input associated with a specified input list.

Parameters

Integer

p_nInputList

Index of the specified input list. The index is zero-based.

Return

The value 0: for a mandatory input of type source, the value 1: for a mandatory input of type target, the value 2: for an optional input of type source, and the value 3: for an optional input of type target.

IUtilitySet.AddInput

Adds a file to a specified input list.

Parameters

Integer	p_nInputList	Index of the specified input list. The index is zero-based.
String	p_sPath	Full path of the file to add to the list.
String	p_sFilterSettings	Filter settings string associated with the file.
String	p_sEncoding	The name of the encoding of the file. The name must be an IANA charset name. This parameter is used only if the filter cannot detect automatically the encoding of the file.

IUtilitySet.NeedOutput

Indicates whether the current utility needs output files.

Return

True if the utility needs output path information, false otherwise.

IUtilitySet.AddOutput

Adds an output file to the list.

Parameters

String	p_sPath	Full path of the output file to create.
String	p_sEncoding	The name of the encoding of the file. The name must be an IANA charset name. This parameter is used only if the filter cannot detect automatically the encoding of the file.

IUtilitySet.NeedOutputEncoding

Indicates whether the current utility needs a default output encoding.

Return

True if the utility needs output encoding information, false otherwise.

IUtilitySet.Execute

Executes the current utility with the current options and parameters.

Parameters

System.Boolean

p_bAllowPrompts

Indicates if the utility is allowed to prompt the user for various confirmations.

Remarks

This method executes the utility currently active (set using the IUtilitySet.GetCurrentUtility property), with the options currently set (with the IUtilitySet.SetDefaultOptions method or the IUtilitySet.SetOptions property), and all the other input and output parameters specified. All errors, warnings, and messages are directed to the Log you have specified when calling the IUtilitySet.Initialize method.

When p_bAllowPrompts is set to false, the utility should run without prompting the user for any interactive input (such as confirmation of file overwrite, etc.)

IUtilitySet.GetLastOutputFolder

Gets the path of the last output folder.

Return

The path of the last output folder used.