Notes C API探訪: NSFDbOpen/NSFDbClose(関数)

Notes/Dominoの根幹はNSFファイルで形成されていると言っても過言ではないでしょう。掲示板、ワークフロー、メール、スケジュール、アドレス帳、あらゆるものがNSFファイル単位で作成されています。そのNSFファイルにアクセスする最初の一歩がNSFDbOpenであり、後始末がNSFDbCloseになります。

NSFDbOpen

NSFDbOpen関数は、パスからデータベースファイルまたはディレクトリを開いて、そのハンドルを取得します。

#include <nsfdb.h>
STATUS LNPUBLIC NSFDbOpen (const char far *PathName, DBHANDLE far *rethDB);

PathNameは、ヌル終端されたパス文字列を指定します。パス文字列はOSPathNetConstruct関数で構築されたパスを指定します。
rethDBは、DBHANDLE変数へのポインタを指定します。

NSFDbOpenは、データベースファイルを開くだけでなく、ディレクトリを開くのにも使用されます。ディレクトリを開く理由は、そのディレクトリ上でファイルやサブディレクトリを検索するためです。

NSFDbModeGet

ハンドルが、ファイルを指しているのか、ディレクトリを指しているかは関数NSFDbModeGetで調べられます。

#include <nsfdb.h>
STATUS LNPUBLIC NSFDbModeGet (DBHANDLE hDB, USHORT far *retMode);

hDBは、DBHANDLE型のデータベースハンドルを指定します。
retModeは、そのハンドルがつかんでいるのがデータベースファイルならばDB_LOADED、ディレクトリならばDB_DIRECTORYを格納する変数(USHORT型)へのポインタを指定します。

NSFDbClose

NSFDbClose関数は、開いているデータベースハンドルを閉じます。

#include <nsfdb.h>
STATUS LNPUBLIC NSFDbClose (DBHANDLE hDB);

hDBは、開いているDBHANDLE型のデータベースハンドルを指定します。閉じたハンドルは以降使用できなくなります。

サンプルコード

#include <global.h>
#include <nsfdb.h>
#include <osfile.h>

void nsfdbopenAndClose(const char *filePath) {
 char path[MAXPATH] = "";
 STATUS status = OSPathNetConstruct(nullptr, "", filePath, path);
 if (ERR(status) != NOERROR) {
   std::cerr << "OSPathNetConstruct error." << std::endl;
   return;
 }
 DBHANDLE hDB = NULLHANDLE;
 status = NSFDbOpen(path, &hDB);
 if (ERR(status) != NOERROR) {
   std::cerr << "NSFDbOpen error." << std::endl;
   return;
 }
 USHORT mode = 0;
 status = NSFDbModeGet(hDB, &mode);
 if (ERR(status) != NOERROR) {
   std::cerr << "NSFDbModeGet error." << std::endl;
   return;
 }
 std::cout << "The mode of '" << filePath
           << "' is " << mode << "." << std::endl;
 status = NSFDbClose(hDB);
 if (ERR(status) != NOERROR) {
   std::cerr << "NSFDbClose error." << std::endl;
   return;
 }
}

void nsfdbopen_closeTest() {
 nsfdbopenAndClose("");
 nsfdbopenAndClose("names.nsf");
 nsfdbopenAndClose("Help");
 nsfdbopenAndClose("Help\\help9_client.nsf");
 nsfdbopenAndClose("hoge.nsf");
}

/* 実行結果
The mode of '' is 2.
The mode of 'names.nsf' is 1.
The mode of 'Help' is 2.
The mode of 'Help\help9_client.nsf' is 1.
NSFDbOpen error.
*/

サンプルコードでは、データベース/ディレクトリをオープンし、モードを取得して表示し、データベース/ディレクトリを閉じるという一連の動作を、ローカルルートディレクトリ、names.nsf(個人アドレス帳)、Helpディレクトリ、NotesクライアントヘルプDB、存在しないファイルに対して行っています。

まとめ

データベースを開くという単純な操作ですが、実はディレクトリ検索と兼用だと紹介しました。さらに、仕様が拡張されたNSFDbOpenExtended関数があったり、スレッド内で再オープンするためのNSFDbReopen関数があったりと、紐解くととても奥深い話になりますので、折を見て紹介できたらいいなと思っています。

注意: コードの利用においてチブル・システムズは一切の責任を負いません。自己責任でご利用をお願いいたします。