Notes C API探訪: NSFNoteGetInfo/NSFNoteSetInfo(関数)

NSFSearch関数で文書がマッチするたびにコールバック関数が呼び出されますが、その第2引数で送られてくるのがSEARCH_MATCH構造体でした。

typedef struct {
	GLOBALINSTANCEID ID;		/* identity of the note within the file */
	ORIGINATORID OriginatorID;	/* identity of the note in the universe */
	WORD NoteClass;				/* class of the note */
	BYTE SERetFlags;			/* MUST check for SE_FMATCH! */
	BYTE Privileges;			/* note privileges */
	WORD SummaryLength;			/* length of the summary information */
	/*WORD TUALength;			length of the $TUA item value; must be requested with SEARCH1_RETURN_THREAD_UNID_ARRAY */
								/* 56 bytes to here */
								/* now comes an ITEM_TABLE with Summary Info */
								/* now comes the optional $TUA item value.  It is in host format. */
} SEARCH_MATCH;

このうち、ID.Note(TIMEDATE)、ID.NoteID(NOTEID)、OriginatorID(ORIGINATORID)、NoteClass(WORD)などは、文書情報として文書ハンドルを取得することができます。

NSFNoteGetInfo

NSFNoteGetInfo関数は、文書ハンドルから文書情報を取得します。

#include <nsfnote.h>
void LNPUBLIC NSFNoteGetInfo (NOTEHANDLE hNote, WORD Type, void far *Value);

hNoteは、文書ハンドルを指定します。
Typeは、取得したい文書情報の種類(後述)を指定します。
Valueは、取得したい情報の変数への型を指定します。

文書情報の種類は、以下の通りです。

#include <nsfnote.h>

/* 	Note structure member IDs for NSFNoteGet&SetInfo. */

#define	_NOTE_DB		0		/* IDs for NSFNoteGet&SetInfo */
#define	_NOTE_ID		1		/* (When adding new values, see the */ 
#define	_NOTE_OID		2		/*  table in NTINFO.C */
#define	_NOTE_CLASS		3
#define	_NOTE_MODIFIED	4
#define	_NOTE_PRIVILEGES	5	/* For pre-V3 compatibility. Should use $Readers item */
#define	_NOTE_FLAGS		7
#define	_NOTE_ACCESSED	8
#define _NOTE_PARENT_NOTEID 10	/* For response hierarchy */
#define _NOTE_RESPONSE_COUNT 11	/* For response hierarchy */
#define _NOTE_RESPONSES 12		/* For response hierarchy */
#define _NOTE_ADDED_TO_FILE 13	/* For AddedToFile time */
#define _NOTE_OBJSTORE_DB 14	/* DBHANDLE of object store used by linked items */

文書情報のデータ型は種類によってまちまちです。_ADDED_TO_FILEのみ情報がありませんが、それ以外は以下の通りです。

_NOTE_DB             /* DBHANDLE */
_NOTE_ID             /* NOTEID */ 
_NOTE_OID            /* ORIGINATORID(OID) */
_NOTE_CLASS          /* WORD */
_NOTE_MODIFIED       /* TIMEDATE */
_NOTE_PRIVILEGES     /* (v3以降使用されなくなったACL的なもの) */
_NOTE_FLAGS          /* WORD */
_NOTE_ACCESSED       /* TIMEDATE */
_NOTE_PARENT_NOTEID  /* NOTEID */
_NOTE_RESPONSE_COUNT /* DWORD */
_NOTE_RESPONSES      /* DHANDLE (返答文書が集合したIDテーブルという構造のハンドル) */
_NOTE_ADDED_TO_FILE  /* ？？？ */
_NOTE_OBJSTORE_DB    /* DBHANDLE */

_NOTE_DBは、属するデータベースのハンドルです。
_NOTE_IDは、文書IDです。
_NOTE_OIDは、UNIDを含むORIGINATORID構造体データです。
_NOTE_CLASSは、文書クラスです。
_NOTE_MODIFIED、文書の最終更新日時です。
_NOTE_FLAGSは、文書フラグです。_NOTE_FLAG_XXXとして定義されています。
_NOTE_ACCESSED、文書の最終アクセス日時です。
_NOTE_PARENT_NOTEID、親文書の文書IDです。
_NOTE_RESPONSE_COUNT、孫以下を含まない、子の返答文書の数です。
_NOTE_RESPONSES、孫以下を含まない、子の返答文書のIDテーブル(後述)ハンドルです。
_NOTE_ADDED_TO_FILEは・・・なんでしょう？作成日時のことでしょうか？情報不足です。
_NOTE_OBJSTOREDBは、オブジェクトストアとしてリンクされるデータベースのハンドルです。

IDテーブルとは、文書IDを昇順で持っているコンテナです。私の愛読書「Notes/Domino APIプログラミング」では「std::set<NOTEID>とほぼ同じ機能」と紹介されています。

Notes/Domino APIプログラミング―C++とSTLによる実践的プログラミング

2000年の著書で、Notes C APIの日本語著作では唯一のものです。今でも非常に役立つ情報が満載です。Amazonでも新品は手に入れにくくなった本ですが、チャンスがあれば是非手に入れてみて下さい。

ちなみに、Notes C APIでは、LIST構造体やRANGE構造体のように、C++であればライブラリで実現できそうなコンテナ構造を、あえて自前で構築している背景には、本来このライブラリがC言語で書かれている点が上げられると思います(先の書籍にもそう指摘されています)。

NSFNoteSetInfo

NSFNoteSetInfo関数は、文書情報を設定します。

#include <nsfnote.h>
void LNPUBLIC NSFNoteSetInfo (NOTEHANDLE hNote, WORD Type, void far *Value);

引数についてはNSFNoteGetInfo関数とかぶるので説明を省略します。

NSFNoteSetInfo関数は、その存在意義に多少の疑問が生じます。DBHANDLEやNOTEID、更新日時やアクセス日時など、利用者が情報を取りに行くことはあっても、こちらから設定できるとは一体どういうことでしょうか？

実は、文書情報を能動的に設定するケースとして、メモリ上にしか存在していない文書、インメモリノートというものがあります。
例えば、DBHANDLEがNULLHANDLEのインメモリノートは、どのデータベースとも関連付いていない状態です。そのため、どこかのデータベースに保存するためには、ここでそのデータベースのハンドルをNSFNoteSetInfo関数で設定する必要があります。
また、NOTEIDを0に設定して保存すると、その文書は新規文書として扱われ、更新時に新たなNOTEIDが付与されます。
OIDは他の文書とかぶってはいけない情報ですが、これにはNSFDbGenerateOIDという関数で生成したものを使います。
更新日時は、例えNSFNoteSetInfo関数であり得ない日時を設定しても、更新時にその日時で上書きされます。

このように、文書情報をこちらで設定する場面があるために、NSFNoteSetInfoが存在します。