Notes C API探訪: NSFNoteOpen/NSFNoteClose(関数)(その1)

NSFSearch関数で呼び出されるコールバック関数では、読み取り専用のサマリーバッファだけでは文書を更新、削除などをすることはできません。その場合、SEARCH_MATCH構造体に文書ID(NOTEID)やUNIDが含まれるので、それらを使って文書をオープンし、文書ハンドルを通して更新や削除などをします。

NOTEIDから文書ハンドルを得るには、NSFNoteOpen関数を使います。使い終わった文書ハンドルは、NSFNoteClose関数で閉じます。

NSFNoteOpen

#include <nsfnote.h>
STATUS LNPUBLIC NSFNoteOpen (
  DBHANDLE hDB,
  NOTEID NoteID,
  WORD OpenFlags,
  NOTEHANDLE far *rethNote);

hDBは、開きたい文書があるデータベースのデータベースハンドルです。
NoteIDは、開きたい文書の文書IDです(UNIDではありません)。
OpenFlagsは、文書オープン時に指定するフラグです(後述)。
rethNoteは、受け取る文書ハンドル変数へのポインタです。

OpenFlagsに指定できる値は以下の通りです。
なお、後半の4バイトフラグ(DWORD型)は、NSFNoteOpenExt関数用で、NSFNoteOpen関数では使えません。

#include <nsfnote.h>

/*	Open Flag Definitions.  These flags are passed to NSFNoteOpen. */

#define	OPEN_SUMMARY			0x0001	/* open only summary info */
#define	OPEN_NOVERIFYDEFAULT	0x0002	/* don't bother verifying default bit */
#define	OPEN_EXPAND				0x0004	/* expand data while opening */
#define	OPEN_NOOBJECTS			0x0008	/* don't include any objects */
#define OPEN_SHARE				0x0020	/* open in a "shared" memory mode */
#define OPEN_CANONICAL			0x0040	/* Return ALL item values in canonical form */
#define	OPEN_MARK_READ			0x0100	/* Mark unread if unread list is currently associated */
#define	OPEN_ABSTRACT			0x0200	/* Only open an abstract of large documents */
#define OPEN_RESPONSE_ID_TABLE	0x1000	/* Return response ID table */
#define OPEN_WITH_FOLDERS		0x00020000	/* Include folder objects - default is not to */
#define OPEN_RAW_RFC822_TEXT	0x01000000	/* If set, leave TYPE_RFC822_TEXT items in native
												format.  Otherwise, convert to TYPE_TEXT/TYPE_TIME. */
#define OPEN_RAW_MIME_PART		0x02000000	/* If set, leave TYPE_MIME_PART items in native
												format.  Otherwise, convert to TYPE_COMPOSITE. */
#define OPEN_RAW_MIME	(OPEN_RAW_RFC822_TEXT | OPEN_RAW_MIME_PART)

普通の使い方をする分には、何も指定せずに0を設定します。

NSFNoteClose

NSFNoteClose関数は、オープンしている文書ハンドルをクローズします。

#include <nsfnote.h>
STATUS LNPUBLIC NSFNoteClose (NOTEHANDLE hNote);

hNoteは、オープンしている文書ハンドルを指定します。

自身のプログラムで、能動的に文書をオープンした場合、そのハンドルはクローズする必要があります。ですが、サーバやクライアントのアドインのコーディングをしていると、サーバーやクライアントから文書ハンドルを渡される場合があります。ケース・バイ・ケースですが、アドイン側で文書を閉じてはいけない場合が多いので、リファレンスなどでこのハンドルは閉じるべきか、してはいけないのか、よく確認しましょう。

まとめ

文書をオープンする関数には、いくつかの派生型があります。

1. NSFNoteOpen
2. NSFNoteOpenExt
3. NSFNoteOpenByUNID
4. NSFNoteOpenByUNIDExtended
5. NSFNoteOpenWithLock
6. NSFNoteOpenSoftDelete

3と4はオープンにUNIDを使用します。2と4はオープンフラグがWORDからDWORD型に拡張されています。5はオープン時に文書ロックを行います。6は一時的削除した文書を開きます。すべてを使いこなす必要はないですが、派生型があることだけでも覚えておくとよいでしょう。