Working with Lotus automation classes in C++

Lotus automation classes provide a rich toolset for working with Lotus Notes client. If using from VBScript the syntax will be very similar to LotusScript. Even LotusScript documentation can be used to reference available Lotus classes. It can be found in Domino Designer Help or IBM site online.

In this article we will talk about Lotus Notes automation classes such as "Notes.NotesSession" and "Notes.NotesUIWorkspace". These classes were around in Lotus for a long time, since version 5.x, and they are still present in Lotus Notes 8.5, even in Eclipse based standard edition.

There are enough NotesUIWorkspace and NotesSession usage samples available on the Net written in Visual Basic 6.0 and VBA for Microsoft Access and Excel. This article should fill the gap of guides to access Lotus automation classes in C++ and ATL.

The most popular sample in VB is sending an email. I don't have Visual Basic 6.0 installed so I've adopted it to VBScript. Here is a code:

' VB Script Document
' http://lotusdesk.blogspot.com/
option explicit

Dim objSession, objMailDB, objMailDoc

Set objSession = CreateObject("Notes.NotesSession")
Set objMailDB = objSession.GetDatabase("", "")

'Open database if it's not ready
If Not objMailDB.IsOpen Then
objMailDB.OpenMail
End If

Set objMailDoc = objMailDB.CreateDocument

Dim strRecipient
strRecipient = "notescoder@gmail.com"

objMailDoc.Form = "Memo"
objMailDoc.SendTo = strRecipient
objMailDoc.Subject = "Test Subject Line"
objMailDoc.Body = "Some Text"

' Let's set it to True to get a copy in Sent folder.
objMailDoc.SaveMessageOnSend = True

objMailDoc.PostedDate = Now()
objMailDoc.Send 0, strRecipient

Let's do the same in C++. Since Notes.NotesSession, Notes.NotesUIWorkspace and associated interfaces support late binding only we need to use IDispatch method pair GetIDOfName() and Invoke() to access their properties and methods. Luckily ATL provides a class CComDispatchDriver which can handle GetIDOfName() and Invoke() pair for us.

CComDispatchDriver ptrSession;
HRESULT hr = ptrSession.CoCreateInstance(OLESTR("Notes.NotesSession"));
OleRun(ptrSession);

_variant_t serverName(OLESTR("")), fileName(OLESTR(""));
_variant_t varMailDb;
hr = ptrSession.Invoke2(OLESTR("GetDatabase"), &serverName, &fileName, &varMailDb);
if(FAILED(hr))
{
return FALSE;
}
return TRUE;

In this sample we have used ProgId to create NotesSession object. We can declare and use CLSID instead:

// {29131401-2EED-1069-BF5D-00DD011186B7}
static const GUID CLSID_NotesSession = 
{ 0x29131401, 0x2EED, 0x1069, { 0xBF, 0x5D, 0x00, 0xDD, 0x01, 0x11, 0x86, 0xB7 } };

This class identifier didn't change since Lotus Notes 6.0, maybe for earlier version it's also the same. So it's safe to use it. Here is another CLSID for NotesUIWorkspace:

// {29131502-2EED-1069-BF5D-00DD011186B7}
static const GUID CLSID_NotesUiWorkspace = 
{ 0x29131502, 0x2EED, 0x1069, { 0xBF, 0x5D, 0x00, 0xDD, 0x01, 0x11, 0x86, 0xB7 } };

Let's put object creation and OleRun call into a separate function so we can reuse it later for creation of NotesUIWorkspace class:

CComDispatchDriver CreateObject(const CLSID &clsid)
{
CComDispatchDriver ptrDispatch;
HRESULT hr = ptrDispatch.CoCreateInstance(clsid);

if(SUCCEEDED(hr))
OleRun(ptrDispatch);

return ptrDispatch;
}

The final code for sending an email will look like this:

BOOL SendMemo()
{
CComDispatchDriver ptrSession = CreateObject(CLSID_NotesSession);
_variant_t serverName(OLESTR("")), fileName(OLESTR(""));

_variant_t varMailDb;

HRESULT hr = ptrSession.Invoke2(OLESTR("GetDatabase"), &serverName, &fileName, &varMailDb);

if(FAILED(hr))
{
return FALSE;
}

CComDispatchDriver ptrMailDb = (IUnknown*)varMailDb;
_variant_t varIsOpen;
ptrMailDb.GetPropertyByName(OLESTR("IsOpen"), &varIsOpen);
if(!varIsOpen)
{
ptrMailDb.Invoke0(OLESTR("OpenMail"));
}

_variant_t varDoc;
hr = ptrMailDb.Invoke0(OLESTR("CreateDocument"), &varDoc);
if(FAILED(hr))
{
return FALSE;
}

CComDispatchDriver ptrDoc = (IUnknown*)varDoc;
_variant_t varSubject(OLESTR("Test subject"));

ptrDoc.PutPropertyByName(OLESTR("Subject"), &varSubject);

_variant_t varRecipient(OLESTR("notescoder@gmail.com"));
ptrDoc.PutPropertyByName(OLESTR("SendTo"), &varRecipient);

_variant_t varBodyText(OLESTR("Body text"));
ptrDoc.PutPropertyByName(OLESTR("Body"), &varBodyText);

_variant_t varTrue(-1l, VT_BOOL);
ptrDoc.PutPropertyByName(OLESTR("SaveMessageOnSend"), &varTrue);

_variant_t varNow(COleDateTime::GetCurrentTime());
ptrDoc.PutPropertyByName(OLESTR("PostedDate"), &varNow);

_variant_t varZero(0);
hr = ptrDoc.Invoke2(OLESTR("Send"), &varZero, &varRecipient);

return SUCCEEDED(hr);
}

Try to create a simple console application to test the code above. Don't forget to include ATL classes:

#include <comdef.h>
#include <atlbase.h>
#include <atlcom.h>
#include <atlctl.h>
#include <atlcomtime.h>
using namespace ATL;

In the next article we will do the same with visual effects in Lotus Notes client.

Differences between Lotus Notes C API and C++ API

We always have few options if we need to do with Lotus Notes something externally. Here I'll try to provide a brief comparison chart of Lotus Notes CAPI and CppAPI. I hope this brochure can help to do the right choice before going deep into the water.

Lotus Notes CAPI	Lotus Notes CppAPI
Complex code, requires high attention during development because it works with raw memory pointers. So without experience it's very easy to produce memory leaks and access violations.	Simple code, it's very similar to Lotus Script and Java APIs.
Procedural code.	Object oriented code.
Notes uses it internally, so no dependency files required to install.	CppAPI requires lcppnXX.dll, there XX is a version of CppAPI. While this dll has versioning info most functionality is compatible across Lotus Notes versions. So lcppn70.dll is working with Lotus Notes 6.5 and Lotus Notes 8.5.1 Standard.
Can be coded anything so it can work much like it was a built-in feature of Lotus Notes.	There are limitations introduced by CppAPI implementation. It's obvious because CppAPI built on CAPI. In most cases it's the same limitations as in LotusScript or Java API. So if you can't do something in LotusScript and you like to move to a lower level than CppAPI is not your option. A good example of such limitations is a memo with attachment. While it's only few lines of code using CppAPI, this memo doesn't look good in Notes because there is no icon thumbnail, just a gray rectangle. With CAPI there will be 300-400 lines of code to add an attachment and to represent it as an icon inside of memo body. It's complex, but memo will look like the one created in Lotus Notes by a real user.
Strings represented in form of special LN Multibyte string (LMBCS). While in the code it looks like a normal ANSI string of type "char *" it can contain zeros inside and encoded non ANSI symbols. It's very easy to miss a large part of text and break international symbols if you apply standard C functions like strcat or strcpy. I'll write in the next post how to work with Lotus strings in CAPI to preserve international symbols and handle zeros in the middle of the string.	LNString class handles lotus strings just perfect. It has methods for string concatenation, searches, substring extraction, etc. It can return a pointer to the platform one byte character set encoding of the string. However it's still better to convert LMBCS to Unicode if you need to pass it outside of Lotus, and it's missing in CppAPI.

Here is a sample code of the same functionality in Lotus CAPI and CppAPI. The code opens Lotus database.

void CppApiCode()
{
 LNNotesSession session;
 session.Init();
 LNString databasePath = "special\\testdb.nsf";
 LNString serverPath;
 LNDatabase docDB;
 session.GetDatabase(databasePath, &docDB, serverPath);
 // Open the database.
 docDB.Open();
 ...
 docDB.Close();
}

void CApiCode()
{
 STATUS error = NotesInitExtended();
 DBHANDLE hDB = 0;
 char szFileName[] = "special\\testdb.nsf";
 char szServerName[] = "";
 char szDbPath[MAXPATH+1];
 error = OSPathNetConstruct(0, szServerName, szFileName, szDbPath);
 // Open the database.
 error = NSFDbOpen(szDbPath, &hDB);
 ...
 NSFDbClose(hDB);
}