Notes C API探訪: メモリハンドル

通常、C/C++でメモリ領域を取得する場合、malloc/freeやnew/deleteを使いますが、あえてNotes/Dominoからメモリ資源を確保することもできます。その場合、Windows SDKのように、メモリハンドルという形で取得することができます。取得したメモリハンドルを通して、メモリにアクセスし、領域を拡張/縮小し、不要になったらリリースすることができます。

DHANDLE

DHANDLE型は、Dominoハンドル(汎用メモリハンドル)です。

#include <global.h>
typdef HANDLE DHANDLE;  // Windowsの場合、Windows.hで定義済みのHANDLEを流用

多くのNotes/Domino用ハンドルはDHANDLE型の別名として定義されています(データベースハンドル、文書ハンドルなど)。

OSMemAlloc

OSMemAlloc関数は、メモリ領域を確保してハンドルを返します。

#include <osmem.h>
STATUS LNPUBLIC	OSMemAlloc (WORD BlkType, DWORD dwSize, DHANDLE far *retHandle);

BlkTypeは、MEM_SHAREフラグとMEM_GROWABLEフラグのオン/オフを指定します。MEM_SHAREは他のプロセスと共有できるメモリとして、MEM_GROWABLEは拡張、縮小が可能なメモリとして宣言できます。
dwSizeは、確保する領域サイズを指定します。
retHandleは、確保したメモリ領域のハンドル値を返します。

OSLockObject

OSLockObject関数は、ハンドル状態のメモリをロックしてポインタを返します。確保したメモリ領域にアクセスするには、このポインタを使用します。

#include <osmem.h>
void far * LNPUBLIC OSLockObject (DHANDLE Handle);

Handleは、ロックしたいメモリハンドルを指定します。
戻り値は、ロックした領域の先頭ポインタを返します。

OSUnlockObject

OSUnlockObject関数は、ロックされたメモリ領域をアンロックします。「アンロック」とは、ポインタによる利用を停止し、ハンドルが確保しているメモリ領域を、移動したり、拡張したり、縮小したり、解放したりできる状態を指します。

#include <osmem.h>
BOOL LNPUBLIC OSUnlockObject (DHANDLE Handle);

Handleは、アンロックしたいメモリハンドルを指定します。
戻り値はBOOL型ですが常にTRUEを返します(チェック不要)。

OSMemGetSize

OSMemGetSize関数は、メモリハンドルが確保しているメモリ領域のサイズを返します。

#include <osmem.h>
STATUS LNPUBLIC	OSMemGetSize (DHANDLE Handle, DWORD far *retSize);

Handleは、サイズを知りたいメモリのハンドルです。
retSizeは、メモリ領域のサイズサイズを返す変数へのポインタです。

OSMemRealloc

OSMemRealloc関数は、メモリハンドルが確保している領域を拡張、または縮小します。OSMemAlloc関数でMEM_GROWABLEフラグを立てたメモリハンドルが対象です。

#include <osmem.h>
STATUS LNPUBLIC	OSMemRealloc (DHANDLE Handle, DWORD NewSize);

Handleは、リサイズしたいメモリのハンドルです。
NewSizeは、リサイズ後のメモリ領域のサイズを指定します。

OSMemFree

OSMemFree関数は、メモリハンドルが確保している領域を解放します。

#include <osmem.h>
STATUS LNPUBLIC	OSMemFree (DHANDLE Handle);

Handleは、解放したいメモリ領域へのハンドルを指定します。

メモリハンドルの所有権

原則として、自分で確保したメモリ領域は自分で解放します。しかし、関数の中には所有権を譲らなければいけないものもあります。その場合、自分で確保したメモリ領域であっても、自身で解放してはいけません。