IMAPITable::SetColumns

4/8/2010

The SetColumns method defines the particular properties and their order of appearance as columns in the table.

Note

This method is not supported on recipient tables.

Syntax

HRESULT SetColumns (
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags
);

Parameters

• lpPropTagArray
  [in] Reference to an array of property tags identifying properties to be included as columns in the table. The property type portion of each tag can be set to a valid type or to PR_NULL to reserve space for subsequent additions. lpPropTagArray cannot be set to NULL; every table must have at least one column.

• ulFlags
  [in] Not used; must be zero.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

• S_OK
  Indicates success.

• MAPI_E_BUSY
  Another operation is in progress that prevents the column setting operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

Remarks

The column set of a table is the group of properties that make up the columns for the rows in the table. There is a default column set for each type of table. The default column set is made up of the properties that the table implementer automatically includes. Table users can alter this default set by calling SetColumns. They can request that other columns be added to the default set (if the table implementer supports other columns), that columns be removed, or that the order of columns be changed. SetColumns specifies the columns that are returned with each row and the order of these columns within each row.

The success of the SetColumns operation is apparent only after a subsequent call has been made to retrieve the data of the table. It is then that any errors are reported.

When building the property tag array for the lpPropTagArray parameter, order the tags in the order that you want the columns to appear in the table view.

You can include property tags set to PR_NULL in the property tag array to reserve space in the column set. Reserving space allows you to add to a column set without having to allocate a new property tag array.

Code Example

The following code example demonstrates how to use SetColumns.

Note

To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

HRESULT SetColumnsExample(IMAPIFolder * pfldr) 
{
    HRESULT hr          = E_FAIL;   
    IMAPITable * pTable = NULL;
    ULONG rgTags[]      = {2, PR_MESSAGE_SIZE, PR_ENTRYID};
    SRowSet * psrs      = NULL;
    
    // Get the messages in this folder.
    hr = pfldr->GetContentsTable(NULL, &pTable);
    
    // Set the columns you want to retrieve.
    hr = pTable->SetColumns((LPSPropTagArray) rgTags, 0);
    // Loop through the messages in this folder.
    while (SUCCEEDED(pTable->QueryRows(1, 0, &psrs)))
    {
        // Check for the end of the table.
        if (psrs->cRows != 1)
        {
            break;
        }
        
        // Check that the table contains the columns you want.
        if (psrs->aRow[0].lpProps[0].ulPropTag == PR_MESSAGE_SIZE)
        {
            DEBUGMSG(TRUE, (L"PR_MESSAGE_SIZE: %d\r\n", psrs->aRow[0].lpProps[0].Value.ul));
        }
    }
     //Clean up
    FreeProws(psrs);
    return hr;
}

Requirements

Header	mapidefs.h
Library	cemapi.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Pocket PC 2002 and later, Smartphone 2002 and later

See Also

Reference

IMAPITable
IMAPITable::QueryRows
IMAPITable::Restrict
IMAPITable::SortTable
SPropTagArray
SPropValue
SRowSet

Other Resources

Messaging