Step Six: Describing the Component's Work

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 elements that a component reads and writes.

When a Pipeline Editor user activates the property pages for your component, the Pipeline Editor checks to see if your component implements IPipelineComponentDescription. 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 like this one.

When you run the Pipeline Component Wizard, the wizard adds a reference to IPipelineComponentDescription to your CMinMaxShipping derivation list, and adds the IPipelineComponentDescription function signatures to the class defintion.

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

In addition, the wizard adds stub implementations to the CMinMaxShipping implementation file. The code added by the wizard looks like this:

//
// IPipelineComponentDescription Methods
//
STDMETHODIMP CMinMaxShipping::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 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 CMinMaxShipping::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 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 CMinMaxShipping::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 form implementing the interface. The following code illustrates the modifications that you make to the stub implementation to make it accurately reflect that values that the MinMaxShip component actually reads and writes:

STDMETHODIMP CMinMaxShipping::ContextValuesRead(VARIANT *pVarRead)
{
    // allocate the safearray of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, 0);

    // 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 CMinMaxShipping::ValuesRead(VARIANT *pVarRead)
{
    // allocate the safearray of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, 1);

    // Populate the safearray variants
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"item._product_list_price");
    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 CMinMaxShipping::ValuesWritten(VARIANT *pVarWritten)
{

    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"order._shipping_total");
    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;

}

Note  If your component does not read or write values to the OrderForm, you must still return a SAFEARRAY, even though the SAFEARRAY will most likely be empty.