Takenoff Labs

今回からようやくコードの説明に入ります。が、今回も基礎的な内容になってしまいました……。いざ書いてみると、説明すべきことが沢山出てきますね(> <)

関数の宣言

VB や LotusScript では、C関数を使用するには関数の宣言が必要になります。関数の宣言には「Declare」ステートメントを使用します。

たとえば、次のアイテムの情報を取得する NSFItemInfoNext という関数は、Cでは以下のように宣言されます。

STATUS LNPUBLIC NSFItemInfoNext(
	NOTEHANDLE  note_handle,
	BLOCKID  NextItem,
	const char far *item_name,
	WORD  name_len,
	BLOCKID far *item_blockid_ptr,
	WORD far *value_type_ptr,
	BLOCKID far *value_blockid_ptr,
	DWORD far *value_len_ptr);

まず最初の「STATUS」ですが、この部分は戻り値の型を示します。「void」の場合は戻り値が無いので「Declare Sub」とし、それ以外の場合は「Declare Function ～ As 戻り値の型」とします（型については次回以降説明）。「STATUS」＝「WORD」＝「unsigned short」＝2バイトなので、Integer が戻り値の型となります。

LNPUBLIC については、まぁ気にしないでください（＾＾；

引数部分は、基本的にポインタ（「*」が付くもの）は Byval を付けず、それ以外には Byval を付けます。ただし、char や構造体の場合は例外です。

まず char （String） の場合は、常に Byval を付けます。値を渡す場合も受ける場合も、Byval を付けてください。奇異に思われるかもしれませんが、そういうもんだと思ってください（＾＾；

構造体の場合は、値を受ける場合は Byval を付けません。値を渡す場合は、メンバごとに分解して渡します。

構造体については、リファレンスを参照すると、宣言が載っています。BLOCKID の場合は、以下のようになっています。

typedef struct {
   DHANDLE pool; /* pool handle */
   BLOCK  block; /* block handle */
 } BLOCKID;

LotusScript では、ユーザー定義型（Type）で宣言できます。（「DHANDLE」＝「HANDLE」＝「unsigned int」＝4バイト＝「Long」、「BLOCK」＝「WORD」＝「unsigned short」＝2バイト＝Integer となります。）

Type BLOCKID
	hPool As Long
	Block As Integer
End Type

ちなみに、型指定に困ったら、「Any」を使うこともできます。LotusScript 的に1つの型で指定できないような場合は、「Any」を使うと便利です。ただし、正しい型の変数を渡さないと、実行時に思わぬエラーになる場合もありますので、注意して使用してください。

以上のことから、NSFItemInfoNext（とBLOCKID） を LotusScript で宣言すると、以下のようになります。

Type BLOCKID
	hPool As Long
	Block As Integer
End Type
Declare Function NSFItemInfoNext Lib "nnotes.dll" _
(Byval hNote As Integer, Byval hPool As Long, _
Byval Block As Integer, Byval ItemName As String, _
Byval NameLen As Integer, _
ItemBlockid As BLOCKID, ValueDatatype As Integer, _
ValueBlockid As BLOCKID, ValueLen As Long) As Integer

"nnotes.dll" の部分は、API 本体の DLL を指定します。プラットフォームによって名前が変わりますが、まあたいてい Windows だと思うので、"nnotes.dll" と覚えておくとよいでしょう。この部分は定数化しておくと便利です。

C 関数の名前そのままでなく、別の名前にして使いたい場合は、「Alias」を使います。

Declare Function ItemInfoNext Lib "nnotes.dll" _
Alias "NSFItemInfoNext" ～

本来の名前のほうが、Alias の後にくることに注意してください。型の問題で、関数宣言を複数定義したい場合がたまにありますので、こういうときには Alias を使うと便利です。

関数の種類

API関数は、接頭辞を見ると、何に対する操作かがだいたい判ります。以下に代表的なものをピックアップしてみます。これであたりをつけて検索すると、目的の関数が見つけやすくなると思います。

接頭辞	説明
ACL～	ACLに対する操作
Agent～	エージェントに対する操作
Folder～	フォルダに対する操作
ID～	IDテーブルに対する操作
Mail～	メールに対する操作
NIF～	ビューに対する操作
NSFDb～	データベースに対する操作
NSFItem～	アイテムに対する操作
NSFNote～	ノートに対する操作
OS～	メモリやリソースなどに対する操作
SEC～	セキュリティ関連の操作
SECKFM～	IDファイルに対する操作
Time～	日時値に対する操作

どんな関数があるかは、Toolkit に付属の「doc\api（バージョン番号）ref.nsf」を見てください。こちらのページからでも、同じものが参照できます。

定数の宣言

定数は、たいていの場合、Toolkit に付いている C のヘッダファイルにしか情報がありません。ネットの LotusScript のサンプルを見る手もありますが、全部載っている訳ではありませんから、できるだけ Toolkit は入手しておいてください。

たとえば、ノートクラスに関する定数は、"nsfnote.h" で以下のように宣言されています。

#define NOTE_CLASS_DOCUMENT		0x0001		/* document note */
#define NOTE_CLASS_DATA		NOTE_CLASS_DOCUMENT	/* old name for document note */
#define NOTE_CLASS_INFO		0x0002		/* notefile info (help-about) note */
#define NOTE_CLASS_FORM		0x0004		/* form note */
#define NOTE_CLASS_VIEW		0x0008		/* view note */
#define NOTE_CLASS_ICON		0x0010		/* icon note */
#define NOTE_CLASS_DESIGN		0x0020		/* design note collection */
#define NOTE_CLASS_ACL		0x0040		/* acl note */
#define NOTE_CLASS_HELP_INDEX	0x0080		/* Notes product help index note */
#define NOTE_CLASS_HELP		0x0100		/* designer's help note */
#define NOTE_CLASS_FILTER		0x0200		/* filter note */
#define NOTE_CLASS_FIELD		0x0400		/* field note */
#define NOTE_CLASS_REPLFORMULA	0x0800		/* replication formula */
#define NOTE_CLASS_PRIVATE		0x1000		/* Private design note, use $PrivateDesign view to locate/classify */
#define NOTE_CLASS_DEFAULT		0x8000		/* MODIFIER - default version of each */
#define NOTE_CLASS_NOTIFYDELETION	NOTE_CLASS_DEFAULT	/* see SEARCH_NOTIFYDELETIONS */
#define NOTE_CLASS_ALL		0x7fff		/* all note types */
#define NOTE_CLASS_ALLNONDATA	0x7ffe		/* all non-data notes */
#define NOTE_CLASS_NONE		0x0000		/* no notes */

これを LotusScript のConst 文に置き換えるのは、ほぼ機械的にできます。「#define」を「Const」に、「0x」を「&H」に変えるなどすれば、簡単にできるでしょう。

Const NOTE_CLASS_DOCUMENT		= &H0001
Const NOTE_CLASS_DATA		= NOTE_CLASS_DOCUMENT
Const NOTE_CLASS_INFO		= &H0002
Const NOTE_CLASS_FORM		= &H0004
Const NOTE_CLASS_VIEW		= &H0008
Const NOTE_CLASS_ICON		= &H0010
Const NOTE_CLASS_DESIGN		= &H0020
Const NOTE_CLASS_ACL		= &H0040
Const NOTE_CLASS_HELP_INDEX		= &H0080
Const NOTE_CLASS_HELP		= &H0100
Const NOTE_CLASS_FILTER		= &H0200
Const NOTE_CLASS_FIELD		= &H0400
Const NOTE_CLASS_REPLFORMULA	= &H0800
Const NOTE_CLASS_PRIVATE		= &H1000
Const NOTE_CLASS_DEFAULT		= &H8000
Const NOTE_CLASS_NOTIFYDELETION	= NOTE_CLASS_DEFAULT
Const NOTE_CLASS_ALL		= &H7fff
Const NOTE_CLASS_ALLNONDATA		= &H7ffe
Const NOTE_CLASS_NONE		= &H0000

定数名については、元の名前をそのまま使うのが手っ取りばやいです。ただし、先頭が「_」で始まる場合などは、そのままでは使えませんので、前に何か付けてください。

値部分については、マクロになっている場合などはそのままでは使えません。これはケースバイケースで対処するしかありません。

定数は必ずしも宣言しなければいけない訳ではありませんが、宣言しておくとコードが見やすくなります。

トラックバックURL :