Enhancing Component Usability

To enhance the usability of your component, you may choose to implement the optional IPipelineComponentDescription interface. This interface defines methods that return SAFEARRAY variables that identify the pipe context elements that a component reads, as well as the OrderForm or Dictionary object elements that a component reads and writes.

When a user activates the property pages for your component through the Pipeline Editor, the Pipeline Editor checks to see if your component implements the IPipelineComponentDescription interface. If it does, the Pipeline Editor invokes your IPipelineComponentDescription method implementations and displays the values that the component reads and writes in a property page.

When you run the ATL Pipeline Component Wizard, the wizard adds a reference to the IPipelineComponentDescription interface to your derivation list, and adds the IPipelineComponentDescription interface signatures to the class definition. For example:

// IPipelineComponentDescription
    STDMETHOD (ContextValuesRead)(VARIANT *pVar);
    STDMETHOD (ValuesRead)(VARIANT *pVar);
    STDMETHOD (ValuesWritten)(VARIANT *pVar);

In addition, the ATL Pipeline Component Wizard adds stub implementations to implement files. The code the wizard adds is:

//
// IPipelineComponentDescription Methods
//
STDMETHODIMP CSampleComponent::ContextValuesRead(VARIANT *pVarRead)
{
    // TODO: Add your own values to the array
    int cEntries = 1;
    // Allocate the SAFEARRAY of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, cEntries);
    // Populate the SAFEARRAY of VARIANTs
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"Example Context Value Read");
    V_VT(pvarT) = VT_BSTR;
    // Set up the return value to point to the SAFEARRAY
    V_VT(pVarRead) = VT_ARRAY | VT_VARIANT;
    V_ARRAY(pVarRead) = psa;
    return S_OK;
}

STDMETHODIMP CSampleComponent::ValuesRead(VARIANT *pVarRead)
{
    // TODO: Add your own values to the array
    int cEntries = 1;
    // Allocate the SAFEARRAY of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, cEntries);
    // Populate the SAFEARRAY of VARIANTs
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"Example Value Read");
    V_VT(pvarT) = VT_BSTR;
    // Set up the return value to point to the SAFEARRAY
    V_VT(pVarRead) = VT_ARRAY | VT_VARIANT;
    V_ARRAY(pVarRead) = psa;
    
    return S_OK;
}

STDMETHODIMP CSampleComponent::ValuesWritten(VARIANT *pVarWritten)
{
    // TODO: Add your own values to the array
    int cEntries = 1;
    // Allocate the SAFEARRAY of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, cEntries);
    // Populate the SAFEARRAY VARIANTs
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"Example Value Written");
    V_VT(pvarT) = VT_BSTR;
    // Set up the return value to point to the SAFEARRAY
    V_VT(pVarWritten) = VT_ARRAY | VT_VARIANT;
    V_ARRAY(pVarWritten) = psa;
    return S_OK;
}

This code contains the basic instructions for implementing the interface.

Note

• Each of the methods in the IPipelineComponentDescription interface must return an array. If there are no association values, the IPipelineComponentDescription interface should return an empty array.

See Also

Deciding Which Interface to Expose

Implementing the IPipelineComponent Interface

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component

All rights reserved.