IConnectionPoint::Advise
Establishes a
connection between the connection point object and the client s sink.
HRESULT Advise(
|
IUnknown *pUnk , |
//Pointer to the client s advise sink |
|
DWORD *pdwCookie |
//Pointer to the connection point identifier used by
Unadvise |
|
); |
|
Parameter
pUnk
[in] Pointer
to the IUnknown
interface on the client s advise sink. The client s sink receives outgoing
calls from the connection point.
pdwCookie
[out] Pointer
to a returned token that uniquely identifies this connection. The caller uses
this token later to delete the connection by passing it to the IConnectionPoint::Unadvise method. If the connection
was not successfully established, this value is zero.
Return Values
This method
supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as
the following:
S_OK
The
connection has been established and *pdwCookie has the connection token.
E_POINTER
The value in pUnk
or pdwCookie is not valid. For example, either pointer may be NULL.
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.
Remarks
Advise establishes a connection between the connection point
and the caller s sink identified with pUnk.
The
connection point must call pUnk->QueryInterface(iid,
...) to obtain the correct outgoing
interface pointer to call when events occur, where iid is the IID for
the outgoing interface managed by the connection point. When iid is
passed to the IConnectionPointContainer::FindConnectionPoint method, an interface
pointer to this same connection point is returned.
Notes to Implementers
The
connection point must query the pUnk pointer for the correct outgoing interface.
If this query fails, this method must return CONNECT_E_CANNOTCONNECT.
The pdwCookie
value must be unique for each connection to any given instance of a connection
point.
See Also