IConnectionPoint Interface

The IConnectionPoint interface is the key interface for managing connection points in the COM connection architecture.

A connection point represents a source of outgoing calls (events) that a COM object can expose. Clients can connect to these connection points to receive event notifications. The IConnectionPoint interface allows clients to discover information about the outgoing interface supported by the connection point and to establish or terminate connections.

Methods

Remarks

The connection point model is fundamental to COM's event handling mechanism. Objects that expose events implement the outgoing interfaces corresponding to those events. To manage these outgoing interfaces and the clients that listen to them, they expose connection points. A connection point is an object that implements the IConnectionPoint interface.

Clients interested in receiving events from an object typically enumerate the connection points exposed by that object using IEnumConnectionPoints. For each connection point, the client queries for the outgoing interface supported by that connection point using GetConnectionInterface. Once the client has identified the desired outgoing interface (and its corresponding IID), it can then call Advise on the connection point, passing a pointer to an object that implements the outgoing interface (this object is often called a "sink"). The Advise method returns a cookie that can be used later to disconnect using Unadvise.

See Also

• IConnectionPointContainer
• IEnumConnectionPoints
• IEnumConnections
• Connection Points Overview

Example

Illustrative C++ code snippet demonstrating the use of Advise:

#include <windows.h>
#include <iostream>

// Assuming pConnPoint is a valid IConnectionPoint pointer
// and pSink is a valid pointer to an object implementing the outgoing interface

HRESULT hr;
DWORD dwCookie;

// Advise the connection point
hr = pConnPoint->Advise(pSink, &dwCookie);

if (SUCCEEDED(hr)) {
    std::cout << "Successfully advised. Cookie: " << dwCookie << std::endl;
    // ... perform operations that trigger events ...

    // Unadvise when done
    hr = pConnPoint->Unadvise(dwCookie);
    if (SUCCEEDED(hr)) {
        std::cout << "Successfully unadvised." << std::endl;
    } else {
        std::cerr << "Failed to unadvise: " << std::hex << hr << std::endl;
    }
} else {
    std::cerr << "Failed to advise: " << std::hex << hr << std::endl;
}

// Release the connection point when no longer needed
if (pConnPoint) {
    pConnPoint->Release();
}
// Release the sink if it was created specifically for this connection
if (pSink) {
    pSink->Release();
}