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>とほぼ同じ機能」と紹介されています。
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が存在します。