IConnectionPoint::Advise

HRESULT IConnectionPoint::Advise([in] IUnknown *pUnk, [out] DWORD *pdwCookie);

Establishes an advisory connection between the connection point and the caller's sink object identified with pUnk. The connection point must call pUnk->QueryInterface(iid, ...) on this pointer in order to obtain the correct outgoing interface pointer to call when events occur, where iid is the inherent outgoing interface IID managed by the connection point (that is, that when passed to IConnectionPointContainer::FindConnectionPoint would return an interface pointer to this same connection point).

Upon successful return, the connection point provides a unique cookie in *pdwCookie that must be later passed to IConnectionPoint::Unadvise to terminate the connection.

Argument

Type

Description

pUnk

IUnknown *

[in] The IUnknown pointer to the client's sink that wishes to receive calls for the outgoing interface managed by this connection point. The connection point must query this pointer for the correct outgoing interface. If this query fails, this member returns CONNECT_E_CANNOTCONNECT.

pdwCookie

DWORD *

[out] A pointer to the caller's variable that is to receive the connection cookie when connection is successful. This cookie must be unique for each connection to any given instance of a connection point.


Return Value

Meaning

S_OK

The connection has been established and *pdwCookie has the connection key.

E_POINTER

The value of pUnk or pdwCookie is not valid (NULL cannot be passed for either argument)

E_UNEXPECTED

An unknown error occurred.

E_OUTOFMEMORY

There was not enough memory to complete the operation, such as if the connection point failed to allocate memory in which to store the sink's interface pointer.

CONNECT_E_ADVISELIMIT

The connection point has already reached its limit of connections and cannot accept any more.

CONNECT_E_CANNOTCONNECT

The sink does not support the interface required by this connection point.