C API programming for Lotus Notes/Domino

Learn the ins and outs of programming using Lotus Notes/Domino C APIs. This article explains some important features found in the c api toolkit and provides some application examples that can meet your needs.
Using Lotus C APIs for Lotus Notes/Domino often reminds people of an easy-to-use vintage swiss army knife: a trendy toolbox that contains many untitled ented useful parts! This article aims to focus on some functions of Lotus c api for Lotus Notes/Domino, and help developers discover its unlimited potential usage. Having a basic understanding of Lotus Notes/Domino and familiarity with programming languages is sufficient for the content of this article. The application knowledge of C programming language can help you better understand some of the concepts we discuss.

Introduction to Lotus c api Toolkit

You can download the lotus c api toolkit for Lotus Notes/Domino on the Toolkits & drivers page. The purpose of this article is to use this toolkit for Lotus Notes/Domino 6.5 on Windows. After decompressing these files in the downloaded files, you can obtain the files, header files, library files, compiled OBJ files, sample programs, and databases used in the examples.

The document contains a user guide and a reference guide, which appear in the form of a separate Notes database. You can get a lot of information from the document. In addition, the User Guide describes the tasks that can be completed using the toolbox and how to complete these tasks. The reference guide records all available functions. Please carefully consider the large amount of information contained in these databases, which is useful for creating full-text indexes for the database, so that you can quickly and accurately search.

The header file can be found in the include folder. They contain definitions of constants, structures, macros, and common functions that can be used as part of the Toolbox. You need to include the corresponding header file in the source code according to the API call used in the program. Library files and compiled OBJ files can be found in the Lib folder in a specific folder of different operating systems. Because the Lib file needs to be linked to the DLL import library of the API program, the OBJ file is the bootstrap object required to use the program at the notesmain entry point or to complete the plug-in server task. (We will review the content later in the article .)

The sample folder provides a detailed list of sample programs. The notedata folder usually contains all the databases used in the sample program. Each function or symbolic value is described in the Reference Guide, which can be referenced by at least one sample program. You can refer to the Reference Guide to learn how to use the function to be checked in a real program.

After understanding what we have to do, the best way to continue studying the toolbox is to look into a practical program. In the next section, we will study the toolbox by traversing two different programs.

 

Back to Top
 

Create a simple program

Let's start with a simple program: a program that outputs the full path of the notes data directory. First, let the C library required by the program contain the header file:

# Include <stdio. h> # include <string. h>
Next, add the header file from Lotus c api for Lotus Notes/Domino:

# Include <global. h> # include <osfile. h>
Now, the task of the main function is to call the notesinitextended () function to initialize the notes Runtime Library. Unless you use the notesmain () function instead of the main () function, you must explicitly call the notesinitextended () function:

Int main (INT argc, char * argv []) {char datadir [256]; Status error = noerror; Word wlength; If (error = notesinitextended (argc, argv )) {printf ("/n unable to initialize notes. /n "); Return (1 );}
 

Finally, we get the data directory and output it. Osgetdatadirectory () is the main Lotus c api function used in this program. As the name implies, osgetdatadirectory () contains the full path of the data directory. The notesterm () function closes the notes Runtime Library to end the function operation. This function must be explicitly called only when notesinitextended () is used to start the Runtime Library:

Wlength = osgetdatadirectory (datadir); If (wlength> 0) printf ("/n the data directory is % s", datadir); notesterm (); Return (0 );}
 

Compilation and link

Next, we will compile and link the program we just compiled. Therefore, make sure that the environment is correctly set up. Of course, the most important requirement is to install matching versions of Lotus Notes and Lotus c api toolkit for Lotus Notes/Domino. In addition, the Microsoft Visual C ++ development environment and Microsoft C/C ++ compilers and libraries provided along with the environment are also required. Finally, we need to set three environment variables:

The PATH variable value should contain the notes program directory and the Microsoft C compiler directory.
The include variable should contain the include directory and Microsoft C include directory required for Lotus c api installation.
The LIB variable should contain the lib directory and Microsoft C lib directory for Windows 32 platform for Lotus c api installation.
 

If you prefer to dynamically install environment variables, you can use a batch file. The following is an example batch processing file:

@ Echo offrem *** comments: REM *** C:/Lotus/notes is the program directory for Lotus Notes 6.5; REM *** C: /program files/Microsoft Visual Studio/vc98/is the REM *** directory where Microsoft Visual C ++ is installed; and REM *** C: /notesapi is the directory where the lotus c api for REM *** Lotus Notes/Domino 6.5 is installed. set Path = .; c:/program files/Microsoft Visual Studio/vc98/bin; C:/program files/Microsoft Visual Studio/vc98 /.. /common/msdev98/bin; C:/program files/Microsoft Visual Studio/vc98 /.. /common/tools; C:/Lotus/notesset Lib = C:/program files/Microsoft Visual Studio/vc98/LIB; C: /program files/Microsoft Visual Studio/vc98/platformsdk/LIB; C:/program files/Microsoft Visual Studio/vc98/mfc/LIB; C: /notesapi/lib/mswin32set include = .; c:/program files/Microsoft Visual Studio/vc98/platformsdk/include; C:/program files/Microsoft Visual Studio/vc98/include; C: /program files/Microsoft Visual Studio/vc98/ATL/include; C:/program files/Microsoft Visual Studio/vc98/mfc/include; C:/notesapi/include
 

Nmake Tool

After running the batch file, the environment for compiling and linking the program is ready. The nmake tool is a part of Microsoft Visual C ++ installation and is easy to use here. Provide a mak file for the tool to "CREATE" applications for you. The Mak file specifies the products that can be delivered, their attributes, and the commands for building these deliverable products (if they do not exist or are older than the products they belong ). Let's call the constructed program simple. C. The following is an example of a mak file that can be used to build simple.exe:

# Comment: # The Mak file for simple. C-a simple Notes API program! Include <ntwin32.mak> # the name of our program. progname = simple # deliverables and dependencies $ (progname ). EXE: $ (progname ). OBJ $ (progname ). OBJ: $ (progname ). C # compile our program. c. OBJ: $ (CC) $ (cdebug) $ (cflags) $ (cpuflags)/DNT $ (cvars) $ *. C # link our program. OBJ. EXE: $ (Link) $ (linkdebug) $ (conflags)-out :$ @$ ** $ (conlibs)/notes. lib user32.lib
 

To check the options that can be used with the nmake tool, run the nmake-HELP command. The command used to build the simple.exe program for the output data directory is as follows:

Nmake/f Simple. Mak/
Simple. Mak is the Mak file we created earlier. The/A option specifies everything we want to build:

Notesmain () function

You can use the notesmain () function as the entry point to write the same program. The only difference is that we don't have to call notesinitextended () and notesterm () as in the previous example (). The following is the function:

/* Simple program to find the data directory using the lotus c api for Lotus Notes/Domino using notesmain () as the entry point * // * include header files that we need from the C library */# include <stdio. h> # include <string. h>/* include header files that we need from the lotus c api for Lotus Notes/Domino */# include <global. h> # include <osfile. h>/* functions defined in this file */void apierrhandler (Status);/* The notesmain () function */status lnpublic notesmain (INT argc, char far * argv []) {/* local variables */Char datadir [256];/* The data directory for Lotus Notes */status error = noerror; /* return type for most Lotus c api functions for Lotus Notes/Domino-defined in global. H */word wlength;/* unsigned integer-defined in global. H * // * Get the full path of the data directory which is returned by the osgetdatadirectory () function in the text buffer whose address is passed in as the argument. the function return value is the length of the buffer returned. */wlength = osgetdatadirectory (datadir);/* print the data directory path. */If (wlength> 0) printf ("/n the data directory is % s", datadir); Return (noerror );}
 

If you think this function has changed the Mak file, you are right. Do you still remember the bootstrap object we talked about before? Here, we need to use this object. Therefore, the Mak file changes the Bootstrap program to the following:

# Comment: # The Mak file for simplever2.c-a simple Notes API program that uses notesmain ()! Include <ntwin32.mak> # the name of our programprogname = simplever2 # deliverables and dependencies $ (progname ). EXE: $ (progname ). OBJ $ (progname ). OBJ: $ (progname ). C # compile our program. c. OBJ: $ (CC) $ (cdebug) $ (cflags) $ (cpuflags)/DNT $ (cvars) $ *. C # link our program (notice the bootstrap object ). OBJ. EXE: $ (Link) $ (linkdebug) $ (conflags)-out :out @ $ ** notes0.obj $ (conlibs)/notes. lib user32.lib
 

 

Back to Top
 

A more complex example

Let's move to a slightly larger program, which uses more Lotus C APIs than in the simple example. This program will look for a name in the local address book. If the name is valid, return the office phone number and address. Does that sound interesting? As usual, we will start with the header file of library C required by the program, and then the header file from Lotus c api:

# Include <stdio. h> # include <string. h> # include <global. h> # include <nsfdb. h> # include <nif. h> # include <osmem. h> # include <miscerr. h> # include <osmisc. h>
 

In this program, we added another function for error handling. Here, we need to declare its prototype and start with the main () function. Of course, in the main () function, all local variables are declared. You need to find out the purpose of each variable when building the program. Next, initialize the notes Runtime Library:

Void apierrhandler (Status); int main (INT argc, char * argv []) {char * dbname = "names. NSF "; char * viewname =" ($ users) "; char firstname [256] =" "; char lastname [256] =" "; char key [256]; dbhandle; notehandle; noteid viewid; hcollection collhandle; collectionposition collpos; handle bufferhandle; noteid * NID; DWORD count; DWORD matches; DWORD whichnote = 0; Status error = noerror; word flg; bool found; char * itemname = ""; char itemvalue [256]; Word itemlen; If (error = notesinitextended (argc, argv )) {printf ("/n unable to initialize notes. /n "); Return (1 );}
 

We need to use the command line for this program to find <firstname> <lastname>. Therefore, make sure that it contains a large number of expected command line parameters:

If (argc! = 3) {printf ("the syntax is: Lookup <firstname> <lastname>"); notesterm (); Return (1);} else {strcpy (firstname, argv [1]); strcpy (lastname, argv [2]); strcpy (Key, firstname); strcat (key, ""); strcat (Key, lastname ); printf ("/ncontact information for % s:", key); printf ("/n --------------------------------------------");}
 

Next, you need to open the address book and process it. The nsfdbopen () function is as follows:

If (error = nsfdbopen (dbname, & dbhandle) {apierrhandler (error); notesterm (); Return (1 );}
 

Read ($ users) design records

After processing the database, you need to use the nifopencollection () function to obtain the Design Record of the view ($ users. The nifopencollection () function processes the document set based on view records. If an error occurs in any of the two operations, you need to close the database and exit:

If (error = niffindview (dbhandle, viewname, & viewid) {nsfdbclose (dbhandle); apierrhandler (error); notesterm (); Return (1 );} if (error = nifopencollection (dbhandle, dbhandle, viewid, 0, nullhandle, & collhandle, nullhandle, null, nullhandle, nullhandle) {nsfdbclose (dbhandle); handle (error ); notesterm (); Return (1 );}
 

Search name

Now we need to find the name you want to view in the set. Nifopencollection () searches for a set based on the primary category key, which is the first column of the view. (Views must be classified .) If this name is found, it is placed before the pointer to the collectionposition to be checked. If an error occurs during the function running, it means that the name does not exist or there are other errors:

Error = niffindbyname (collhandle, key, find_case_insensitive | find_first_equal, & collpos, & matches); If (ERR (error) = err_not_found) {printf ("/Nno such name in the address book. /n "); nifclosecollection (collhandle); nsfdbclose (dbhandle); notesterm (); Return (0) ;}if (error) {nifclosecollection (collhandle); nsfdbclose (dbhandle ); apierrhandler (error); notesterm (); Return (1 );}
 

You can call the nifreadentries () function to obtain the noteid of the document you are interested in. This function places the required information in bufferhandle, and we will allow its pointer to enter. In addition, we will ignore some parameters not required in the context (such as Count and flg ). However, if you expect that the returned information in the buffer zone is not insignificant in size, you need to close the call to nifreadentries () in a loop and test the flg parameter value. If there is too much data to put them in the buffer, set the signal_more_to_do bit in the flg parameter. If the buffer is null after the function returns, exit:

If (error = nifreadentries (collhandle, & collpos, (Word) (navigate_current), 0l, navigate_next, matches-whichnote, read_mask_noteid, & bufferhandle, null, null, & count, & flg) {nifclosecollection (collhandle); nsfdbclose (dbhandle); apierrhandler (error); notesterm (); Return (1);} If (bufferhandle = nullhandle) {nifclosecollection (collhandle); nsfdbclose (dbhandle); printf ("/nempty buffer returned by nifreadentries. /n "); notesterm (); Return (0 );}
 

Now that we have obtained the noteid of the record we want to obtain, we can open it. First, use the oslockobject () function to lock the buffer in the memory and obtain its address. I can forcibly convert noteid to noteid:

Nid = (noteid *) oslockobject (bufferhandle); If (error = nsfnoteopenext (dbhandle, NID [0], 0, & notehandle) {osunlockobject (bufferhandle ); osmemfree (bufferhandle); nifclosecollection (collhandle); nsfdbclose (dbhandle); apierrhandler (error); notesterm (); Return (1 );}
 

Almost done! Now, all we need to do is check whether the address and phone number exist. If so, output them. You can use nsfitemispresent () to check whether these items exist and use nsfitemgettext () to obtain the values of these items:

Found = false; itemname = "mailaddress"; found = nsfitemispresent (notehandle, itemname, (Word) strlen (itemname); If (found) {itemlen = nsfitemgettext (notehandle, itemname, itemvalue, sizeof (itemvalue); printf ("/nmail address: % s", itemvalue);} else {printf ("/Nno mail address Found ");} found = false; itemname = "officephonenumber"; found = nsfitemispresent (notehandle, itemname, (Word) strlen (itemname); If (found) {itemlen = nsfitemgettext (notehandle, itemname, itemvalue, sizeof (itemvalue); printf ("/noffice phone number: % s", itemvalue);} else {printf ("/Nno office phone number found ");}
 

Stop the function operation by unlocking the buffer and releasing its memory, and then disabling records, collections, and databases:

Osunlockobject (bufferhandle); osmemfree (bufferhandle); If (error = nsfnoteclose (notehandle) {nifclosecollection (collhandle); nsfdbclose (dbhandle); handle (error); notesterm (); return (1) ;}if (error = nifclosecollection (collhandle) {nsfdbclose (dbhandle); apierrhandler (error); notesterm (); Return (1 );} if (error = nsfdbclose (dbhandle) {apierrhandler (error); notesterm (); Return (1) ;}notesterm (); Return (0 );}
 

The last difficulty is the apierrhandler () function. This function obtains the strings related to the passed errors and outputs these strings.

Void apierrhandler (status error) {status errorid = err (error); char errorstring [200]; Word Len; Len = osloadstring (nullhandle, errorid, errorstring, sizeof (errorstring )); printf ("encountered this error: % s", errorstring );}
 

You may have noticed the mode named after the lotus c api function. All functions whose names start with NSF must use databases, records, or items. Functions Whose names start with NIF are usually used to process views and sets. The function name used to process operating system-level information (such as locked objects in memory) starts with OS. This naming convention is useful when you look for a function that matches the information you want to archive.

You can download the complete program described in this section from sandbox.

Useful Lotus c api options

Lotus C APIs are useful in the client and server context. In this section, we will focus on some available options.

Design Elements

By using Lotus C APIs, you can create and manipulate design elements such as proxies, forms, views, and navigators. When creating a design element, the note_class_xxx value is very important because it recognizes the type of the record we will create. Note_class_document is used for documents, note_class_form is used for forms, note_class_view is used for views, note_class_filter is used for proxies and macros, and so on. For example, you can use the following function call to create a view design record:

Word classview = note_class_view; nsfnotecreate (HDB, & hnote); nsfnotesetinfo (hnote, _ note_class, & classview );
You can even use the nsfformulacompile () and nsfcomputeevaluate () functions to compile and evaluate formulas.

Server plug-in task

You can create a server task running on the server, just like creating other tasks. Although the plug-in task can be executed and exited, the plug-in task is usually used for operations that require regular execution. Lotus c api provides some specific functions used to build plug-in tasks. The main entry point of this program is the addinmain () function. The addinidle () function is used to control the main loop in a program.

Addindayhaselapsed (), addinminuteshaveelapsed (), and addinsecondshaveelapsed () can help users determine whether regular operations are performed. You can use the <taskname> Server Load balancer to manually start and stop the plug-in task from the service console and tell <taskname> to exit the command. By adding the program name to the servertasks variable value in the notes. ini file of the server, you can also set the plug-in task to automatically start and close as the server is turned on.

Customizes the actions menu Program

You can add your operations to the menu option actions of the Notes client. To do this, the entry point must be a function in the following format:

Namresult lncallback functionname (word wmsg, long lparam)
This function can have any name, but it must be declared by the ordinal value 1 in the exports function of the module definition (DEF) file. The first parameter indicates the operation to be executed, and the second parameter indicates the operation-specific information. This operation can have the following values:

Namm_initnamm_initmenunamm_commandnamm_term
 

Namm_init indicates that an Action menu item can be added now. Namm_initmenu allows a program to modify menu items, such as those that can be used or disabled. Namm_command indicates that the Action menu item has been selected, and now you can perform related operations. Namm_term provides an opportunity to execute an end operation (such as releasing memory.

Calendar and Scheduling

Lotus c api provides the ability to perform calendar and scheduling operations, such as creating calendar entries or searching for busy business periods. Creating calendar entries (such as meetings, appointments, memos, and all-day events) involves using the nsfnotecreate () function to create a record in the required mail database, add the required calendar items to the record.

You can use the schretrieve () function to retrieve the time table of a user at a specific time. You can use the schcontainer_getfirstschedule () function to retrieve the first time table object. Then, use the schedule_extractfreetimerange () function to retrieve the idle time in the time range of the scheduled object, or use the schedule_extractbusytimerange () function to obtain the busy time in the time range of the scheduled object.

 

Back to Top
 

Extensionmanager

The following is a special service provided by Lotus c api: Extension Manager. It allows you to run custom processes before or after some notes or Domino operations by registering callback routines. The entry point of the program should be a function in the following format:

Status lnpublic functionname (void)
This function can have any name, but it must be declared by the ordinal value 1 in the exports function of the module definition (DEF) file. The callback function must have the following format:

Status lnpublic functionname (emrecord far * pexrecord );
Before registering a callback routine, it is useful to use the emcreaterecursionid () function to obtain a recursive ID. If the extension has been called, this can prevent the same extension from being called again, so we recommend that you do this. The emregister () function is used to register callback routines. This can be illustrated using an example:

Emregister (em_nsfdbclose, em_reg_before, (emhandler) ghandlerproc, grecursionid, & hhandler );
 

The first parameter is em_nsfdbclose, which recognizes the callback operation we want to register. The second parameter is em_reg_before, which indicates that we want to run the program before calling the operation. Therefore, the program is called as long as the nsfdbclose () operation is called, and the nsfdbclose () operation is used to close the database. There are many operations that can register callback routines for them. This parameter value indicates each operation starting with EM _ (the complete list can be obtained from the API reference guide ). The third parameter is the custom function to be called. The fourth parameter is the recursive ID (if any). The last parameter is the handle returned by the function used to cancel registration.

When you end the program, use the emderegister () function to cancel registration of the callback routine. To specify the extensions built to Lotus Notes/Domino, use the extmgr_addins variable in the notes. ini file of the server or client (depending on the location where the extension is running ).

The trap of the calendar configuration file

One of our sample codes shows how to use Extension Manager by using the routine for ending the calendar configuration file update of a specific mail file. This program registers a callback routine for nsfnoteupdateextended. In this callback routine, we will check whether the record to be updated is an email file that we are interested in and whether the record is a calendar configuration file. If yes, the date and time are recorded in a log file. After compiling and linking the program, you must use the following format to list it in the notes. ini file of the server:

Extmgr_addins = <dllname>
You can download the complete code of the Program (including the Mak file and module definition file) from the sandbox ).