FindItemType Class

Definition

public ref class FindItemType : ExchangeWebServices::BaseRequestType

public class FindItemType : ExchangeWebServices.BaseRequestType

Public Class FindItemType
Inherits BaseRequestType

Inheritance

Object

BaseRequestType

FindItemType

Examples

The following code example shows a find item query that returns the following results:

1. An indexed query result that starts at the beginning of the result set and returns at most 10 entries from the result set.
2. A grouped search that does the following:
3. All the properties that are defined for the AllProperties shape, in addition to the IsMeeting and Importance properties. Note that the AllProperties shape is different in a FindItem operation than it is in a GetItem operation.
4. Items found in the Calendar default folder.
5. Only items that have a start time that is after the current time.
6. Items sorted by the Subject property.
7. Items found only in the top level of the searched folder.

static void FindItem()
{
    // Create the service binding.
    ExchangeServiceBinding esb = new ExchangeServiceBinding();
    esb.Credentials = new NetworkCredential("username", "password", "domain");
    esb.Url = @"https://ExchangeServer/EWS/Exchange.asmx";

    // Form the FindItem request.
    FindItemType <span class="label">findItemRequest</span> = new <span class="label">FindItemType</span>();

    // Define the paging scheme for the result set.
    IndexedPageViewType ipvt = new IndexedPageViewType();
    ipvt.BasePoint = IndexBasePointType.Beginning;
    ipvt.MaxEntriesReturned = 10;
    ipvt.MaxEntriesReturnedSpecified = true;
    ipvt.Offset = 0;
    // Add the paging scheme to the request.
<span class="label">findItemRequest</span>.Item = ipvt;

    // Define the grouping scheme for the result set.
    GroupByType group = new GroupByType();
    // Define the property that is used to determine the order of groups of items in a group.
    AggregateOnType aggregate = new AggregateOnType();
    PathToUnindexedFieldType subject = new PathToUnindexedFieldType();
    subject.FieldURI = UnindexedFieldURIType.itemSubject;
    aggregate.Item = subject;
    aggregate.Aggregate = AggregateType.Minimum;
    group.AggregateOn = aggregate;
    // Define the property that is used to group items.
    PathToUnindexedFieldType importance = new PathToUnindexedFieldType();
    importance.FieldURI = UnindexedFieldURIType.itemImportance;
    group.Item = importance;
    // Define how the groups are ordered in the response.
    group.Order = SortDirectionType.Descending;
    // Add the grouping scheme to the request.
<span class="label">findItemRequest</span>.Item1 = group;

    // Define the item properties that are returned in the response.
    ItemResponseShapeType itemProperties = new ItemResponseShapeType();
    // Use the Default shape for the response.            
    itemProperties.BaseShape = DefaultShapeNamesType.Default;
    // Add more properties to the request.
    PathToUnindexedFieldType addIsMeeting = new PathToUnindexedFieldType();
    PathToUnindexedFieldType addImportance = new PathToUnindexedFieldType();
    addIsMeeting.FieldURI = UnindexedFieldURIType.calendarIsMeeting;
    addImportance.FieldURI = UnindexedFieldURIType.itemImportance;
    itemProperties.AdditionalProperties = new PathToUnindexedFieldType[2];
    itemProperties.AdditionalProperties[0] = addIsMeeting;
    itemProperties.AdditionalProperties[1] = addImportance;
    // Add the properties shape to the request.
<span class="label">findItemRequest</span>.ItemShape = itemProperties;

    // Identify which folders to search.
    DistinguishedFolderIdType[] folderIDArray = new DistinguishedFolderIdType[1];
    folderIDArray[0] = new DistinguishedFolderIdType();
    folderIDArray[0].Id = DistinguishedFolderIdNameType.calendar;
    // Add folders to the request.
<span class="label">findItemRequest</span>.ParentFolderIds = folderIDArray;

    // Create a restriction for the result set.
    RestrictionType restriction = new RestrictionType();
    PathToUnindexedFieldType pteft = new PathToUnindexedFieldType();
    pteft.FieldURI = UnindexedFieldURIType.calendarStart;
    FieldURIOrConstantType fieldURIORConstant = new FieldURIOrConstantType();
    fieldURIORConstant.Item = new ConstantValueType();
    (fieldURIORConstant.Item as ConstantValueType).Value = DateTime.Now.ToString();
    IsGreaterThanType isGreaterThan = new IsGreaterThanType();
    isGreaterThan.Item = pteft;
    isGreaterThan.FieldURIOrConstant = fieldURIORConstant;
    restriction.Item = isGreaterThan;
<span class="label">findItemRequest</span>.Restriction = restriction;

    // Define the sort order of items.
    FieldOrderType[] fieldsOrder = new FieldOrderType[1];
    fieldsOrder[0] = new FieldOrderType();
    PathToUnindexedFieldType subjectOrder = new PathToUnindexedFieldType();
    subjectOrder.FieldURI = UnindexedFieldURIType.itemSubject;
    fieldsOrder[0].Item = subjectOrder;
    fieldsOrder[0].Order = SortDirectionType.Ascending;
<span class="label">findItemRequest</span>.SortOrder = fieldsOrder;

    // Define the traversal type.
<span class="label">findItemRequest</span>.Traversal = ItemQueryTraversalType.Shallow;

    try
    {
        // Send the FindItem request and get the response.
        FindItemResponseType findItemResponse = esb.FindItem(<span class="label">findItemRequest</span>);

        // Access the response message.
        ArrayOfResponseMessagesType responseMessages = findItemResponse.ResponseMessages;
        ResponseMessageType responseMessage = responseMessages.Items[0];

        if (responseMessage is FindItemResponseMessageType)
        {
            FindItemResponseMessageType firmt = (responseMessage as FindItemResponseMessageType);
            FindItemParentType fipt = firmt.RootFolder;
            object obj = fipt.Item;

            // Determine whether the FindItem response contains grouped items.
            if (obj is ArrayOfGroupedItemsType)
            {
                ArrayOfGroupedItemsType groupedItems = (obj as ArrayOfGroupedItemsType);
                //TODO: Write code to handle grouped items.
            }

            // FindItem contains an array of items.
            else if (obj is ArrayOfRealItemsType)
            {
                ArrayOfRealItemsType items = (obj as ArrayOfRealItemsType);
                //TODO: Write code to handle items.
            }
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }
}

Remarks

The FindItemType class provides many options for querying a mailbox. Although the FindItem query is limited to shallow and soft-deleted searches of a set of folders, many options are available for creating complex search expressions and views of the search result set. The FindItemType class contains a set of properties that are used to set the parameters of the search. The following table lists the properties that describe the different parameters that are used to construct queries.

Properties that are used to construct queries

The FindItem query should be used for queries that change frequently and that do not require a deep traversal of the folder structure. If a specific search is performed regularly, it may be more appropriate to create a search folder for the search. Note that search folders can also perform deep traversals of the folder structure.

Important: Search folders run in the Exchange Server 2007 database and therefore do affect the performance of the computer that is running the Exchange server, while FindItem queries only affect performance when the queries are received by the Exchange server.

The FindItem query will provide much of the information that a client application needs. It basically returns a summary of an item. FindItem returns only the first 512 bytes of any streamable property. For Unicode, it returns the first 255 characters by using a null-terminated Unicode string.

Note: FindItem does not return a message body, attachments, or recipient lists.

Use GetItemType to get the details of specific items. GetItem returns more properties than FindItem. If more information is required, a client application must perform a FindItem call and then use the item identifiers in a GetItem call to get the properties that are not available in the FindItem call.

The following table lists the properties that are returned in both the FindItem and GetItem calls.

Properties that are returned in FindItem and GetItem calls

Note: Although the Sender property is returned in both FindItem and GetItem calls, only the DisplayName (string) is returned in the FindItem call. DisplayName (string), EmailAddress (NonEmptyStringType), and RoutingType (EmailAddress) are returned by the GetItem call.

The Item and Item1 properties are created by the proxy generation process and how it handles XML schema choice elements. The Item property is set with an object that extends the BasePagingType class. This property describes which type of view will be returned in the response. The Item1 property is set with an object that extends the BaseGroupByType class. This property describes how the response will group items in the result set. For more information about these properties, see XML Schema Choice Element Proxy Artifacts.

Constructors

Properties

Applies to