FindItemType Class
The FindItemType class represents a query to find items in a mailbox.
Inheritance Hierarchy
System.Object
ExchangeWebServices.BaseRequestType
ExchangeWebServices.FindItemType
Namespace: ExchangeWebServices
Assembly: EWS (in EWS.dll)
Syntax
'Declaration
<SerializableAttribute> _
Public Class FindItemType _
Inherits BaseRequestType
'Usage
Dim instance As FindItemType
[SerializableAttribute]
public class FindItemType : BaseRequestType
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
Property |
Description |
|---|---|
Identifies the paging mechanism of the result set. This property is optional. |
|
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. |
|
Identifies which item properties are returned for the items in the result set. |
|
Identifies which folders are searched. |
|
Identifies a set of parameters that define a filter on the items that are returned in the result set. This property is optional. |
|
Identifies how the items are ordered in the results set. This property is optional. |
|
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 Microsoft Exchange Server 2007 database and therefore do affect the performance of the computer that is running Microsoft Exchange, while FindItem queries only affect performance when the queries are received by the Microsoft 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 is returned in the FindItem call. DisplayName, EmailAddress, 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.
Examples
The following code example shows a find item query that returns the following results:
An indexed query result that starts at the beginning of the result set and returns at most 10 entries from the result set.
A grouped search that does the following:
Aggregates the groups by the minimum value of the subject property.
Groups items based on the Importance property.
Returns groups in descending order. In this example, the order is determined by the minimum value of the subject property.
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.
Items found in the Calendar default folder.
Only items that have a start time that is after the current time.
Items sorted by the Subject property.
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 findItemRequest = new FindItemType();
// 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.
findItemRequest.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.
findItemRequest.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.
findItemRequest.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.
findItemRequest.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;
findItemRequest.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;
findItemRequest.SortOrder = fieldsOrder;
// Define the traversal type.
findItemRequest.Traversal = ItemQueryTraversalType.Shallow;
try
{
// Send the FindItem request and get the response.
FindItemResponseType findItemResponse = esb.FindItem(findItemRequest);
// 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);
}
}
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
See Also