Edit

Share via


FindItemType Class

Definition

The FindItemType class represents a query to find items in a mailbox.

public ref class FindItemType : ExchangeWebServices::BaseRequestType
public class FindItemType : ExchangeWebServices.BaseRequestType
Public Class FindItemType
Inherits BaseRequestType
Inheritance
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

Item Identifies the paging mechanism of the result set. This property is optional.
Item1 Identifies how the data is grouped in the result set. This property is optional. If this property is not set, no grouping will be applied.
ItemShape Identifies which item properties are returned for the items in the result set.
ParentFolderIds Identifies which folders are searched.
Restriction Identifies a set of parameters that define a filter on the items that are returned in the result set. This property is optional.
SortOrder Identifies how the items are ordered in the results set. This property is optional.
Traversal Identifies how the search is performed in the folders.

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

ConversationIndexConversationTopicCulture
DateTimeCreatedDateTimeReceivedDateTimeSent
DisplayCcDisplayToFrom
HasAttachmentsImportanceInReplyTo
InternetMessageIdIsDeliveryReceiptRequestedIsDraft
IsFromMeIsReadIsReadReceiptRequested
IsResendIsResponseRequestedIsSubmitted
IsUnmodifiedItemClassItemId
ParentFolderIdReferencesReminderDueBy
ReminderIsSetReminderMinutesBeforeStartSender
SensitivitySizeSubject

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

FindItemType()

The FindItemType constructor initializes a new instance of the FindItemType class.

Properties

Item

The Item property gets or sets the paging type that describes how the query result set is paged in the response. This property gets or sets either an IndexedPageViewType, FractionalPageViewType, CalendarViewType, or ContactsViewType object. This property is optional. This is a read/write property.

Item1

The Item1 property gets or sets the grouping type that describes how the query result set is grouped in the response. This property gets or sets either a GroupByType or DistinguishedGroupByType object. This property is optional. This is a read/write property.

ItemShape

The ItemShape property gets or sets the shape of the query set. This property is required. This is a read/write property.

ParentFolderIds

The ParentFolderIds property gets or sets the folders that the FindItem operation searches. This property is required. This is a read/write property.

QueryString
Restriction

The Restriction property gets or sets the search parameters that define an item query. This property is optional. This is a read/write property.

SortOrder

The SortOrder property gets or sets the sort order of items returned in the result set. This property is optional. This is a read/write property.

Traversal

The Traversal property gets or sets the traversal scheme that is used to search for items in folders. This property is required. This is a read/write property.

Applies to