IBindCtx::RegisterObjectParam
Stores an IUnknown
pointer on the specified object under the specified key in the bind context s
string-keyed table of pointers. The method must call IUnknown::AddRef
HRESULT RegisterObjectParam(
LPOLESTR pszKey, |
//Pointer to the key to be used |
IUnknown *punk |
//Pointer to the object to be associated with the
key |
); |
|
Parameters
pszKey
[in] Pointer
to a zero-terminated wide character string (two bytes per character) containing
the key under which the object is being registered. Key string comparison is
case-sensitive.
punk
[in] Pointer
to the IUnknown interface on the object that is to be registered.
Return Values
This method
supports the standard return value E_OUTOFMEMORY, as well as the following:
S_OK
The pointer
was successfully registered under the specified string.
Remarks
A bind
context maintains a table of interface pointers, each associated with a string
key. This enables communication between a moniker implementation and the caller
that initiated the binding operation. One party can store an interface pointer
under a string known to both parties so that the other party can later retrieve
it from the bind context.
Binding
operations subsequent to the use of this method can use IBindCtx::GetObjectParam
Notes to Callers
IBindCtx::RegisterObjectParam is useful to those implementing a new moniker class
(through an implementation of IMoniker) and to moniker clients (those
who use monikers to bind to objects).
In
implementing a new moniker class, you call this method when an error occurs
during moniker binding to inform the caller of the cause of the error. The key
that you would obtain with a call to this method would depend on the error
condition. The following lists common moniker binding errors, describing for
each the keys that would be appropriate:
MK_E_EXCEEDEDDEADLINE
If a binding
operation exceeds its deadline because a given object is not running, you
should register the object s moniker using the first unused key from the list:
ExceededDeadline , ExceededDeadline1 , ExceededDeadline2 , etc. If the
caller later finds the moniker in the Running Object Table, the caller can
retry the binding operation.
MK_E_CONNECTMANUALLY
The
ConnectManually key indicates a moniker whose binding requires assistance
from the end user. The caller can retry the binding operation after showing the
moniker s display name to request that the end user manually connect to the
object. Common reasons for this error are that a password is needed or that a
floppy needs to be mounted.
E_CLASSNOTFOUND
The
ClassNotFound key indicates a moniker whose class could not be found (the
server for the object identified by this moniker could not be located). If this
key is used for an OLE compound-document object, the caller can use IMoniker::BindToStorage
If you re a
moniker client with detailed knowledge of the implementation of the moniker
you re using, you can also call this method to pass private information to that
implementation.
You can
define new strings as keys for storing pointers. By convention, you should use
key names that begin with the string form of the CLSID of the moniker class
(see the StringFromCLSID
If the pszKey
parameter matches the name of an existing key in the bind context s table, the
new object replaces the existing object in the table.
When you
register an object using this method, the object is not released until one of
the following occurs:
It is replaced in the table by
another object with the same key.
It is removed from the table by
a call to IBindCtx::RevokeObjectParam .
The bind context is released.
All registered objects are released when the bind context is released.
See Also