InTrust 11.6 - InTrust SDK Reference

InTrust SDK Overview

The InTrust SDK makes InTrust functionality available to applications. At this time, the SDK includes the following components:

• Repository Services API
• Log Knowledge Base API

The InTrust SDK is included in the InTrust Server component and works on any computer where InTrust Server is deployed.

Requirements

If you want to install the SDK separately from InTrust Server, the computer must meet the following requirements (similar to the requirements for InTrust Server):

Required Permissions

To be able to use the features of the InTrust SDK, your code must be run under an account that is listed as an InTrust organization administrator. For details about setting up this privilege, see InTrust Organization Administrators.

Standalone Setup

To install the InTrust SDK separately from InTrust Server, run the INTRUST_SDK.11.6.0.*.*.msi installation package provided to you. It is located in the InTrust\Server folder in your InTrust distribution.

Configuring C# References

To make sure that C# bindings work, enable references to the following COM type libraries:

1. InTrust Environment 1.0 Type Library
2. Repository Record Inserter 1.0 Type Library
3. Repository Services 1.0 Type Library

For each of them, open the properties and set the Embed Interop Types parameter to False.

Repository Services API

This topic describes the API that InTrust provides for repositories. This API lets you do the following:

• Connect to a repository for searching and writing
• Get records from a repository by searching
• Put records in a repository
• Manage repositories:
  • Remove (unregister) them
  • Create them
  • Work with repository properties

The API is implemented as a collection of COM objects that become available after you have installed the InTrust SDK. Use the interfaces described in the topics listed below; call the methods of those interfaces for access to records and repositories.

• Connecting to a Repository
• Getting Records
• Writing Records
• Creating and Removing Repositories
• Repository Record Data Structures
• Event Record Data Structures
• Working with Repository Properties
• Interfaces

Connecting to a Repository

Use the interfaces listed below for access to an InTrust repository. Once you have gained access, you can search for records in the repository (see Getting Records) and write records to it (see Writing Records).

Overview of Repository Access

The following diagram shows the relationships between the InTrust SDK's interfaces used for getting access to a repository. An arrow indicates that an interface returns another interface.

Before you can have access to an InTrust repository, you need to initialize the InTrust environment. For that, create an object that implements the IInTrustEnvironment interface. This object makes the current InTrust organization, its servers and its repositories available to you. The relationships between these items are as follows:

• An InTrust organization provides a single configuration database for one or more InTrust servers.
• An InTrust repository is registered with an InTrust organization, and its entry is contained in the configuration shared by all InTrust servers in the organization.
• Specific InTrust servers manage specific repositories but do not “own” them; however, the organization does.

The IInTrustEnvironment interface provides the environment for working with all available InTrust organizations. You can use two methods to get the organization you need:

1. Get a collection of known organizations (Organizations method of the IInTrustEnvironment interface) and pick the necessary one. This involves working with the IInTrustOrganizationCollection interface. In this case, organizations are discovered by an Active Directory query.
2. Connect directly to an InTrust server by name (ConnectToServer method of the IInTrustEnvironment interface). This involves working with the IInTrustServer interface, which you can use to get the organization that the server is in.

Once you have gained access to an organization, use its interface (IInTrustOrganization3) to get a collection of the repositories in it (IInTrustRepositoryCollection2) and get the repository you are looking for (IInTrustRepository3).

The information above concerns access to regular production repositories. However, a valid file structure with data can also act as an InTrust repository for the purposes of searching and writing, even if it is not included in InTrust configuration. It is called an idle repository. An idle repository has no representation in the InTrust environment, so you need to construct its interface to gain access. For details, see Creating and Removing Repositories.

Examples

If you know the name of the organization for a specific repository, follow the organization → repository chain of access:

{
    IInTrustEnvironment intrust_environment = new InTrustEnvironment();
    IInTrustOrganizationCollection organizations = intrust_environment.Organizations;
    IInTrustOrganization3 intrust_organization = organizations.Cast<IInTrustOrganization3>().Where(x => x.Name == "My Organization").First();
    IInTrustRepositoryCollection2 repositories = intrust_organization.Repositories2;
    IInTrustRepository3 repository = repositories.Cast<IInTrustRepository3>().Where(x => x.Name == "My Repository").First();
}

If you only know the name of a server in the organization, follow the server → organization → repository chain of access:

{
    IInTrustEnvironment intrust_environment = new InTrustEnvironment();
    IInTrustServer intrust_server = intrust_environment.ConnectToServer("My Server");
    IInTrustOrganization3 intrust_organization = intrust_server.Organization as IInTrustOrganization3;
    IInTrustRepositoryCollection2 repositories = intrust_organization.Repositories2;
    IInTrustRepository3 repository = repositories.Cast<IInTrustRepository3>().Where(x => x.Name == "My Repository").First();
}

Details

Use the following interfaces for repository access and related tasks:

• IInTrustEnvironment
• IInTrustOrganizationCollection
• IInTrustOrganization
• IInTrustServerCollection
• IInTrustServer
• IInTrustRepositoryCollection2
• IInTrustRepository3

Getting and Putting Data

The InTrust repository was originally developed to store event log data, and this dictated the design choices that it is based on. However, the repository architecture is flexible enough for storing generic records containing arbitrary key-value pairs. The repository API provides tools for reading and writing both kinds of data.

Importantly, the repository is a document-oriented store. If you need to implement any inter-document relationships, you need to define them at the document contents level.

Overview

The following diagram shows the relationships between the InTrust SDK's interfaces used for reading and writing repository data. An arrow indicates that an interface returns another interface. Dashed lines between interfaces mean they don't return one another, but are used together for particular tasks.

See below for details about building program flow that uses these relationships. For a diagram of how to obtain the IInTrustRepository3 interface, see Connecting to a Repository.

Writing

Whether you want to write generic records or events, first you need access to the IRepositoryRecordInserter or IRepositoryRecordInserter2 interface. Take the following steps:

1. Connect to the repository you need, as described in Connecting to a Repository.
2. Get the IRepositoryRecordInserter or IRepositoryRecordInserter2 interface.
   This interface manages the writing of data to a repository. To obtain it, call the Inserter method of the IInTrustRepository3 interface of the repository you are connected to. A new inserter is created every time you make this call. You should obtain it once and reuse it for all writing to the repository.

For details about the next steps, see the following topics:

• Writing Records
• Writing Events

Reading

Reading data from a repository means searching the repository for it. Search queries use the REL language described in InTrust Customization Kit. For a list of fields that you can use in search queries, see Searchable Event and Record Fields. For some important REL query specifics, see Composing REL Queries.

The data-retrieving functionality of the InTrust repository API is modeled after the push-based notification system used in the Microsoft .NET Framework. Therefore, the API provides similar interfaces (such as IObservable and IObserver).

To perform a repository search

1. Connect to the repository you need, as described in Connecting to a Repository. This gives you access to the IInTrustRepository3 interface.
2. Use the Searcher method of the IInTrustRepository3 interface to get the IInTrustRepositorySearcher interface.
3. Use that interface's Search method to get an IObservable interface.
4. Subscribe to the notification using the IObserver interface.

Example of a helper function (C#):

static void search_events(IInTrustRepository intrust_repository, string query)
{
    IObservable observable = intrust_repository.Searcher().Search(query);
    MyObserver observer = new MyObserver();
    observable.Subscribe(observer, out observer.m_cookie);
}

The repository API also provides a way to perform searches on multiple repositories simultaneously. The IMultiRepositorySearcher interface is provided for this purpose.

To perform a multi-repository search

1. Obtain the IInTrustRepositorySearcher interfaces for the repositories you need.
2. Construct a IMultiRepositorySearcher interface using the IMultiRepositorySearcherFactory interface.
3. In the newly-created interface, specify the interfaces from the first step using the MakeMultiSearchObject method.
4. Use the returned interface as a regular IInTrustRepositorySearcher interface, as described above.

Example of a multi-repository search:

IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("10.30.38.230");
IInTrustOrganization org = server.Organization;
IInTrustEventory evs = org.Eventory;
string eventory_str = evs.Eventory;
IMultiRepositorySearcherFactory multi_searcher_fac = new MultiRepositorySearcherFactory();
IMultiRepositorySearcher multi_searcher = multi_searcher_fac.CreateMultiRepositorySearcher(eventory_str);

The example above involves an explicitly specified log knowledge base (see Log Knowledge Base API for details). To use the default log knowledge base, rewrite it as follows:

IMultiRepositorySearcherFactory multi_searcher_fac = new MultiRepositorySearcherFactory();
IMultiRepositorySearcher multi_searcher = multi_searcher_fac.CreateMultiRepositorySearcher(null);

For details about the next steps, see the following topics:

• Getting Records
• Getting Events

The following interfaces are involved in repository searches:

• IObservable
  
  Enables push-based notification. Implement this interface as the source of discovered records.
• IObserver
  
  Gets push-based notifications. Implement this interface as the search result handler.
• ICookie
  
  Keeps a search active. It is unlikely that you will need to handle this interface directly, but it helps to know that it is involved in searching.