Win32 API 日本語リファレンス
ホーム › System.Com › ADVF

ADVF

列挙型
📘 Microsoft Learn (日本語) · English
基底型i4

メンバー 7

名前10進16進説明
ADVF_NODATA10x1

データアドバイザリ接続 (IDataObject::DAdvise または IDataAdviseHolder::Advise) の場合、このフラグは、IAdviseSink::OnDataChange を呼び出す際にデータを送信しないようデータオブジェクトに要求します。変更通知を受け取った側は、後から IDataObject::GetData を呼び出してデータを要求できます。データオブジェクトは、STGMEDIUM パラメーターに TYMED_NULL を渡すことでこの要求に応じることもできますし、そのままデータを提供することもできます。たとえば、データオブジェクトが複数のアドバイザリ接続を持ち、そのすべてが ADVF_NODATA を指定しているわけではない場合、オブジェクトはすべての接続に同じ通知を送信することがあります。コンテナーの要求にかかわらず、その IAdviseSink の実装は STGMEDIUM パラメーターを確認しなければなりません。メディアが TYMED_NULL でない場合は、それを解放する責任があるためです。

キャッシュ接続 (IOleCache::Cache) の場合、このフラグは、実行中のオブジェクトに加えられた変更によってキャッシュを更新しないよう要求します。代わりに、コンテナーが IOleCache::SetData を明示的に呼び出してキャッシュを更新します。この状況は、通常、オブジェクトのアイコン表示の側面がキャッシュされる場合に発生します。

ADVF_NODATA はビューアドバイザリ接続 (IViewObject::SetAdvise) では有効なフラグではなく、E_INVALIDARG を返します。

ADVF_PRIMEFIRST20x2データまたはビューが変更されるのを待たずに、IAdviseSink::OnDataChange の最初の呼び出し (データまたはビューのアドバイザリ接続の場合)、あるいはキャッシュの更新 (キャッシュ接続の場合) を行うようオブジェクトに要求します。ADVF_ONLYONCE と組み合わせて使用すると、このパラメーターは非同期の IDataObject::GetData 呼び出しを実現します。
ADVF_ONLYONCE40x4

接続を削除する前に、変更通知またはキャッシュの更新を 1 回だけ行うようオブジェクトに要求します。

ADVF_ONLYONCE は、データまたはビューの通知を 1 回送信した後、アドバイザリ接続を自動的に削除します。アドバイズシンクは IAdviseSink の呼び出しを 1 回だけ受け取ります。接続が確立された場合は 0 以外の接続識別子が返されるため、呼び出し元はそれを使用して最初の変更通知より前に接続を削除できます。

データ変更通知の場合、ADVF_ONLYONCE と ADVF_PRIMEFIRST の組み合わせは、事実上、非同期の IDataObject::GetData 呼び出しを実現します。

キャッシュで使用する場合、ADVF_ONLYONCE は最初の IAdviseSink::OnDataChange 通知を受け取ったときに 1 回だけキャッシュを更新します。更新が完了すると、オブジェクトとキャッシュの間のアドバイザリ接続は切断されます。アドバイザリ接続のソースオブジェクトは Release メソッドを呼び出します。

ADVF_DATAONSTOP640x40

データアドバイザリ接続の場合、データへのアクセス可能性を保証します。このフラグは、データオブジェクトが閉じられる際に、呼び出しと共にデータを提供して IAdviseSink::OnDataChange を呼び出す必要があることを示します。通常、この値は ADVF_NODATA と組み合わせて使用します。この値を指定しない場合、データを伴わない OnDataChange の呼び出しがシンクに到達する時点で、ソースが既にシャットダウンを完了しており、データにアクセスできない可能性があります。この値を指定するシンクは、OnDataChange でデータが渡される場合はそれを受け取るようにしてください。再度取得する機会が得られない可能性があるためです。

キャッシュ接続の場合、このフラグは、オブジェクトを閉じる処理の一部としてキャッシュを更新する必要があることを示します。

ADVF_DATAONSTOP はビューアドバイザリ接続では有効なフラグではありません。

ADVFCACHE_NOHANDLER80x8より多く使用される ADVFCACHE_FORCEBUILTIN と同義です。
ADVFCACHE_FORCEBUILTIN160x10この値は、自身のオブジェクトの描画を行う DLL オブジェクトアプリケーションおよびオブジェクトハンドラーで使用されます。ADVFCACHE_FORCEBUILTIN は、キャッシュ内にプレゼンテーションが確実に存在するように、プレゼンテーションデータをキャッシュするよう OLE に指示します。この値は、データまたはビューのアドバイザリ接続では有効なフラグではありません。キャッシュ接続の場合、このフラグは、IDataObject::GetData または IViewObject::Draw で生成するために OLE (または基盤となるオペレーティングシステム) に同梱されているコードのみを必要とするデータをキャッシュします。この値を指定することで、コンテナーは、オブジェクトやハンドラーのコードが利用できない場合でもデータを取得できるようにできます。
ADVFCACHE_ONSAVE320x20キャッシュ接続の場合、このフラグは、キャッシュを含むオブジェクトが保存されるときにのみ、キャッシュされた表現を更新します。キャッシュは、OLE オブジェクトが実行状態から読み込み済み状態に戻るときにも更新されます (その後の保存操作でオブジェクトを再実行する必要が生じるためです)。この値は、データまたはビューのアドバイザリ接続では有効なフラグではありません。

公式ドキュメント

データのキャッシュと変更通知を制御するフラグです。

解説(Remarks)

データまたはビューのアドバイザリ接続では、コンテナーは IAdviseSink インスタンスと IDataObject または IViewObject インスタンスとの間の接続を設定する際に ADVF 定数を使用します。これらの接続は、IDataObject::DAdvise、IDataAdviseHolder::Advise、または IViewObject::SetAdvise メソッドを使用して設定します。

キャッシュ接続では、オブジェクトがキャッシュをどのように更新すべきかについてのコンテナーの要求を示すために、IOleCache::Cache メソッドでこれらの定数を指定します。

これらの定数は、STATDATA 構造体の advf メンバーでも使用されます。この構造体は、IEnumSTATDATA が列挙された接続を記述するために使用し、advf メンバーは、アドバイザリ接続またはキャッシュ接続が確立された際に指定されたフラグを示します。STATDATA が IOleObject::EnumAdvise 列挙子に使用される場合、advf メンバーは不定です。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

列挙メンバーの定義。HSP タブは #define global(値は16進)。

typedef enum ADVF : int {
    ADVF_NODATA = 1,
    ADVF_PRIMEFIRST = 2,
    ADVF_ONLYONCE = 4,
    ADVF_DATAONSTOP = 64,
    ADVFCACHE_NOHANDLER = 8,
    ADVFCACHE_FORCEBUILTIN = 16,
    ADVFCACHE_ONSAVE = 32
} ADVF;
public enum ADVF : int
{
    ADVF_NODATA = 1,
    ADVF_PRIMEFIRST = 2,
    ADVF_ONLYONCE = 4,
    ADVF_DATAONSTOP = 64,
    ADVFCACHE_NOHANDLER = 8,
    ADVFCACHE_FORCEBUILTIN = 16,
    ADVFCACHE_ONSAVE = 32,
}
Public Enum ADVF As Integer
    ADVF_NODATA = 1
    ADVF_PRIMEFIRST = 2
    ADVF_ONLYONCE = 4
    ADVF_DATAONSTOP = 64
    ADVFCACHE_NOHANDLER = 8
    ADVFCACHE_FORCEBUILTIN = 16
    ADVFCACHE_ONSAVE = 32
End Enum
import enum

class ADVF(enum.IntEnum):
    ADVF_NODATA = 1
    ADVF_PRIMEFIRST = 2
    ADVF_ONLYONCE = 4
    ADVF_DATAONSTOP = 64
    ADVFCACHE_NOHANDLER = 8
    ADVFCACHE_FORCEBUILTIN = 16
    ADVFCACHE_ONSAVE = 32
// ADVF
pub const ADVF_NODATA: i32 = 1;
pub const ADVF_PRIMEFIRST: i32 = 2;
pub const ADVF_ONLYONCE: i32 = 4;
pub const ADVF_DATAONSTOP: i32 = 64;
pub const ADVFCACHE_NOHANDLER: i32 = 8;
pub const ADVFCACHE_FORCEBUILTIN: i32 = 16;
pub const ADVFCACHE_ONSAVE: i32 = 32;
// ADVF
const (
	ADVF_NODATA int32 = 1
	ADVF_PRIMEFIRST int32 = 2
	ADVF_ONLYONCE int32 = 4
	ADVF_DATAONSTOP int32 = 64
	ADVFCACHE_NOHANDLER int32 = 8
	ADVFCACHE_FORCEBUILTIN int32 = 16
	ADVFCACHE_ONSAVE int32 = 32
)
const
  ADVF_NODATA = 1;
  ADVF_PRIMEFIRST = 2;
  ADVF_ONLYONCE = 4;
  ADVF_DATAONSTOP = 64;
  ADVFCACHE_NOHANDLER = 8;
  ADVFCACHE_FORCEBUILTIN = 16;
  ADVFCACHE_ONSAVE = 32;
// ADVF
pub const ADVF_NODATA: i32 = 1;
pub const ADVF_PRIMEFIRST: i32 = 2;
pub const ADVF_ONLYONCE: i32 = 4;
pub const ADVF_DATAONSTOP: i32 = 64;
pub const ADVFCACHE_NOHANDLER: i32 = 8;
pub const ADVFCACHE_FORCEBUILTIN: i32 = 16;
pub const ADVFCACHE_ONSAVE: i32 = 32;
const
  ADVF_NODATA* = 1
  ADVF_PRIMEFIRST* = 2
  ADVF_ONLYONCE* = 4
  ADVF_DATAONSTOP* = 64
  ADVFCACHE_NOHANDLER* = 8
  ADVFCACHE_FORCEBUILTIN* = 16
  ADVFCACHE_ONSAVE* = 32
enum ADVF : int {
    ADVF_NODATA = 1,
    ADVF_PRIMEFIRST = 2,
    ADVF_ONLYONCE = 4,
    ADVF_DATAONSTOP = 64,
    ADVFCACHE_NOHANDLER = 8,
    ADVFCACHE_FORCEBUILTIN = 16,
    ADVFCACHE_ONSAVE = 32,
}
#define global ADVF_NODATA            0x1
#define global ADVF_PRIMEFIRST        0x2
#define global ADVF_ONLYONCE          0x4
#define global ADVF_DATAONSTOP        0x40
#define global ADVFCACHE_NOHANDLER    0x8
#define global ADVFCACHE_FORCEBUILTIN 0x10
#define global ADVFCACHE_ONSAVE       0x20