IBindCtx::RegisterObjectParam

Stores a pointer to the specified object under the specified key in the bind context's string-keyed table of pointers. The method calls IUnknown::AddRef on the stored pointer.

HRESULT RegisterObjectParam(

LPOLESTR pszKey,	//Points to the key to be used
IUnknown *punk	//Points to the object to be associated with the key
);

Parameters

pszKey

[in] Points to a zero-terminated string containing the key under which the object is being registered. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character. Key string comparsion is case sensitive.

punk

[in] Points to the object that is to be registered.

Return Values

S_OK

The pointer was successfully registered under the specified string.

E_OUTOFMEMORY

Indicates insufficient memory.

Comments

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 the IBindCtx::GetObjectParam method to retrieve the stored pointer.

Notes to Callers

You can call IBindCtx::RegisterObjectParam if you are either a moniker implementor or a sophisticated moniker client.

If you're a moniker implementor and an error occurs during moniker binding, you can use one of the keys predefined by OLE to inform the caller of the cause of an error. The following list describes the keys associated with various error conditions:

MK_E_EXCEEDEDDEADLINE

If a binding operation exceeds its deadline because a given object is not running, then 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. The most common reasons for returning this value 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 (i.e., the server for the object identified by this moniker could not be located). If this key is used in an OLE compound-document situation, the caller can use IMoniker::BindToStorage to bind to the object, and then try to carry out a Treat As... or Convert To... operation to associate the object with a different server. If this is successful, the caller can retry the binding operation.

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 API function).

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

IBindCtx::GetObjectParam, IBindCtx::RevokeObjectParam, IBindCtx::EnumObjectParam

Software for developers

Delphi Components
.Net Components
Software for Android Developers

More information resources

MegaDetailed.Net
Unix Manual Pages
Delphi Examples

Databases for Amazon shops developers

Amazon Categories Database
Browse Nodes Database