Notes C API探訪: NSFLocateSummaryValue/NSFGetSummaryValue(関数)

前回お伝えしたITEM_TABLE構造体は、RANGE型のようにヘルパー関数の乏しいデータ型です。が、皆無ではありません。名前付きサマリーバッファから名前を指定してテキストを取り出すNSFGetSummaryValueと、テキスト以外のデータでも取得可能にするNSFLocateSummaryValue、2つの関数が用意されています。

NSFLocateSummaryValue

NSFLocateSummaryValue関数は、以下のように定義されています。

#include <nsfnote.h>
BOOL LNPUBLIC NSFLocateSummaryValue (
    const void far *SummaryBuffer,
    const char far *Name,	
    void far *retValuePointer,
    WORD far *retValueLength,
    WORD far *retDataType);

SummaryBufferは、名前付きサマリーバッファのITEM_TABLE構造体へのポインタを指定します。
Nameは、取り出したいアイテムの名前を指定します。
retValuePointerは、指定した名前のアイテムの、値へのポインタを返します。
retValueLengthは、指定した名前のアイテムの、値のサイズを保存する変数へのポインタを返します。
retDataTypeは、指定したアイテム値のデータタイププレフィックスを保存する変数へのポインタを返します。

retValuePointerは値へのポインタを示す(Locateする)だけなので、実際にデータを使う場合は、ポインタから値をコピーしてから使うようにします。

NSFGetSummaryValue

NSFGetSummaryValue関数は、名前付きサマリーバッファからテキストデータ限定で取得します。

#include <nsfnote.h>
BOOL LNPUBLIC NSFGetSummaryValue (
  const void far *SummaryBuffer,
  const char far *Name,
  char far *retValue,
  WORD ValueBufferLength);

SummaryBufferは、名前付きサマリーバッファのITEM_TABLE構造体へのポインタを指定します。
Nameは、取り出したいアイテムの名前を指定します。
retValueは、値を格納するバッファへのポインタを返します。
ValueBufferLengthは、用意しいバッファへサイズを指定します。

NSFGetSummaryValueは、実際にテキストデータを取得(Get)する関数なので、呼び出し元でテキストを格納するバッファを用意する必要があります。

まとめ

サマリーバッファは、その特性上ReadOnlyなデータなので、今回ご紹介した関数でほぼ事足りるでしょう。ITEM_TABLE構造体とサマリーバッファは構造さえ押さえてしまえばどうとでもなるので、ヘルパー関数が必要だと思ったら自作してみましょう。