| Platform SDK: Transaction Server |
[This product will work only on Windows NT 4.0 versions and earlier. For Windows 2000 and later, see COM+ (Component Services).]
Used by an object to obtain a reference to itself that's safe to pass outside its context.
The header file for the SafeRef function is mtx.h.
void* SafeRef (
REFIID riid
UNKNOWN* pUnk
);
Parameter
riid
[in] A reference to the interface ID of the interface that the current object wants to pass to another object or client.
pUnk
[in] A reference to an interface on the current object.
Return Values
Non-NULL
A pointer to the interface specified in the riid parameter that's safe to pass outside the current object's context.
NULL
The object is requesting a safe reference on an object other than itself, or the interface requested in the riid parameter is not implemented.
Remarks
When an MTS object wants to pass a self-reference to a client or another object (for example, for use as a callback), it should always call SafeRef first and then pass the reference returned by this call. An object should never pass a this pointer, 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's 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's 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's finished with it.
Note Safe references have different pointer values than their unsafe counterparts. For example, this and the safe version of this do not have the same value. It's 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's possible that both pointers refer to the same object, but that one is a safe reference and the other isn't. 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.
See Also