Winapi.Mtx.SafeRef
Delphi
function SafeRef(const rid: TGUID; Unk: IUnknown): Pointer;
Properties
| Type | Visibility | Source | Unit | Parent |
|---|---|---|---|---|
| function | public | Winapi.Mtx.pas | Winapi.Mtx | Winapi.Mtx |
Description
Returns a reference to a transactional object that is safe to pass outside its context.
SafeRef encapsulates the SafeRef MTS function that passes in a reference to the interface ID of the interface (rid) that the current object wants to pass to another object or client and a reference to an interface on the current object (pUnk).
SafeRef returns a pointer to the interface specified in the rid parameter that is safe to pass outside the current object's context.
When using COM+, it is always safe to pass a self-reference to a client or other object. Thus, when you call SafeRef in an application that is running under a version of Windows that implemnts COM+, SafeRef simply returns the pointer passed as pUnk. Thus, it is not necessary to call SafeRef for COM+ applications. It will, however, do no harm in an application that is used under both MTS and COM+.
Under MTS, and should always call SafeRef before passing a self-reference to a client or other object and then pass the reference returned by this call. Under MTS, it is not safe for an object to pass a self pointer (Delphi) or this pointer (C++), or a self-reference obtained through an internal call to QueryInterface, to a client or to any other object. Once such a reference is passed outside the object's context, it is no longer a valid reference.
Calling SafeRef on a reference that is already safe returns the safe reference unchanged, except that the reference count on the interface is incremented.
When a client calls QueryInterface on a reference that is safe, MTS automatically ensures that the reference returned to the client is also a safe reference.
An object that obtains a safe reference must release the safe reference when it is finished with it.
Under MTS, safe references have different pointer values than their unsafe counterparts. For example, self or this and the safe version of self or this do not have the same value. It is important to be aware of this when testing whether two pointers refer to the same object. Calling QueryInterface for IID_IUnknown on each of the pointers and comparing the value of the returned pointers may result in the wrong conclusion. It is possible that both pointers refer to the same object, but that one is a safe reference and the other is not. If both references are safe references, they can be compared in the usual way. This is only a consideration for MTS objects, because clients should never have access to unsafe references.
Note: When writing a transactional object that may be installed under either MTS or COM+, use the SafeRef method of TMtsDll instead. TMtsDll automatically checks the current environment and returns the appropriate reference.