Chat now with support
Chat with Support

InTrust 11.4.1 - InTrust SDK Reference

InTrust SDK Overview Repository Services API Log Knowledge Base API Enumerations Interfaces

Getting Records

A repository search returns data wrapped in a polymorphic IUnknown interface, as described in Getting and Putting Data. To interpret the data as repository records, cast it as IBulkRecord2.

Example (C#)

class MyObserver : IDisposable, REPOSITORYSERVICESLib.IObserver
{
    
public REPOSITORYSERVICESLib.ICookie m_cookie;
    
public MyObserver()
    
{
    
}
    
public void OnDone()
    
{
        
Console.WriteLine("Search done");
    
}
    
public void OnError(int hr, string description)
    
{
        
Console.WriteLine("Search error: {0}", description);
    
}
    
public void OnNext(object data)
    
{
        
if (data != null)
        
{
            
IBulkRecord2 bulk_record2 = (data as IBulkRecord2);
            
List<record2> records = bulk_record.GetRecords().Cast<record2>().ToList<record2>();
            
int record_count = 0;
            
foreach (record2 my_record in records)
            
{
                
++record_count;
            
}
        
}
        
System.Runtime.InteropServices.Marshal.FinalReleaseComObject(data);
    
}
}

For details about what repository records are, see Repository Record Data Structures.

Getting Events

A repository search returns data wrapped in a polymorphic IUnknown interface, as described in Getting and Putting Data. To interpret the data as event records, cast it as IBulkEventWithReadExtensions.

Example (C#)

class MyObserver : IDisposable, REPOSITORYSERVICESLib.IObserver
{
    
public REPOSITORYSERVICESLib.ICookie m_cookie;
    
public MyObserver()
    
{
    
}
    
public void OnDone()
    
{
        
Console.WriteLine("Search done");
    
}
    
public void OnError(int hr, string description)
    
{
        
Console.WriteLine("Search error: {0}", description);
    
}
    
public void OnNext(object data)
    
{
        
if (data != null)
        
{
            
IBulkEventWithReadExtensions bulk_event = (data as IBulkEventWithReadExtensions);
            
List<event_with_read_extensions> events = bulk_event.GetEvents().Cast<event_with_read_extensions>().ToList<event_with_read_extensions>();
            
int event_count = 0;
            
foreach (event_with_read_extensions my_event in events)
            
{
                
++event_count;
            
}
        
}
        
System.Runtime.InteropServices.Marshal.FinalReleaseComObject(data);
    
}
}

For details about what event records are, see Event Record Data Structures.

Composing REL Queries

REL is an expression language developed specifically for InTrust, and it is used for multiple purposes besides repository searching.

The following topics about REL in the InTrust Customization Kit contain information that is fully applicable to queries used for searching in repositories:

However, due to the specifics of how repositories operate, there are some limitations on what you can include in your queries and nuances that affect performance. These peculiarities have to do with the following:

  • Use of punctuation in field values
  • Whether "equals" or "contains" semantics are used

Punctuation and Other Non-Alphanumeric Characters

Some characters, such as curly braces and the hyphen, are treated in a special way by the repository indexing engine. A query that includes these characters is automatically transformed during an indexed search, even though the query itself may be perfectly valid. The indexing engine splits the query into substrings at these characters and uses the substrings to make the clauses of an AND expression.

As a result, these characters are effectively removed from the index. This affects how well irrelevant data is filtered out and, consequently, how fast queries are evaluated. The following is a list of such characters:

- \ & { } ( ) [ ] < > , ! ? .

You can deal with this limitation in the following ways:

What you can do

Comments

Do nothing; leave the characters where they are.

Your query will be transformed automatically so that the indexing engine filters out as much of the repository as it can before running the search. However, punctuation characters are not part of the index, so the expected values may not be the only ones that match. A lot of similar but irrelevant matches can be present in the results.

How fast your query runs and how relevant its results are depends on how many distinctive alphanumeric substrings it contains besides the punctuation:

  • If your query is made up of strings that have low chances of occurrence, your search will be fast and the results will be mostly relevant.
  • If your query contains strings that occur all the time, your search will be slow and the results will not be very useful.

Pick different fields to match by; ones that can contain only alphanumeric characters.

You can achieve maximum search performance, but it can be difficult or impossible to find equally relevant fields.

"Equals" Versus "Contains"

In a repository search, a query that uses "equals" semantics (the striequ REL function) is always evaluated faster than a similar query using "contains" semantics (the substr REL function). Queries with "does not equal" semantics are even slower.

Regular expressions (the regexp REL function) are slowest.

Searchable Event and Record Fields

This topic lists the field names that you can use in your REL queries when you search for events or records in a repository using the IObservable and IObserver interfaces.

The results of a search are polymorphic and can be cast to events or records as necessary. In addition, you can treat the contents of the repository as either events or records and use either event field names or record field names. However, you cannot mix event and record field names in the same query.

For example, if your repository contains custom records with filled-in insertion strings, it is convenient to treat the records as events for easy access to insertion string contents (see Insertion Strings below).

Event Fields

Field

Details

__AnyField

Look for the specified pattern in all fields.

Category

A symbolic representation of the event category. Search pattern example:
"(\\b|\\W|^)security"

Computer

The computer where the event was logged.

Environment

Internally, InTrust predefines two environment ID values:

  • 8EAF6C85-D1FF-4CFD-9D90-64944C8E6B3E
    Unix Network Environment
  • 9E442BEE-EAC2-4D79-9013-053FB225CFD0
    Microsoft Windows Network Environment

Custom environment IDs can also occur.

EventID

 

PlatformID

Internally, InTrust predefines the following platform ID values:

  • 500
    Microsoft Windows
  • 610
    Solaris
  • 620
    HP-UX
  • 630
    Linux
  • 640
    IBM AIX

Custom platform IDs can also occur.

Source

The subsystem or service that the event is related to. For example, in forwarded Syslog events the source is "Syslog Device".

SourceComputer

The computer where the event originated; this can be different from the computer where it was logged.

SourceDomain

The domain of the computer where the event originated, if applicable.

Time

The timestamp in the event.

Tip: Use filtering by date in your REL queries whenever the date range is known. This speeds up searches considerably.

Type

The predefined types are Information, Warning, Error, Failure Audit and Success Audit.

UserDomain

The domain of the user who produced the event.

UserName

The name of the user who produced the event.

VersionMajor

The major operating system version number of the computer on which the event occurred. For example, the major version of Windows 7 is 6.

VersionMinor

The minor operating system version number of the computer on which the event occurred. For example, the minor version of Windows 7 is 1.

What

A brief description of what the event is about.

Where

The computer where the event happened (had effect).

Where_From

The name or IP address of the computer from which the activity (such as a logon or configuration change) was performed. This is not necessarily the same computer as the one where the activity had effect.

Who

The plain user name of the account that caused the event.

WhoDomain

The Active Directory domain of the account that caused the event, where applicable.
Whom The user account that was affected by the event, where applicable.

Insertion Strings

To look in insertion strings and resolved insertion strings, respectively, use the following field names:

  • InsertionStringN
  • ResolvedInsertionStringN

where N is the number of the string.

Examples of REL expressions:

in( InsertionString10, "rei", "(\\b|\\W|^)is1608133597" );

striequ(ResolvedInsertionString2,"is");

Record Fields

Most of the fields defined in the record data structures (see Repository Record Data Structures) can be used in search queries:

  • directory_tag_1
  • directory_tag_2
  • directory_tag_3
  • directory_tag_4
  • field_1
  • field_3
  • field_4
  • file_tag_1
  • file_tag_2
  • file_tag_3
  • file_tag_4
  • formatting_record_field
  • string_field_1
  • string_field_2
  • string_field_3
  • string_field_4
  • string_field_5

Note that some fields contain integers and others strings.

Examples of REL expressions:

field_1 = 123;

striequ(directory_tag_1,"blue");

striequ(formatting_record_field,"green");

striequ(string_field_1,"cerise");

file_tag_1 = 5385;

 

Related Documents