DBXanalyzer API Programmers' Manual

The functions in the DBXanalyzer API allow you to query and extract data from a version 5 or 6 Microsoft Outlook Express DBX file using a variety of programming languages.

In all cases, messages are referenced by an index number between 0 and N-1 where N is the number of messages in the file. There are functions to query the DBX file and find the required index number, and functions to extract information and messages. All functions are read-only as far as the DBX file is concerned, so you cannot damage your email store by using this API.

The actual value of the index is set internally by Outlook Express and bears no relation to any particular order. Do not assume it will remain the same for a given message after the DBX file has been updated. Deleted messages are ignored and cannot be accessed.

Installing

The core executable file is DBXazapi.dll which is a simple Win32 DLL. This file must exist on the user's system for all programming language interfaces. DBXazapi.dll is not registered with Regsvr32 (it can't be). To install, just copy to a directory on the user's system in the library search path. This can be the same directory as the executable that is calling it, or a directory in the PATH environment setting, but the easiest place is the %windows\system% directory which will allow it to be found by anything.

Wrapper DLLs

There are two wrapper executables provided to allow programming access to the core executable. Both require the core Win32 DLL to exist in the library search path.

DBXazCom.dll is an ActiveX DLL which exposes the dbx class to allow programming access from ASP, VBscript and other COM applications including VB. This DLL does require registering. To register, copy the DBXazCom.dll to a convenient folder, open a command-line window, and type
```
REGSVR32 DBXazCom.dll
```
DBXazNet.dll is a .NET Class Library which exposes the Dbx class to allow programming access from C# and VB.NET projects. This file is referenced from your .NET project. It is not registered.

Using with C/C++

To use with C or C++, include DBXazapi.h in your source code and link to DBXazapi.lib.

#include "DBXazapi.h"

The C interface accesses the functions in the core DLL directly and only requires that the Win32 DBXazapi.dll file exists in the system's library search path. See the examples in t_DBXazapi.c and the notes below. The DBXazapi.lib library provided was compiled using MSVC++5 and should work with versions 5, 6, 7, and 8 (2005 Express) of Visual C++.

Borland C++

The lib file distributed with the program is made using MSVC and will not work with Borland C++. With Borland you need to generate a new .lib file directly from the DLL using the IMPLIB utility.

implib DBXazapi.lib DBXazapi.dll

Using with C# and VB.NET

Copy the dotnet DBXazNet.dll library file into a convenient folder.
In your application, add a reference to the library:
1. Project > Add Reference.
2. In the .NET tab, click on the Browse button to find and select the library file DBXazNet.dll.
3. Click on OK and the wizard will add the reference of the class library to your project.
Add the line (for C#)
```
using DBXanalyzer;
```
or (for VB.NET)
```
Imports DBXanalyzer
```
to your code.
Call the methods in the DBXanalyzer.Dbx class. See the list of methods below. Note that all the methods are static methods and so the object does not need instantiation.

Alternatively, with C#, you can just include the source code module DBXanalyzer.cs in your project and there is no need to reference the class library.

Using with VB6 and VBA

You can either use the ActiveX interface or call the core functions directly. The ActiveX interface is easier.

Using the ActiveX Interface

Make sure the core Win32 DLL is installed.
Make sure the ActiveX DLL file is registered on the system.
Set a reference to the DBXazCom.dll ActiveX DLL (Project>References>Browse).
Call the methods in the dbx class.

Calling the core functions directly from VB

Make sure the core Win32 DLL is installed.
Make a reference to the Type Library DBXazapi.tlb.
Call the core functions. Functions that output text data require the string to be pre-dimensioned using the String function. See the source code of DBXazCom for examples and the notes below.

Using with ASP

Make sure the core Win32 DLL is installed.
Make sure the ActiveX DLL file is registered on the system.

Create a server object

Dim oDbx
Set oDbx = Server.CreateObject("DBXazCom.dbx")

Call the methods in the dbx class, e.g.
```
nVersion = oDbx.Version()
```
See Methods.

Methods

The methods in the COM DBXazCom.dbx class and the .NET DBXanalyzer.Dbx class are identical in behaviour. The .NET methods are all static methods. There are no properties; all methods return either a string or an integer in a "one-off" action. Errors are indicated by returning a negative integer or an empty string.

Version: Returns the version number of the core DLL.
Count: returns the number of undeleted messages in the DBX file.
GetSubject: returns a string with the subject line of the indexed message or an empty string on error.
GetTimeReceived: ditto for the time received as a string in the format "yyyy-mm-dd hh:nn:ss"
GetMessageId: ditto for the Message ID.
GetMessage: ditto for the entire text of the message.
MaxTimeReceived: returns a string with the greatest value of time received for all messages in the file.
IndexMaxTimeReceived: returns the index of the message with the greatest time received.
Size: returns the size of the file in bytes.
LastError: returns the last error message. Currently only used for .Find.
ErrorLookup: returns the error message corresponding to the error code.
Find: returns the index of the first message in the file that matches the search criteria or a negative error code. It starts searching at the specified start index.

Functions in Core DLL

Syntax

' ONE-OFF FILE FUNCTIONS
nRet = DBX_Count(strFileName) 
nRet = DBX_GetSubject(strBuf, nMaxChars, nIndex, strFileName) 
nRet = DBX_GetTimeReceived(strBuf, nMaxChars, nIndex, strFileName) 
nRet = DBX_GetMessageId(strBuf, nMaxChars, nIndex, strFileName) 
nRet = DBX_GetMessage(strBuf, nMaxChars, nIndex, strFileName) 
nRet = DBX_Find(strCriteria, nStartIndex, strFileName) 
nRet = DBX_MaxTimeReceived(strBuf, nMaxChars, strFileName) 
nRet = DBX_IndexMaxTimeReceived(strFileName)
nRet = DBX_Size(strFileName)

' GENERAL FUNCTIONS
nRet = DBX_Version() 
nRet = DBX_LastError(strBuf, nMaxChars) 
nRet = DBX_ErrorLookup(strBuf, nMaxChars, nErrCode)

Notes

All core functions return a 32-bit signed integer (a `Long' in VB6 but an `Integer' in VB.NET).
Arguments are either a string or a 32-bit integer value.
Functions that return data in strBuf require that string to be pre-dimensioned beforehand.
Only ANSI characters are supported, not Unicode.
Error codes are generally returned as a negative number.

Functions in the core DLL

DBX_Count: returns the number of undeleted messages in the file strFileName or a negative error code.
DBX_GetSubject: sets strBuf with the subject for the message at nIndex in the file. It returns the number of characters set in strBuf or a negative error code. If called with nMaxChars set to zero it will return the required number of characters.
DBX_GetTimeReceived: ditto for the time received as a string in the format "yyyy-mm-dd hh:nn:ss"
DBX_GetMessageId: ditto for the Message ID.
DBX_GetMessage: ditto for the entire text of the message.
DBX_MaxTimeReceived: sets strBuf as the greatest value of time received for all messages in the file.
DBX_IndexMaxTimeReceived: returns the index of the message with the greatest time received.
DBX_Size: returns the size of the file in bytes.
DBX_Version: returns the version of the DLL using the formula (major x 100 + minor x 10 + release).
DBX_LastError: sets strBuf as the last error message. Currently only used for DBX_Find error message.
DBX_ErrorLookup: sets strBuf as the error message corresponding to nErrCode.
DBX_Find: returns the index of the first message in the file that matches the search criteria. It starts searching at index nStartIndex.

Rules for the search criteria

Expecting a string of similar format to SQL syntax except

no parentheses
only single quotes (') supported

Syntax

[NOT] keyword OP quoted-string (AND|OR [NOT] keyword OP quoted-string)*

OP can be one of the six VB-like relational operators, namely:

	=, >, <, >=, <=, or <>

with no spaces allowed inside the double ones. String must be quoted in single quotes ('). Use backslash (\) to escape single quotes and itself in the string. Examples:-

	"Subject='foo'"
	"Received > '2004-12-31 23:59:59'"
	"Not Received >= '2004-12-31 23:59:59' And Subject='foo'"
	"Received < '2004-12-31 23:59:59' Or Subject='bar'"
	"Received >= '2004-12-31 23:59:59' And Subject='foo' or from= 'bar' "
	"Received < '2004-12-31 23:59:59' Or NOT Subject='bar'"
	"Subject='With \'quotes\' inside'"
	"Subject <> 'foo' OR FROM='bar' AND Received > '2004-12-31'"

The input is parsed from left-to-right and AND has a higher precedence than OR so

a AND b OR c is interpreted as (a AND b) OR c
a OR b AND c is interpreted as a OR (b AND c)
a AND b OR c AND d OR e = (a AND b) OR ((c AND d) OR e)

Supported keywords are:

RECEIVED
SUBJECT
MESSAGEID
TO
FROM
TOADDR
FROMADDR

All keywords and searches are case insensitive. Wildcards (*?) are NOT supported but are implied, so

SUBJECT='foo'

is interpreted as SUBJECT='*foo*' and will find "foo", "Foo bar", "more FOO", "April Fool". The greater-than/less-than operators are only valid for the keyword RECEIVED which compares lexicographically up to length of the search string. This may give weird results for a badly-formed date. Dates must be in the ISO format "yyyy-mm-dd hh:nn:ss" with a single space between the date and time.

Error Codes

The error codes returned by the core DLL functions are as follows:

0=OK, success, no error
1=Cannot open input file
2=Cannot create output file
3=File read error
4=File write error
5=Memory error
6=Invalid handle
7=Data is in wrong format
8=Invalid DBX signature
9=Not a DBX message store
10=Index not in valid range
11=Parsing error
12=Error in criteria
13=No match found

Version 1.1.1. This page last updated 1 January 2008.

David Ireland
DI Management Services Pty Ltd
www.di-mgt.com.au
www.cryptosys.net