Office Compatible 97—Outlook Journaling

by Ross Comer
Development Lead, Microsoft Office Compatible

June 1996

Abstract

This article provides a detailed description of the Outlook Journaling feature of Office Compatible and the steps necessary to implement this feature into your custom application. It also provides sample code for both a C/C++ interface and an OLE Automation interface accessible from Visual Basic or Visual Basic for Applications.

Description

Outlook Journaling allows you to create applications that interact with Outlook. Journaling creates a log when a user creates, opens, closes, routes, prints, sends, or posts a document. By recording this information, the Outlook journal allows a user to keep track of, or find, files based on when they worked on the file rather than file name,type, or where the document is stored. 

Registry Settings

In order to use this feature, the application must register in the following location.

HKEY_CURRENT_USER\Software\Microsoft\Shared Tools\Outlook\Journaling 

Under this registration location, add a key for your application.

Key: AppName

Within this key, set the following values.

Description=Name REG_SZ
Enabled= 1 REG_DWORD                             //* this should be set on *//
AutoJournaled=1 REG_DWORD                   //* required by Outlook *//
Large Icon=<path>Name.exe,1 REG_SZ
Small Icon=<path>Name.exe,1 REG_SZ

C Interface

Get the Outlook Interface from the IOfficeCompatible interface with the PioutGetOutlook() call.  If the result of this call is non-NULL, the call succeeded and you are holding the Outlook interface.

The Outlook interface is automatically released when the IOfficeCompatible interface is released. There is no need to do any other releases on this interface.

IMsocOutlook Interface

Use this call to create a new journal entry.

   //    wzFileName is NULL for New docs 
   //    and is the full path to Opened docs
   IMsocOutlookJournalEntry *PiojeCreateOutlookJournalEntry(LPCWSTR wzFileName);

   BOOL GetLoggingState();
   void SetLoggingState(BOOL fState);

IMsocOutlookJournalEntry Interface

Once you have created a journal entry, use the following methods to set the disposition of the file or the action taken by the user.

Use this method to indicate the document has been saved by the user.

   // filename can be null for Save if and only if
   // a valid filename was supplied on creation
   HRESULT Save(LPCWSTR wzFileName);

Use this method to indicate the document has been closed by the user.  Once you have called the Close or CloseProps method, the Journal object is released.

   HRESULT Close(LPCWSTR lpwzAuthor, LPCWSTR lpwzKeyWords, 
      LPCWSTR lpwzManager, LPCWSTR lpwzCompany);

   // Use this call if you are using C++
   HRESULT Close(IMsocDocProps *pMsocDocProps);
   // Use this call if you are using C
   HRESULT CloseProps( IMsocDocProps *pMsocDocProps); 

The following functions log the named event in the Outlook journal entry.

   HRESULT Route();
   HRESULT Print();
   HRESULT Send();
   HRESULT Post();

Sample C Code

// Get the OfficeCompatible interface
IOfficeCompatible *pOC = CreateOfficeCompatible(L”SampleApp”, L”SampleApplication”)

if (pOC != NULL)
   {
   // Get the Outlook interface
   IMsocOutlook *pOutlook = pOC->PioutGetOutlook();

   if (pOutlook == NULL)
      return();

   pOutlook->SetLoggingState(TRUE); // turn on logging

   IMsocOutlookJournalEntry *pJournalEntry = PiojeCreateOutlookJournalEntry(wzFileName);

   if (pJournalEntry == NULL)
      return();

   pJournalEntry->Print();

   pJournalEntry->Save(wzFileName);

   pJournalEntry->Close(L“Author”, L“”, L”Manager”, L”Microsoft”);

   pJournalEntry = NULL;
   pOutlook = NULL;
   }

Automation Interface

The Outlook Journal is also available through the Office Compatible Automation interfaces.

The Outlook object allows creation of a journal entry.

Outlook
   properties
      Application - returns the application object
      Parent - returns the application object
      Logging - Boolean, set or return the logging state

   methods
      // FileName should contain the name of a file that was opened
      // FileName should be blank for a New file
      CreateJournalEntry([opt]fileName) - creates a JournalEntry object for fileName

For a Journal Entry object, use the following properties and methods to set the information logged into the Outlook journal entry.

JournalEntry 
   properties
      Application - returns the application object
      Parent - returns the application object
   methods
      Save(fileName) - Marks the document as being saved
      Printed - Logs the document as being printed
      Route - Logs the document as being routed
      Send - Logs the document as being sent (mailed)
      Post - Logs the document as being Posted to Exchange

This call closes the journal document.  After this call, the journal object is no longer available.

      Close([opt]author, [opt]keywords, [opt]manager, [opt]company, [opt]docProps)

Sample VB Code

   Set OC = CreateObject("OfficeCompatible.Application")
   If OC Is Nothing Then Exit Sub
    
   On Error Resume Next
   OC.Init "OCBSamp", "Office Compatible Basic Sample App"

   If (Err.Number <> 0) Then
      Set OC = Nothing
      On Error GoTo 0
      Exit Sub
   End If
        
   Set Outlook = OC.Outlook
   If (Err.Number <> 0) Then
      Set OC = Nothing
      On Error GoTo 0
      Exit Sub
   End If

   Set JournalEntry = Outlook.CreateJournalEntry() ‘ Create a New JournalEntry
   If (Err.Number <> 0) Then
      Set OC = Nothing
      On Error GoTo 0
      Exit Sub
   End If

   JournalEntry.Print  ‘ Mark the document as having been printed
   JournalEntry.Save(fileName)   ‘ Mark the document as having been saved

   JournalEntry.Close(“Author”)    ‘ Close the document and update the author property
   Set JournalEntry = Nothing