IConnectionPoint::Advise
A version of this page is also available for
4/8/2010
This method establishes a connection between the connection point object and the client's sink.
Syntax
HRESULT Advise(
IUnknown* pUnk,
DWORD* pdwCookie
);
Parameters
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 established, this value is zero.
Return Value
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 can 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.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
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.
Requirements
| Header | ocidl.h, ocidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |