CoLockObjectExternal 関数 (combaseapi.h)
オブジェクトをロックしてメモリ内に留まるか、そのようなロックを解除するために呼び出されます。
構文
HRESULT CoLockObjectExternal(
[in] LPUNKNOWN pUnk,
[in] BOOL fLock,
[in] BOOL fLastUnlockReleases
);
パラメーター
[in] pUnk
ロックまたはロック解除するオブジェクトの IUnknown インターフェイスへのポインター。
[in] fLock
オブジェクトをロックするか解放するかを示します。 このパラメーターが TRUE の場合、オブジェクトは AddRef/Release 操作、登録、または失効とは関係なく、メモリ内に保持されます。 このパラメーターが FALSE の場合、この関数の呼び出しで以前に設定されたロックが解放されます。
[in] fLastUnlockReleases
ロックがオブジェクトを存続させる最後の参照である場合は、 TRUE を 指定してオブジェクトへのすべてのポインターを解放します (他の参照が存在する可能性があります)。 それ以外の場合は、 FALSE を指定します。
fLock が TRUE の場合、このパラメーターは無視されます。
戻り値
この関数は、E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTED、S_OKの標準戻り値を返すことができます。
注釈
CoLockObjectExternal 関数は、オブジェクトが実際に存在するプロセス (ハンドラーが読み込まれるプロセスではなく、EXE プロセス) で呼び出す必要があります。
CoLockObjectExternal 関数は、オブジェクトの参照カウントが 0 になるのを防ぎ、ロックが解除されるまでオブジェクトを "ロック" します。 同じ関数 (パラメーターが異なる) によってロックが解放されます。 ロックは、オブジェクトに対してシステム呼び出し IUnknown::AddRef を呼び出すことによって実装されます。 その後、fLock を FALSE に設定して CoLockObjectExternal を呼び出すまで、システムはオブジェクトで IUnknown::Release を呼び出すのを待機します。 この関数は、エンド ユーザーの代わりにオブジェクトの参照カウントを維持するために使用できます。これは、ユーザーと同様にオブジェクトの外部で動作するためです。
エンド ユーザーは、外部ロックがある場合でも、アプリケーションの有効期間を明示的に制御できます。 つまり、ユーザーがアプリケーションを閉じる場合は、シャットダウンする必要があります。 外部ロック ( CoLockObjectExternal によって設定されたロックなど) が存在する場合、アプリケーションは CoDisconnectObject 関数を呼び出して、シャットダウン前にこれらの接続を強制的に閉じることができます。
CoLockObjectExternal を呼び出すと、オブジェクトに対して強力なロックが設定されます。 強力なロックはオブジェクトをメモリ内に保持しますが、弱いロックは保持しません。 たとえば、OLE 埋め込みのサイレント更新中など、強力なロックが必要です。 埋め込みオブジェクトのコンテナーは、更新プロセスが完了するまでメモリ内に残る必要があります。 また、アプリケーション オブジェクトに対して強力なロックを設定して、クライアントへのサービスの提供が完了するまでアプリケーションが稼働し続けられるようにする必要があります。 すべての外部参照は、オブジェクトに厳密な参照ロックを設定します。
CoLockObjectExternal 関数は、通常、次の状況で呼び出されます。
- オブジェクト サーバーは、表示されたら fLock と fLastLockReleases の両方を TRUE に設定して CoLockObjectExternal を呼び出す必要があります。 この呼び出しにより、ユーザーに代わって強力なロックが作成されます。 アプリケーションを閉じるときに、 CoLockObjectExternal の呼び出しでロックを解放し、 fLock を FALSE に、 fLastLockReleases を TRUE に設定 します。
- サーバー上の CoLockObjectExternal の呼び出しは、 IOleContainer::LockContainer の実装でも使用できます。
アプリケーションがアプリケーションのすべての側面を管理し、 CoLockObjectExternal の呼び出しでドキュメントのシャットダウンを完全に管理しない限り、ロックカウントが 0 に達し、コンテナーが非表示になったときに終了するように、コンテナーは LockContainer でプライベート ロック数を保持する必要があります。 シャットダウンのすべての側面を維持し、プライベート ロック数を保持しないようにすることは、次のいずれかの条件が発生するたびに CoLockObjectExternal を呼び出す必要があることを意味します。
- ドキュメントが作成され、破棄されるか、表示または非表示になります。
- アプリケーションが起動し、ユーザーによってシャットダウンされます。
- 擬似オブジェクトが作成され、破棄されます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | combaseapi.h (Objbase.h を含む) |
| Library | Ole32.lib |
| [DLL] | Ole32.dll |