Takenoff Labs

Lotus Notes/Domino に関する Tips や、クラシックの名曲などを紹介します

[Notes/Domino] 設計解析講座: API関数の宣言

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

関数の宣言

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

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

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

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

1 Star2 Stars3 Stars4 Stars5 Stars (2 votes, average: 3.50 out of 5)
Loading...

トラックバック

トラックバックはありません

コメント

コメントはありません

※コメントは承認制となっております。管理者が承認するまで表示されません。申し訳ありませんが、投稿が表示されるまでしばらくお待ちください。





(以下のタグが使えます)
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

For spam filtering purposes, please copy the number 7696 to the field below:

^
×