Symantec Enterprise Vault: Application Programmer's Guide

Symantec Enterprise Vault™
Application Programmer’s Guide
Enterprise Vault 9.0 SP1

Symantec Enterprise Vault: Application
Programmer’s Guide
The software described in this book is furnished under a license agreement and may be
used only in accordance with the terms of the agreement.
Last updated: November 19, 2010.
Legal Notice
Copyright © 2010 Symantec Corporation. All rights reserved.
Symantec, the Symantec Logo, Veritas, Enterprise Vault, Compliance Accelerator, and
Discovery Accelerator are trademarks or registered trademarks of Symantec Corporation
or its affiliates in the U.S. and other countries. Other names may be trademarks of their
respective owners.
This Symantec product may contain third party software for which Symantec is required
to provide attribution to the third party (“Third Party Programs”). Some of the Third Party
Programs are available under open source or free software licenses. The License
Agreement accompanying the Software does not alter any rights or obligations you may
have under those open source or free software licenses. Please see the Third Party
Software file accompanying this Symantec product for more information on the Third
Party Programs.
The product described in this document is distributed under licenses restricting its use,
copying, distribution, and decompilation/reverse engineering. No part of this document
may be reproduced in any form by any means without prior written authorization of
Symantec Corporation and its licensors, if any.
THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED

CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH
DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION SHALL
NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION
WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE
INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE
WITHOUT NOTICE.
The Licensed Software and Documentation are deemed to be commercial computer

software as defined in FAR 12.212 and subject to restricted rights as defined in FAR
Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS
227.7202, "Rights in Commercial Computer Software or Commercial Computer Software
Documentation", as applicable, and any successor regulations. Any use, modification,
reproduction release, performance, display or disclosure of the Licensed Software and
Documentation by the U.S. Government shall be solely in accordance with the terms of
this Agreement.
Symantec Corporation
350 Ellis Street
Mountain View, CA 94043
http://www.symantec.com
Technical Support
In order to develop software using Enterprise Vault APIs, your company must be
a member of Symantec Technology Enabled Program (STEP).
For details of the technical support available to you, refer to your STEP
membership documentation, or contact the STEP office at
TechPartner@symantec.com.
Further information about STEP is available at the following address:
http://go.symantec.com/step
Contents
Technical Support .................................................................................................. 3
Chapter 1 About this guide

Introducing this guide .........................................................................................15
Enterprise Vault documentation .......................................................................15
Comment on the documentation .......................................................................15
Chapter 2 API updates

Notice of future changes .....................................................................................17
Enterprise Vault 9.0 .............................................................................................18
Enterprise Vault 8.0 SP5 .....................................................................................18
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0
SP5 ..................................................................................................................31
Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4
33
Chapter 3 Enterprise Vault

API overview
Overview of Enterprise Vault APIs ...................................................................37
Prerequisite software and settings ...................................................................39
Licensing ...............................................................................................................40
Deploying an application that uses the API ....................................................41
Installing the Enterprise Vault SDK .................................................................44
Programming notes .............................................................................................46
Chapter 4 Content Management API

About the Content Management API ................................................................49
6 Contents
General guidelines for using the API ................................................................ 52

Enumerations ....................................................................................................... 58
ContentManagementAPI object ........................................................................ 69
IContentManagementAPI :: Archive ................................................................. 73
IContentManagementAPI :: Item ...................................................................... 75
IContentManagementAPI :: Holds .................................................................... 77
IContentManagementAPI :: Hold ...................................................................... 79
IContentManagementAPI :: DirectoryDNSAlias ............................................. 81
IContentManagementAPI :: AuthenticationMode .......................................... 83
IContentManagementAPI2 :: VaultStores ....................................................... 85
IContentManagementAPI2 :: VaultStore ......................................................... 87
IContentManagementAPI2 :: Archives ............................................................. 89
IContentManagementAPI3 :: Items .................................................................. 90
IContentManagementAPI3 :: IDispatchQueryInterface ................................ 91
IContentManagementAPI4 :: LastError ........................................................... 93
VaultStores object ............................................................................................... 94
IVaultStores :: Computer .................................................................................... 96
VaultStore object ................................................................................................. 98
IVaultStore :: Id .................................................................................................. 100
IVaultStore :: Name ........................................................................................... 102
IVaultStore :: Description ................................................................................. 103
IVaultStore :: Status .......................................................................................... 104
IVaultStore :: ArchiveCount ............................................................................. 105
IVaultStore :: DirectoryDNSAlias .................................................................... 107
IVaultStore :: Get ............................................................................................... 108
Archives object ................................................................................................... 109
IArchives :: Computer ....................................................................................... 112
IArchives :: VaultStoreId .................................................................................. 114
IArchives :: ArchiveName ................................................................................. 115
IArchives :: Permissions ................................................................................... 117
IArchives :: ArchiveTypes ................................................................................ 119
Archive object ..................................................................................................... 120
IArchive :: VaultStoreId .................................................................................... 123
IArchive :: Id ....................................................................................................... 124
IArchive :: Name ................................................................................................. 126
IArchive :: Description ...................................................................................... 128
IArchive :: ExpireItems ..................................................................................... 130
IArchive :: ConvertedContent .......................................................................... 132
IArchive :: IndexUrgency .................................................................................. 134
IArchive :: IndexLevel ....................................................................................... 136
IArchive :: Size ................................................................................................... 138
IArchive :: SecurityDescriptor ......................................................................... 140
IArchive :: ComplianceDevice .......................................................................... 142
Contents 7
IArchive :: ItemCount ........................................................................................144

IArchive :: Create ................................................................................................146
IArchive :: Get .....................................................................................................149
IArchive2 :: Type ................................................................................................150
IArchive2 :: Status ..............................................................................................151
IArchive2 :: HasFolders .....................................................................................152
IArchive2 :: Full ..................................................................................................153
IArchive2 :: DirectoryDNSAlias .......................................................................154
IArchive3 :: SecurityDescriptor .......................................................................155
IArchive3 :: SecurityDescriptorString ............................................................157
IArchive3 :: Type ................................................................................................160
Items object .........................................................................................................162
IItems :: ArchiveId .............................................................................................166
IItems :: StartSequenceNum ............................................................................168
IItems :: OrderBy ................................................................................................170
Item object ..........................................................................................................172
IItem :: ArchiveId ...............................................................................................175
IItem :: Id .............................................................................................................177
IItem :: Content ...................................................................................................179
IItem :: ArchiveMetaData .................................................................................181
IItem :: BrowserViewURL .................................................................................183
IItem :: DefaultMSGFormat ..............................................................................185
IItem :: Holds .......................................................................................................187
IItem :: NativeItemURL .....................................................................................188
IItem :: DeletionLevel ........................................................................................190
IItem :: CopyOptions ..........................................................................................192
IItem :: Insert ......................................................................................................196
IItem :: Get ...........................................................................................................200
IItem :: Delete .....................................................................................................204
IItem :: CanBeDeleted ........................................................................................206
IItem :: CopyTo ...................................................................................................208
IItem :: MoveTo ..................................................................................................212
IItem2 :: DeletionReason ...................................................................................215
IItem3 :: Undelete ...............................................................................................217
Content object .....................................................................................................220
IContent :: Title ...................................................................................................222
IContent :: OriginalLocation .............................................................................223
IContent :: FileExtension ..................................................................................224
IContent :: MIMEFormat ...................................................................................226
IContent :: CreatedDate .....................................................................................228
IContent :: ModifiedDate ...................................................................................230
IContent :: Data ...................................................................................................232
IContent :: OriginalSize .....................................................................................234
8 Contents
IContent :: Author .............................................................................................. 235

ArchiveMetaData object ................................................................................... 237
IArchiveMetaData :: RetentionCategory ........................................................ 240
IArchiveMetaData :: ComplianceDevice ......................................................... 242
IArchiveMetaData :: OverrideOnHoldRetCat ................................................ 243
IArchiveMetaData :: ArchivedDate ................................................................. 245
IArchiveMetaData :: ComplianceData ............................................................ 247
IArchiveMetaData :: SavesetSize .................................................................... 249
IArchiveMetaData :: RetentionExpires .......................................................... 251
IArchiveMetaData :: IndexData ....................................................................... 253
IArchiveMetaData :: IsItemSecured ................................................................ 255
IIArchiveMetaData :: CustomIdentifier .......................................................... 257
IIArchiveMetaData :: CustomQualifier ........................................................... 259
IIArchiveMetaData :: CustomProperties ........................................................ 261
IArchiveMetaData :: Update ............................................................................. 263
IArchiveMetaData2 :: CurrentLocation .......................................................... 265
IArchiveMetaData2 :: CurrentFolderId .......................................................... 271
IArchiveMetaData2 :: SequenceNum .............................................................. 273
IArchiveMetaData2 :: ArchivedDate ............................................................... 275
SimpleIndexMetadata object ........................................................................... 277
ISimpleIndexMetadata :: _NewEnum ............................................................. 280
ISimpleIndexMetadata :: DateTimesUTC ...................................................... 282
ISimpleIndexMetadata :: Count ....................................................................... 283
ISimpleIndexMetadata :: Add .......................................................................... 284
ISimpleIndexMetadata :: Clear ........................................................................ 287
ISimpleIndexMetadata :: ToXML ..................................................................... 288
ISimpleIndexMetadata :: FromXML ................................................................ 290
ISimpleIndexMetadata :: ToLocalTime .......................................................... 291
ISimpleIndexMetadata :: ToUTCTime ............................................................ 292
SimpleIndexProperty object ............................................................................ 293
ISimpleIndexProperty :: Set ............................................................................. 294
ISimpleIndexProperty :: Name ........................................................................ 296
ISimpleIndexProperty :: Value ........................................................................ 299
ISimpleIndexProperty :: Searchable ............................................................... 301
ISimpleIndexProperty :: Retrievable .............................................................. 303
ISimpleIndexProperty :: System ...................................................................... 305
ComplianceData object ..................................................................................... 307
IComplianceData :: Units .................................................................................. 308
IComplianceData :: Value ................................................................................. 310
IComplianceData :: SetBy ................................................................................. 312
Holds object ........................................................................................................ 313
IHolds :: _NewEnum .......................................................................................... 316
IHolds :: Item ...................................................................................................... 317
Contents 9
IHolds :: Count ....................................................................................................318

IHolds :: GroupId ................................................................................................319
IHolds :: ConsumerGUID ...................................................................................321
IHolds :: Metadata ..............................................................................................323
IHolds :: Add ........................................................................................................325
IHolds :: PlaceHolds ...........................................................................................326
IHolds :: ReleaseHolds .......................................................................................328
IHolds2 :: ReleaseHolds2 ...................................................................................330
Hold object ..........................................................................................................332
IHold :: ArchiveId ...............................................................................................334
IHold :: ItemId .....................................................................................................336
IHold :: Id .............................................................................................................338
IHold :: Status .....................................................................................................340
IHold :: Metadata ................................................................................................341
IHold :: ConsumerGUID ....................................................................................342
IHold :: GroupId ..................................................................................................343
ICollectionBase : IDispatch ...............................................................................344
ICollectionBase :: Count ....................................................................................345
ICollectionBase :: _NewEnum ...........................................................................346
ICollectionBase :: Item .......................................................................................347
ICollectionBase :: Maximum .............................................................................348
ICollectionBase :: More ......................................................................................350
ICollectionBase :: Get .........................................................................................351
ICollectionBase :: Clear ......................................................................................353
ICollectionBase :: Reset .....................................................................................354
ExtendedErrorInfo object .................................................................................355
IExtendedErrorInfo :: Error ..............................................................................359
IExtendedErrorInfo :: Description ...................................................................360
IExtendedErrorInfo :: InnerError ....................................................................361
IExtendedErrorInfo :: InnerErrorDescription ...............................................362
IExtendedErrorInfo :: Source ...........................................................................363
DiagnosticsAPI object .......................................................................................364
IDiagnosticsAPI : Name ....................................................................................365
IDiagnosticsAPI : IsTraceEnabled ...................................................................366
IDiagnosticsAPI : LogEvent ..............................................................................367
IDiagnosticsAPI : Trace .....................................................................................368
Chapter 5 NSF Manager API

NSF Manager API ...............................................................................................371
Enumerations .....................................................................................................374
NSFManager object ............................................................................................375
INSFManager :: OpenNSF .................................................................................377
INSFManager :: CreateNSF ...............................................................................378
10 Contents
INSFManager :: CloseNSF ................................................................................. 379

INSFManager :: ViewNote ................................................................................ 380
INSFManager :: ImportNote ............................................................................. 381
INSFManager :: ExportNote ............................................................................. 382
INSFManager :: DeleteNote .............................................................................. 383
INSFManager :: InitializeNotes ....................................................................... 384
INSFManager :: TerminateNotes ..................................................................... 385
INSFManager :: SwitchToID ............................................................................. 386
Chapter 6 Retention API

Retention API ..................................................................................................... 387
Enumerations ..................................................................................................... 389
RetentionCategories object .............................................................................. 390
IRetentionCategories :: Count .......................................................................... 393
IRetentionCategories :: _NewEnum ................................................................ 394
IRetentionCategories :: Item ............................................................................ 396
IRetentionCategories :: DirectoryDNSAlias ................................................... 397
IRetentionCategories :: Lookup ....................................................................... 399
IRetentionCategories :: Create ......................................................................... 401
IRetentionCategories :: Add ............................................................................. 403
IRetentionCategories :: Update ........................................................................ 405
IRetentionCategories2 :: Get ............................................................................ 407
RetentionCategory object ................................................................................. 408
IRetentionCategory :: Period ............................................................................ 410
IRetentionCategory :: Units ............................................................................. 412
IRetentionCategory :: IsVisible ........................................................................ 414
IRetentionCategory :: Identifier ...................................................................... 416
IRetentionCategory :: Name ............................................................................. 418
IRetentionCategory :: Description .................................................................. 420
IRetentionCategory :: OnHold .......................................................................... 421
IRetentionCategory :: Locked ........................................................................... 423
IRetentionCategory2 :: ExpiryBasis ................................................................ 425
Chapter 7 Filtering APIs

About the Filtering APIs ................................................................................... 427
Exchange Filtering API ..................................................................................... 429
Enumerations (Exchange filtering) ................................................................. 433
IExternalFilter interface ................................................................................... 435
IExternalFilter :: Initialize ................................................................................ 436
IExternalFilter :: ProcessFilter ........................................................................ 437
IExternalFilter :: FilteringComplete ............................................................... 438
IArchivingControl interface for Exchange filtering .................................... 439
Contents 11
IArchivingControl :: currentVaultId ...............................................................443

IArchivingControl :: currentRetentionCategoryId .......................................444
IArchivingControl :: defaultRetentionCategoryId ........................................445
IArchivingControl :: deleteOriginalItem ........................................................446
IArchivingControl :: createShortcutToItem ..................................................447
IArchivingControl :: Action ..............................................................................448
IArchivingControl :: MAPISession ..................................................................449
IArchivingControl :: MAPIMessage .................................................................450
IArchivingControl :: AddIndexedProperty .....................................................451
IArchivingControl :: IndexedPropertiesSet ...................................................452
IArchivingControl :: AddIndexPropertyToSet ..............................................453
IArchivingControl :: AddIndexPropertySet ...................................................454
IArchivingControl :: TransactionID ................................................................455
IArchivingControl :: AgentType ......................................................................456
IArchivingControl :: AgentAssignedRetentionCategoryId ..........................457
IArchivingControl :: AgentAssignedVaultId ..................................................458
IArchivingControl :: GetFilterProperty ..........................................................459
IArchivingControl :: PutFilterProperty ..........................................................460
IArchivingControl :: AttachmentAction .........................................................461
IArchivingControl :: RetryStatus .....................................................................462
IArchivingControl :: ReArchiveStatus ............................................................463
IArchivingControl2 :: BrowserViewURL ........................................................464
IArchivingControl2 :: NativeItemURL ............................................................465
IArchivingControl2 :: MessageClass ...............................................................466
IArchivingControl2 :: MAPISaveChanges ......................................................467
IArchivingControl3 :: SenderRecipientXML ..................................................468
IArchivingControl3 :: EnvelopeSenderRecipientXML ..................................470
IArchivingControl3 :: MessageDirection ........................................................472
Domino Filtering API .......................................................................................473
Enumerations (Domino filtering) ....................................................................476
IExternalFilter interface ...................................................................................478
IExternalFilter :: Initialize ................................................................................479
IExternalFilter :: ProcessFilter .........................................................................480
IExternalFilter :: FilteringComplete ................................................................481
IExternalFilter :: Shutdown ..............................................................................482
IArchivingControl interface .............................................................................483
IArchivingControl :: OriginalVaultID .............................................................484
IArchivingControl :: CurrentVaultID ..............................................................485
IArchivingControl :: OriginalRetentionCategoryID .....................................486
IArchivingControl :: CurrentRetentionCategoryID ......................................487
IArchivingControl :: IndexData .......................................................................488
IArchivingControl :: FilterProperties ..............................................................489
ILotusArchivingControl interface ...................................................................490
12 Contents
ILotusArchivingControl :: Action .................................................................... 491

ILotusArchivingControl :: NoteHandle .......................................................... 492
ILotusArchivingControl :: DatabaseHandle ................................................... 493
ILotusArchivingControl :: DatabaseName ..................................................... 494
ILotusArchivingControl :: SenderRecipientXML .......................................... 495
ILotusArchivingControl :: StoreIdentifier ..................................................... 497
ILotusArchivingControl :: Direction ............................................................... 498
IIndexMetadata interface ................................................................................. 499
IIndexMetadata :: ToXML ................................................................................. 500
IIndexMetadata :: FromXML ............................................................................ 501
IIndexMetadata :: Add ....................................................................................... 502
IIndexMetadata :: Clear ..................................................................................... 504
IIndexMetadata :: Count ................................................................................... 505
IIndexMetadata :: DateTimesUTC ................................................................... 506
IIndexProperty interface .................................................................................. 507
IIndexProperty :: Set ......................................................................................... 508
IIndexProperty :: Name ..................................................................................... 509
IIndexProperty :: Value ..................................................................................... 510
IIndexProperty :: Searchable ........................................................................... 511
IIndexProperty :: Retrievable ........................................................................... 512
IKeyedList interface .......................................................................................... 513
IKeyedList :: Insert ............................................................................................. 514
IKeyedList :: RemoveAt ..................................................................................... 515
Chapter 8 Search API

Introduction to storing and indexing ............................................................. 517
Using the Search API ........................................................................................ 519
Constants and enumerations ........................................................................... 533
SearchQuery object ........................................................................................... 537
ISearchQuery :: Query ....................................................................................... 540
ISearchQuery :: Clear ........................................................................................ 541
ISearchQuery :: SetTerm .................................................................................. 542
ISearchQuery :: AddTerm ................................................................................. 544
ISearchQuery :: SetRange ................................................................................. 546
ISearchQuery :: AddRange ............................................................................... 548
ISearchQuery :: SetProperty ............................................................................ 550
ISearchQuery :: AddProperty ........................................................................... 552
ISearchQuery :: AddOp ..................................................................................... 554
ISearchQuery :: Combine .................................................................................. 556
ISearchQuery :: AddQuery ................................................................................ 558
ISearchQuery2 :: SetPropertyRange ............................................................... 560
ISearchQuery2 :: AddPropertyRange ............................................................. 562
IndexSearch object ............................................................................................ 564
Contents 13
IIndexSearch2 :: IndexVolumeSets .................................................................568

IIndexSearch2 :: Options ...................................................................................570
IIndexSearch2 :: SortBy ....................................................................................572
IIndexSearch2 :: ResultsPropertySet ..............................................................573
IIndexSearch2 :: AdditionalResultsProperties ..............................................575
IIndexSearch2 :: Timeout ..................................................................................577
IIndexSearch2 :: ArchiveEntryId .....................................................................578
IIndexSearch2 :: ArchiveName ........................................................................579
IIndexSearch2 :: HasFolders .............................................................................580
IIndexSearch2 :: IndexVolumeSetIdentity .....................................................581
IIndexSearch2 :: IndexVolumeIdentity ..........................................................582
IIndexSearch2 :: IndexVolumeSetCount ........................................................583
IIndexSearch2 :: MaxSearchIndexVolumeSets .............................................584
IIndexSearch2 :: MaxSearchResultsPerVolumeSet ......................................586
IIndexSearch2 :: SelectArchive ........................................................................588
IIndexSearch2 :: ListIndexVolumeSets ...........................................................590
IIndexSearch2 :: SelectIndexVolumeSet ........................................................592
IIndexSearch2 :: SelectIndexVolume ..............................................................594
IIndexSearch2 :: Search ....................................................................................595
IIndexSearch2 :: SearchToXML .......................................................................598
IIndexSearch2 :: AddAdditionalResultsProperty ..........................................601
IIndexSearch2 :: AddAdditionalResultsCustomProperty ............................602
IIndexSearch2 :: Reset .......................................................................................604
IndexVolumeSets object ...................................................................................605
IIndexVolumeSets :: ArchiveEntryId ..............................................................607
IIndexVolumeSets :: ArchiveName .................................................................608
IIndexVolumeSets :: HasFolders ......................................................................609
IIndexVolumeSets :: Count ...............................................................................610
IIndexVolumeSets :: _NewEnum .....................................................................611
IIndexVolumeSets :: Item .................................................................................613
IndexVolumeSet object .....................................................................................615
IIndexVolumeSet :: Identity .............................................................................617
IIndexVolumeSet :: ArchiveEntryID ...............................................................618
IIndexVolumeSet :: ArchiveName ...................................................................619
IIndexVolumeSet :: FirstItemIndexSequenceNumber .................................620
IIndexVolumeSet :: OldestArchivedDate ........................................................621
IIndexVolumeSet :: YoungestArchivedDate ..................................................622
IIndexVolumeSet :: OldestItemDate ...............................................................623
IIndexVolumeSet :: YoungestItemDate ..........................................................624
IIndexVolumeSet :: DateTimesUTC ................................................................625
SearchResults object .........................................................................................627
ISearchResults :: Results ...................................................................................629
ISearchResults :: Count .....................................................................................631
14 Contents
ISearchResults :: Total ...................................................................................... 632

ISearchResults :: Start ...................................................................................... 633
ISearchResults :: Options ................................................................................. 634
ISearchResults :: SortBy ................................................................................... 635
ISearchResults :: _NewEnum ........................................................................... 636
ISearchResults :: Item ....................................................................................... 638
ISearchResults2 :: InSync ................................................................................. 640
ISearchResults2 :: TruncationReason ............................................................ 641
ISearchResults2 :: DateTimesUTC .................................................................. 643
ISearchResults2 :: LoadResults ........................................................................ 645
SearchResult object ........................................................................................... 646
ISearchResult :: Result ...................................................................................... 648
ISearchResult :: Number ................................................................................... 649
ISearchResult :: Prop ......................................................................................... 650
ISearchResult :: Prop2 ....................................................................................... 652
ISearchResult2 :: Count .................................................................................... 654
ISearchResult2 :: Item ....................................................................................... 655
ISearchResult2 :: DateTimesUTC .................................................................... 657
Appendix A About Enterprise Vault indexes

About index volume sets and volumes ........................................................... 659
About index schemas ........................................................................................ 660
Appendix B Enterprise Vault Properties

System properties .............................................................................................. 664
Defined custom properties ............................................................................... 680
Defined custom FSA properties ....................................................................... 681
Defined custom SharePoint properties .......................................................... 681
Defined properties for Compliance Accelerator ........................................... 682
Appendix C API return values

Content Management API return values ....................................................... 685
Retention API return values ............................................................................ 686
Search API return values .................................................................................. 687
External Filter API Event log messages ......................................................... 688
Index ......................................................................................................691
Chapter 1
About this guide
This chapter includes the following topics:
■ “Introducing this guide”
■ “Enterprise Vault documentation”
■ “Comment on the documentation”
Introducing this guide

This book describes the publicly available Application Programming Interfaces
(APIs) for Symantec Enterprise Vault. These enable developers to integrate
Enterprise Vault features with third-party applications.
The information in this manual relates to Symantec Enterprise Vault 6.0 SP5
and later releases.
Readers are assumed to have a good knowledge of Windows application
development languages and tools, in particular, C++/C#, COM, DCOM, and .NET.
Enterprise Vault documentation

This book is available as HTML Help and as a PDF file from Symantec
Technology Enabled Program (STEP) and OEM Partners Program.
The Enterprise Vault documentation set is shipped in the Enterprise Vault
server kit.
Comment on the documentation

Let us know what you like and dislike about the documentation. Were you able
to find the information you needed quickly? Was the information clearly
16 About this guide
Comment on the documentation
presented? Report errors and omissions, or tell us what you would find useful in
future versions of our guides and online help.
Please include the following information with your comment:
■ The title and product version of the guide you are commenting on
■ The topic (if relevant) you are commenting on
■ Your name
Email your comment to evdocs@symantec.com. Please only use this address to
comment on product documentation.
We appreciate your feedback.
Chapter 2
API updates
This chapter lists changes made to the APIs, SDK, or this API manual, and
advance notice of future changes to Enterprise Vault APIs.
Notice of future changes

This section lists significant changes to Enterprise Vault APIs in upcoming
releases.
Enterprise Vault Properties

From Enterprise Vault 10, the Enterprise Vault system property, shct, will no
longer be supported.
Search API
From Enterprise Vault 10, the Search API will not support the following search
operators for newly indexed items:
■ begins with any of (ESQBeginany)
■ begins with phrase (ESQBegins)
■ is exactly any of (ESQExactany)
■ ends with any of (ESQEndsany)
■ ends with phrase (ESQEnds)
■ automatically add wildcard to end of all words (ESQAutowild)
Using these search operators against previously indexed items will continue to
be supported.
18 API updates
Enterprise Vault 9.0

This section lists the changes and corrections made for Enterprise Vault 9.0.
Content Management API
Ref Change details
MSXML 6.0 or later is now required on the computer where you

install the Enterprise Vault API runtime.
900-1652 Guidance on thread priority has been added.

See “General guidelines for using the API” on page 52
900-2524 The sender and recipient index properties, and the Vault.MsgDirection and
Vault.MsgType custom index properties are now stored on item insert
operations. These properties are also preserved during copy and move item
operations.
900-2677 Added the method IItem3::Undelete.

If an item has been moved to the Enterprise Vault "dumpster" area (soft
deleted), this method can be used to recover the item.
See “IItem3 :: Undelete” on page 217
2050482 When inserting Outlook messages, either the FileExtension property must
have the value “.msg”, or the MIMEFormat property must have the value
“application/vnd.ms-outlook”, to provide full Enterprise Vault indexing and
storage optimization functionality. If you assign any other MIME type value
to an item, Enterprise Vault archives and indexes the item as a file.
See “IItem :: Insert” on page 196
See “IContent :: FileExtension” on page 224
See “IContent :: MIMEFormat” on page 226

This section lists the changes and corrections made for
Enterprise Vault 8.0 SP5.
API updates 19
Ref Change details
8053386, The property type for IArchive::Size was incorrectly shown as ULONGLONG
E2030385 instead of VT_UI8. This has been corrected.
See “IArchive :: Size” on page 138
E2133959 ISimpleIndexProperty :: Value now has a fuller description of possible values

for the property.
See “ISimpleIndexProperty :: Value” on page 299
Filtering APIs
Ref Change details
8054561, HARD_DELETE is now available as an option in the Domino action

E2096343 enumeration.
See “EV_ACTION enumeration” on page 433
E1980890 The following sections have been expanded to provide more information on
the filtering registry settings:
See “Exchange filtering registry settings” on page 430
See “Domino filtering registry settings” on page 474
E2095734 The remarks in the section, IArchivingControl2 :: MAPISaveChanges, now

clarify that changes made to messages are saved in the Exchange Server
store. The changes are saved in the archive when the message is
subsequently archived.
See “IArchivingControl2 :: MAPISaveChanges” on page 467
Enterprise Vault properties
Ref Change details
E2027779 Added the property, Vault.CopiedFrom, to the list of custom properties

defined in Enterprise Vault. This property provides details for items that
have been copied by Move Archive.
See “Defined custom properties” on page 680
20 API updates
Ref Change details
E2139819 The following index properties have been added to the list of Enterprise
Vault system properties:
■ Calendar start date (csrt)
■ Calendar end date (cend)
■ Calendar location (clon)
■ Task due date (tddt)
■ Task date completed (tcdt)
■ Task status (tsts)
See “System properties” on page 664


Enterprise Vault 8.0 SP4 includes the following changes and corrections to the
Content Management API documentation:
Ref Change details
E1927661 Updated IContent :: FileExtension section in the manual to clarify the when
a preceding period is included in file extensions.
See “IContent :: FileExtension” on page 224
E1533874 The manual indicated that the Vault Store ID must be set before Archive::Get
is called. This is incorrect. The manual has been updated.
E1669297 The description of the EV_STG_API_ITEM_DETAIL enumeration has been

expanded to show the properties that are returned for the different
enumeration values.
See “EV_STG_API_ITEM_DETAIL enumeration” on page 65
804-1613, When using the CopyTo function, the source item's Sender/Recipients P1
E1948433 data was not retained and merged with any specified custom index
properties for adding to the destination/copied item.
This has been fixed.
API updates 21
Ref Change details
8041728, If the converted content for an item or attachment is larger than 5MB, then
E1950563 it is not returned in the 'cont' property when a call to Item.Get requests
DETAIL_LEVEL__SYSTEM_INDEXDATA.
If required, you can override this limit using the registry setting,
HKLM\Software\KVS\Enterprise Vault\MaxIndexDataHTMLContentKB
The registry setting is documented in the Enterprise Vault Registry Values
manual.
See “IItem :: Get” on page 200
Search API
Search API documentation:
Ref Change details
E1448964 Information has been added to the Search API chapter on how to create
multiple index volume sets for testing search applications.
See “Performing a search” on page 524


Ref Change details
803151 A new interface, IItem2, has been added to the Content Management API.
This interface inherits from IItem, and provides the property,
DeletionReason, which enables calling applications to find out why an item
was deleted from the archive.
See “IItem2 :: DeletionReason” on page 215
22 API updates
Ref Change details
803137 Soft deleted items are no longer included when populating the Items
collection object.
See “Items object” on page 162
803069, When using the Archive object to retrieve details for an archive that was
E1630338 created prior to Enterprise Vault 7.0, the ConvertedContent and
IndexUrgency properties could contain misleading values, as these
properties were introduced at Enterprise Vault 7.0.
When retrieving details for pre-Enterprise Vault 7.0 archives, these
properties are now given the following default values:
IndexUrgency = INDEX_ITEMS_IMMEDIATELY
ConvertedContent = CONVERTED_CONTENT_STORED
E1810317 The S_FALSE return value has been documented for the following object
properties.
■ IItem::Id
■ IContent::OriginalLocation
■ IArchiveMetaData::RetentionCategory
■ IArchiveMetaData::CustomIdentifier
■ IArchiveMetaData::CustomQualifier
■ ArchiveMetaData::CustomProperties
■ IArchiveMetaData2::CurrentLocation
■ IArchiveMetaData2::CurrentFolderId
■ IArchiveMetaData2::ArchivedDate
These properties can return the default property value and an S_FALSE
return value when reading the property before it has been written. This is a
success return value. When coding in C++ the S_FALSE return value should
be handled using the Windows SUCCEEDED or FAILED macros.
803587, When populating very large Archives collection objects, the value of the
E1737966 Maximum property (the maximum number of records that can be returned)
was not honored. As a result, the operation failed, and insufficient resource
errors were reported.
803125, Sometimes files of between 5 MB and 50 MB were truncated when retrieved

E1726196, using the Content Management API .
E1739537 This has been fixed.
API updates 23
Ref Change details
803327, Retrieving large items (that is, files larger than 50 MB) resulted in corrupt
E1792685 data being returned. This has been fixed.
If Enterprise Vault 8.0 SP3 is installed on your Enterprise Vault server,
ensure that you install the Enterprise Vault 8.0 SP3 API runtime on your
client application computer. Failure to do this may result in insufficient
memory errors when attempting to retrieve large items.


Enterprise Vault 8.0 SP2 includes the following additions and changes to the
Ref Change details
802168 A new interface, IExtendedErrorInfo, has been added. This interface

provides extended error information if an error is encountered when using
the Content Management API methods.
See “ExtendedErrorInfo object” on page 355.
802077 EV_STG_API_AUTHENTICATE_USING enumeration has new value added:

AUTHENTICATE_USING_MOST_APPROPRIATE_MODE
See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 60.
802559, IContent::Title no longer needs to be populated before calling Insert.

E1703228,
See “IItem :: Insert” on page 196.
E1639951
802577, IArchive::Name and IArchive::Description can contain printable, Unicode

E1476982, characters.
E1600648
IArchive::Name is mandatory and cannot be blank or an empty string.
IArchive::Description is optional.
See “IArchive :: Name” on page 126, and “IArchive :: Description” on
page 128.
24 API updates


Enterprise Vault 8.0 SP1 includes the following additions and changes to the
Ref Change details
8010032 The new value, ITEM_COPYOPTIONS_MERGE_INDEXMETADATA, has been

added to the EV_STG_API_ITEM_COPYOPTIONS enumeration. This enables
additional custom index metadata properties on the source item to be added
to existing custom index metadata properties on the destination item.
See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 64
8010141 The new interface, IHolds2, has been added. This provides the method,
ReleaseHolds2, which can be used to release a hold on each item in a
collection, and also returns a summary status report, in XML, for each vault
store in which items were processed.
See “IHolds2 :: ReleaseHolds2” on page 330
8010204, If the source archive was in a read-only state, CopyTo failed and returned the
E1422959 error CONTENTMANAGEMENTAPI_E_BUSY.
Further changes have been made to support situations where an archive is in
a read-only state. The error
CONTENTMANAGEMENTAPI_E_NO_ACCESS
(Status code = 0x80040303)
is now returned when the following actions are attempted:
■ Copying an item when the destination archive is in a read-only state.
■ Moving an item when the source or destination archive is in a read-only
state.
■ Inserting, deleting, or changing the retention period for an item when
the archive is in a read-only state.
In addition, the IItem::CanBeDeleted property value will indicate
DELETE_ACCESS_DENIED for items located in an archive which is in a
read-only state.
API updates 25
Ref Change details
8010139 If a hold with the same ConsumerGUID or GroupId was reapplied to an item,
a new hold was created instead of returning the existing hold ID.

Minimum supported OS version

The Content Management API features introduced at Enterprise Vault 8.0
require Windows Server 2003 or later.
Changes to programming language support
Visual Basic 6.0

The new Content Management API features introduced at Enterprise Vault 8.0
support third party applications written in the Visual Basic .Net programming
language, but do not support third party applications written in Visual Basic 6.0.
Existing Visual Basic 6.0 applications that use Content Management API
features available in earlier releases of Enterprise Vault are not impacted.
Visual Basic Script

The ContentManagement API interfaces, IArchive3 and IArchiveMetaData2, are
not directly accessible by Visual Basic Script applications. To access properties
on these interfaces, the Visual Basic Script application can perform a
QueryInterface using the new IDispatchQueryInterface method and specifying
the required Interface Identifier (IID) string.
General changes
Audit logging can now be enabled for item operations.
See “Audit logging” on page 56.
The name of the Enterprise Vault SDK kit has changed to
Symantec Enterprise Vault Software Development Kit.msi
26 API updates
The name of the Enterprise Vault API runtime kit has changed to:
Symantec Enterprise Vault API Runtime.msi
NSF Manager API added

The NSF Manager API enables interaction between Enterprise Vault and Lotus
Notes databases.

Enterprise Vault 8.0 includes the following additions and changes to the Content
Management API documentation:
Ref Change details
■ The following new interfaces have been added to the Content

Management API:
IContentManagementAPI3
IArchive3
IItems
IArchiveMetaData2
BAU0819 ■ IContentManagementAPI3::
IDispatchQueryInterface method has been added to enable calling
applications written in Visual Basic Script to access IArchive3 and
IArchiveMataData2 properties.
See “IContentManagementAPI3 :: IDispatchQueryInterface” on
page 91.
BAU0819 ■ IArchive3 interface adds new read/write Type, SecurityDescriptor and

SecurityDescriptorString properties.
The SecurityDescriptorString property enables security permissions to
be specified using MSDN Security Descriptor String Format, as
described in the Microsoft article:
http://msdn.microsoft.com/en-us/library/aa379570.aspx
This property is recommended for retrieving and setting the security
descriptor from applications written in .NET managed code.
BAU0819 ■ The EV_STG_API_PERMISSIONS_TYPE enumerator is now used in

BAU2464 place of the DV_DS_E_PERMISSION enumerator when creating the
security descriptor for use with IArchive::SecurityDescriptor.
BAU0225 ■ A new interface, IItems, has been added to facilitate the enumeration of
items in an archive.
“Enumerating vault stores, archives and items” on page 53.
API updates 27
Ref Change details
BAU0778 ■ Significant changes have been made to facilitate copying and moving
BAU0795 items from one archive to another :
BAU1179 ■ The default action has changed; the item content and its
associated ArchiveMetaData and IndexData elements are copied
from the source item to the destination item. This means that the
new default behaviour preserves the original ArchivedDate and
OriginalLocation on the destination item, if override values are
not specified.
For backwards compatibility, the calling application can set
suitable override values on the destination item object.
■ A new CopyOptions property identifies the source item property
values to be copied to the destination item when copying or
moving items.
Override values can be set for specific Item properties.
See “Specifying item property override values” on page 193.
BAU0378 ■ IArchiveMetaData2 provides additional properties for determining the

archive folder location of an item:
■ The CurrentLocation or CurrentFolderId properties identify the
archive folder in which the item is stored, or to be stored.
See “Which properties determine the current archive folder” on
page 267.
BAU0378 ■ The new IArchiveMetaData2::SequenceNum property (ULONGLONG)

uniquely identifies an item in the archive. It can be used to identify the
start Index Sequence Number when enumerating collections of
archived items using the Items collection object.
Note that Windows Server 2003 supports ULONGLONG types with OLE
Automation. However ULONGLONG types are not supported on
Windows Server 2000 unless an additional component is installed. If
Windows Server 2000 support is required then the calling application
will need to specify this property value as a VARIANT VT_DECIMAL
type for handling 64 bit integer values.
BAU778 ■ A new read/write IArchiveMetaData2::ArchivedDate property enables

the caller to set the UTC date and time when an item was stored.
To prevent unauthorized users, who have write access to an archive,
from changing the archived date of an item, the calling application
must run under an account assigned to the Enterprise Vault Power
Administrator role or Storage Administrator role.
28 API updates
Ref Change details
BAU1179 ■ The following properties, which were previously hidden, have now been
BAU2853 exposed for public use:
IArchiveMetaData::CustomIdentifier
IArchiveMetaData::CustomQualifier
IArchiveMetaData::CustomProperties
These properties can be used to hold proprietary information about the
stored item.
CustomIdentifier and CustomQualifier can be used to identify items
when using Get.
BAU1761 ■ IHold::ItemId property value can now be a valid Saveset Id or

Transaction Id.
See “Saveset IDs and Transaction IDs” on page 54.
BAU1473 ■ The Content Management API now supports IStream and ILockBytes
implementations where the input data length provided by the Stat
method is not known.
BAU1796 ■ Enhancements to the API mean that .NET applications no longer need
to call CoInitializeSecurity when remotely accessing IStream or
IlockBytes objects containing large items (larger than 4MB).
■ The Content Management API threading model has been changed from
COM single-threaded apartment (STA) to Both, thus simplifying use in
.NET applications.
BAU2013 ■ MSXML 3.0 is now the minimum version of MSXML required on the
computer where you install the application using the Content
Management API.
API updates 29
Retention API
Table 2-1 Changes to Retention API
Ref Change details
BAU1072 Enabled the caller to set the date from which storage expiry is calculated.
Added the following interfaces, method and property:
■ IRetentionCategories2
Improved the retrieval of retention category details by providing a Get
method.
■ IRetentionCategory2
Provides ExpiryBasis property for determining date from which storage
expiry is calculated.
Migration API
Table 2-2 Change to Migration API
Ref Change details
BAU2485 The MigratedFileId parameter of the SendFile method identifies the object or
file in the external storage system, and must be unique within the partition.
The migrator must now explicitly set this value.
New index properties added
Table 2-3 New index properties
Ref Index property Description

name
BAU0585 crct Current Retention Category Id, searchable and retrievable
BAU0931 clcn Current location, retrievable only

cllf Current leaf folder name, retrievable only
clfn Current location folder names, retrievable only
crcn Current Retention Category name, retrievable only
BAU1320 cnhv Conversation Hierarchical View, retrievable only
BAU1426 fpdd Index Fingerprint of item, searchable and retrievable

fpcn Index Fingerprint of content, searchable and retrievable
30 API updates
Corrections
Table 2-4 Corrections
Ref Change details
1088101, The Storage service is no longer accessed when enumerating archives.

847952
1204891 The IContent::OriginalLocation property is now preserved when performing a

copy or move operation.
1271036 Description of IArchiveMetaData::RetentionExpires property has been

clarified. This property is for use with compliance devices, and requires the
item detail level set to DETAIL_LEVEL_COMPLIANCE_DATA.

Ref Change details
E1107082 Updated description of “IContent :: FileExtension” on page 224.
E1143215 Added description of the use of wildcard characters in ESQfilter searches.
E1167957 Updated information about supported combinations of properties in “Archives

object” on page 109.
E1185396 Added “IContentManagementAPI2 :: VaultStore” on page 87.
E1187820 Corrected description of “ISimpleIndexMetadata :: Count” on page 283.
E1188342 Corrected description of “IItem :: CanBeDeleted” on page 206.
E1191078 Added example format for the consumer GUID in

“IHold :: ConsumerGUID” on page 342.
E1193018 Updated information about retrieving items, and added information about
retrieving hold data, in “IItem :: Id” on page 177.
E1196051 Updated description of “ComplianceData object” on page 307 to note that it is

for use only with compliance devices, and updated Return values for
“IArchiveMetaData :: Update” on page 263.
API updates 31
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5
Ref Change details
E1203217 Updated Remarks section of “IHolds :: Item” on page 317 to note that the index
supplied to the property is 1-based not 0-based.
Enterprise Vault 2007 SP1, Enterprise Vault 7.0

SP3, and Enterprise Vault 6.0 SP5
This section lists the changes and corrections made for Enterprise Vault 2007
SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5.
Table 2-6 Changes and corrections
Ref Change details Availability
751207, ■ New sere index property. This property returns Enterprise Vault 6.0 SP5,
703021, sender and recipient details from the message Enterprise Vault 7.0 SP3,
605047 header (P2) if the archived item is a message. Enterprise Vault 2007 SP1
See Table B-1 on page 664.
■ menv index property changes. This property is
now only returned for journaled messages. It
returns sender recipient details from the
message envelope (P1) if the archived item is an
envelope message. See Table B-1 on page 664.
751208, ■ New interface for Exchange filtering, Enterprise Vault 6.0 SP5,
703020, IArchvingControl3, to retrieve sender and Enterprise Vault 7.0 SP3,
605036 recipient information as XML. See Enterprise Vault 2007 SP1
“IArchivingControl interface for Exchange
filtering” on page 439.
751127, ■ SimpleIndexProperty object: Added new Enterprise Vault 7.0 SP3,

703010 attachment number ("anum") in the returned Enterprise Vault 2007 SP1
index data with the attachment numbering
based on the attachment structure as stored in
the saveset indexable item data stream. See
“ISimpleIndexProperty :: Name” on page 296.
■ menv index property: This property now
includes the message sender/author and
delegate sender (if applicable) encoded in the
<AUTH> element. See Table B-1 on page 664.
32 API updates
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5
751143, ■ Previously, where an item’s content data was Enterprise Vault 7.0 SP3,
703011 unobtainable, the cont index metadata property Enterprise Vault 2007 SP1
value was returned with a string,
"<reason>:<type>", where reason was an error
code number and type was the item file type. For
example, "1:MSG".
Now the reason for missing content items is
returned in the content missing property (comr)
in the index metadata.
See Table B-1 on page 664.
703038, ■ IArchive::Create: updated description of Enterprise Vault 7.0 SP3,

E1143932 properties and examples. See “IArchive :: Enterprise Vault 2007 SP1
Create” on page 146.
API updates 33
Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4
Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and

This section lists the changes and corrections made for Enterprise Vault 2007,
Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4.
DOR610 ■ The following new Content Management API Enterprise Vault 2007
interfaces have been added to enhance
enumeration of archives and vault stores:
IContentManagementAPI2, IVaultStores,
IVaultStore, IArchives, IArchive2,
ICollectionBase. These interfaces supersede the
functionality previously provided by the
unsupported EnumVaultsByMe method.
■ DirectoryDNSAlias property in the Content
Management API and Retention API has been
enhanced to accept input of any Enterprise
Vault id, such as, archive Id, retention category
Id, vault store Id.
■ New IDiagnosticsAPI interface added to Content
Management API to enable application
integration tracing using Enterprise Vault
diagnostic tools.
DOR620 ■ Simple API removed from API Guide. Refer to Enterprise Vault 2007
previous releases of the manual for this
deprecated API.
■ Migration API included in API Guide.
■ Integrating third-party messaging removed and
now available as a tech note from Enterprise
Vault support knowledge base.
■ Provisioning API removed. This will be
incorporated in the Utilities Guide at a future
release.
34 API updates
702045, ■ When the enumerated value, Enterprise Vault 6.0 SP4,

604133, DETAIL_LEVEL_ITEM_CONTENT, was included Enterprise Vault 7.0 SP2
E974294 as part of the input parameter for the Content
Management API method, IItem::Get(), the
current date and time was returned by
IContent::ModifiedDate and
IContent::CreatedDate.
702045, ■ In previous releases, you could not retrieve Enterprise Vault 6.0 SP4,
604133 expanded distribution list information from the Enterprise Vault 7.0 SP2
XMLStream using the Content Management
API.
This information can now be accessed using the
existing IArchiveMetaData :: IndexData
property. It is retrieved in the menv index
property using the
DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEX
DATA value of the EV_STG_API_ITEM_DETAIL
enumeration.
Note that MSXML 4.0 is required for this feature.
See “EV_STG_API_ITEM_DETAIL enumeration”
on page 65.
The menv index property is described in
Table B-1 on page 664.
■ The value of ISimpleIndexProperty :: Name can
now be a formatted number (1, 1.1, 1.2 and so
on), which refers to a message attachment.
See “ISimpleIndexProperty :: Name” on
page 296.

CAP031 ■ It is now possible to use the transaction Id Enterprise Vault 7.0

instead of the saveset id when setting the
Item::Id property.
API updates 35
CAP433 ■ An API license is no longer required in order to Enterprise Vault 7.0

develop applications against the Enterprise
Vault APIs.
CAP463 ■ In previous releases, if an item had been marked Enterprise Vault 7.0
"on hold" using the retention category, then it
could not be deleted, and hence could not be
moved. This has been fixed.
CAP545, ■ IArchivingControl2 interface added to Exchange Enterprise Vault 7.0

CAP721, Server Filtering API.
E804597 This interface provides a new property and
method (MessageClass and MAPISaveChanges)
which provide improved handling of MAPI
Message Classes.
The interface also provides the properties,
BrowserViewURL and NativeViewURL, which
have been moved from IArchivingControl.
CAP525 ■ IContentManagementAPI has a new property: Enterprise Vault 7.0

E775452 AuthenticationMode, which specifies the mode
of authentication to be used when the calling
application contacts Enterprise Vault.
36 API updates
Chapter 3
Enterprise Vault
API overview
This chapter introduces the Enterprise Vault SDK and the APIs it comprises.
These can be used by applications to access Enterprise Vault functionality.
Overview of Enterprise Vault APIs

Enterprise Vault SDK comprises a number of APIs. The various Enterprise Vault
APIs are implemented as COM or .NET objects, which expose task-specific
interfaces. For example, archiving items uses the IContentMangementAPI and
IItem interfaces.
In general, applications which use the APIs should be run from a client
computer, and not on the Enterprise Vault server.
38 Enterprise Vault API overview
Overview of Enterprise Vault APIs
To help you choose the appropriate APIs for your application, the available APIs
are listed in Table 3-1. Examples of possible applications are also given to
provide guidance:
Table 3-1 Enterprise Vault APIs
Content Management API ■ Create archives.

■ Enumerate collections of vault stores, archives or items.
■ Get properties of vault stores and archives.
■ List the items in an archive.
■ Store, retrieve, copy, move and delete archived items.
■ Get item properties.
■ Add custom index metadata to an item as it is stored.
■ Place holds on a group of items to prevent items from
being deleted manually or by Enterprise Vault storage
expiry. (Legal Hold)
■ Remove any holds placed on items. (Legal Hold)
Archives and vault stores cannot be deleted using the Content
Management API.
NSF Manager API Enables interaction between Enterprise Vault and Notes
databases:
■ Extract notes from an archive using the Enterprise Vault
Content Management API, and import them into a
database
■ Extract notes from a database and place them in an
Enterprise Vault archive
■ Create and delete databases
Search API ■ Search Enterprise Vault indexes.
Retention API ■ Create new retention categories.

■ Enumerate retention categories.
■ Set locks on a retention category.
■ Update an existing retention category.
■ Look up an existing retention category.
Enterprise Vault API overview 39
Prerequisite software and settings
Table 3-1 Enterprise Vault APIs
Exchange Filtering API External filters enable preprocessing of items in order to

Domino Filtering API decide on the actions to take; for example, whether to archive
the item and which archive settings to apply.
The Filtering APIs provide the ability to:
■ Select certain items for processing (and possibly
archiving), based on attributes (for example, subject text,
sender).
■ Store selected items in specific archives.
■ Set a particular retention category on selected items.
■ Delete selected items without archiving them.
■ Add custom index metadata to selected items before they
are archived.
Note: The Simple API was available in previous releases. This has been replaced
by the Content Management API. For details of the Simple API, refer to the
Enterprise Vault Application Programmer’s Guide included with Enterprise
Vault 6.0.
Prerequisite software and settings

Details of prerequisites for Enterprise Vault are described in the Installing and
Configuring manual.
If you are using the Content Management API, then MSXML 6.0 or later is
required on the computer where you install the Enterprise Vault API runtime.
Permissions
In general, the caller has to have sufficient permissions to access the target
archive.
If the calling application is acting on behalf of clients, and has assumed the
responsibility of checking client permissions prior to proxying calls to the API,
then the caller must have adequate administration permissions. This can be
either Vault Service account permissions, or a suitable Enterprise Vault
administration role, which is assigned using the Enterprise Vault
Administration Console.
Similarly, to create archives, the caller must have either Vault Service account
permissions, or a suitable Enterprise Vault administration role.
Vault Service account permissions are described in the Installing and
Configuring manual.
Licensing
Enterprise Vault administration roles are described in the Enterprise Vault

Administration guide.
Licensing
No additional Enterprise Vault license is required in order to develop
applications against the Enterprise Vault APIs. However, customer deployments
of third-party applications which make use of the Enterprise Vault APIs will
require the following license, in addition to any third party licensing
requirements:
■ Symantec Enterprise Vault Custom Archiving Agent license (Enterprise
Vault 8.0)
■ Symantec Generic Ingest Agent license (Enterprise Vault 2007)
This section describes the licensing requirements for the Enterprise Vault APIs.
Development licensing
The Enterprise Vault APIs described in this guide are for developers who wish to
add and/or manage content in Enterprise Vault archives. In most circumstances,
these developers would be granted a Not for Resale (NFR) license to develop to
these APIs by membership of Symantec Technology Enabled Program (STEP).
Customers who wish to develop applications that integrate to these APIs would
need to purchase one of the following licenses and request access to the
Enterprise Vault SDK:
Vault 8.0 or later) for ingesting content into Enterprise Vault. This license
also covers management of content archived by Enterprise Vault.
■ Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault
8.0 or later) for management of content archived by Enterprise Vault.
■ Symantec Generic Ingest Agent license (Enterprise Vault 7.0 and Enterprise
Vault 2007) for ingesting content into Enterprise Vault. This license also
covers management of content archived by Enterprise Vault.
■ Symantec Generic Content Management Connector license (Enterprise
Vault 7.0 and Enterprise Vault 2007) for management of content archived
by Enterprise Vault.
Production licensing
The STEP licensing contract does not grant production use of the Enterprise
Vault APIs. Customer deployments of third-party applications and
Deploying an application that uses the API
customer-developed applications that make use of the Enterprise Vault APIs will
require one of the following licenses, in addition to any third-party licensing
requirements:
Vault 8.0 or later) for ingesting content into Enterprise Vault. This license
also covers management of content archived by Enterprise Vault.
■ Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault
8.0 or later) for management of content archived by Enterprise Vault.
■ Symantec Generic Ingest Agent license (EEnterprise Vault 7.0 and
Enterprise Vault 2007) for ingesting content into Enterprise Vault. This
license also covers management of content archived by Enterprise Vault.
■ Symantec Generic Content Management Connector license (Enterprise
Vault 7.0 and Enterprise Vault 2007) for management of content archived
by Enterprise Vault.

This section describes API runtime and .NET considerations when deploying
applications that use the Enterprise Vault API runtime.
Enterprise Vault API runtime MSI

The Enterprise Vault API runtime libraries are provided in the Windows
installer kit,
Symantec Enterprise Vault API Runtime.msi
on the Symantec Enterprise Vault release media.
Note: The Enterprise Vault API runtime kit is not redistributable.
The runtime should be obtained from the customer’s Enterprise Vault release
media and installed on the server that will host the application.
The Enterprise Vault API runtime libraries are automatically installed with the
Enterprise Vault server, but it is not recommended that the application runs on
the Enterprise Vault server.
The runtime installer registers the COM objects for Content Management,
Search and Retention APIs, and provides interoperability libraries for .NET
language bindings for .NET managed code.
Checking the API runtime version and the installation path

The application should verify that version of the runtime installed on the local
computer is compatible with the application. For example, if the application
uses Enterprise Vault 8.0 features, then the API runtime must be Enterprise
Vault 8.0 or later.
If you are using Enterprise Vault 8.0 or later, the application can query registry
settings directly to find out the the version of the Enterprise Vault API runtime
installed locally and the installation path. The registry settings to query are
InstallPath and Version in the following location:
HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\API Runtime
\Install
On 64-bit versions of Windows Server, the Enterprise Vault registry settings are
under the following location:
HKEY_LOCAL_MACHINE
\Software
\WOW6432node
\KVS
If you are using a version of Enterprise Vault prior to Enterprise Vault 8.0,
follow the instructions given in “Checking version and installation path details
prior to Enterprise Vault 8.0”.
Checking version and installation path details prior to

To detect if Enterprise Vault API runtime libraries, or the Enterprise Vault SDK,
are installed locally, and find out the installation location, you can use the
Windows Installer API:
■ Use the FindRelatedProducts action and the Upgrade Table to locate
products with the following UpgradeCodes:
{2FEB3523-3A2C-4518-A0D4-BD38E66A5E8C} – Enterprise Vault runtime
{C8486BDD-85C4-48CC-97BA-82F1079DA61E} – Enterprise Vault SDK
■ When you have ascertained that either of these is installed, you can use the
MsiGetProductInfo method and the relevant product code to find out
the installation location (INSTALLPROPERTY_INSTALLLOCATION) of the
runtime or SDK.
To detect if Enterprise Vault server is installed, and find out the installation
location, you can query the following registry settings directly:
■ HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\Install
\VaultServices
If the value of this setting is “Installed”, then Enterprise Vault server is
installed.
■ HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\Install
\InstallPath
Deploying .NET applications

When deploying a .NET application, the application must ensure that suitable
versions of the Interop assemblies for Enterprise Vault API components have
been installed. This is best done in one of the following ways:
■ The application can be built against the set of Primary Interop Assemblies
(PIAs) in the Enterprise Vault SDK. When the application is deployed, it
must be configured to use the PIAs provided by the Enterprise Vault API
runtime.
This requires an application configuration file with <dependentAssembly>
entries for each of the Enterprise Vault API components used by the
application.
The assembly redirections must include a <codebase> element that defines
the location of the PIA and, optionally, a <bindingRedirect> element if the
application is built against a different PIA version to the one deployed by
the Enterprise Vault runtime.
See “Updating binding redirections in configuration files”.
■ Alternatively, the application generates, builds against, and deploys a set of
Interop assemblies for those Enterprise Vault API components that are used
by the application. The Interop assemblies can be generated indirectly
using Visual Studio as part of the application build, or directly using the
Microsoft .NET Framework Type Library Importer tool (tlbimp.exe). For
example:
tlbimp /nologo EVContentManagementAPI.dll
Installing the Enterprise Vault SDK
Using Visual Studio the required API COM libraries, for example
EVContentManagementAPI.dll, should be added to the application’s
References.
Updating binding redirections in configuration files

This section provides instructions on how to update the .NET application
configuration files to use a newer version of the Enterprise Vault API runtime.
To update the application configuration file:
1 Open the client application’s configuration file, locate the Enterprise Vault
<assemblyIdentity> nodes, and update any <bindingRedirect> and
<codebase> nodes as illustrated in the following example to redirect any
requests for an older version of an Enterprise Vault API Runtime file to the
new version. For example:
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity
name="KVS.EnterpriseVault.Interop.IndexClient"
culture="neutral" publicKeyToken="26c5e2ccf2b9267c"/>
<bindingRedirect oldVersion="7.5.4.2534"
newVersion="8.0.0.0"/>
<codeBase version="8.0.0.0" href=
"FILE:///C:\Program Files\Enterprise Vault\
KVS.EnterpriseVault.Interop.IndexClient.dll"/>
</dependentAssembly>
</assemblyBinding>
</runtime>
2 Apply the updates to the configuration file for each .NET application that
uses the Enterprise Vault API Runtime files.

The Enterprise Vault SDK is distributed as a Windows installer kit,
Symantec Enterprise Vault Software Development Kit.msi,
which installs the following:
■ Enterprise Vault API runtime libraries
■ API samples
■ This manual in PDF and CHM format
Checking the SDK version and installation path

If you are using Enterprise Vault 8.0 or later, you can query the registry settings
InstallPath and Version in the following location to find out the the version of
the Enterprise Vault API SDK installed and the installation path:
HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\Software Development Kit
\Install
On 64-bit versions of Windows Server, the Enterprise Vault registry settings are
under the following location:
HKEY_LOCAL_MACHINE
\Software
\WOW6432node
\KVS
If you are using a version of Enterprise Vault prior to Enterprise Vault 8.0,
follow the instructions given in “Checking version and installation path details
prior to Enterprise Vault 8.0” on page 42.
SDK examples
An example application for the Content Management API is included in the
Enterprise Vault SDK, in samples\ECM API Sample.
This example application has been built using Visual Studio 2005.
The application does not have a manifest configured. If the target Enterprise
Vault server is running on Windows Server 2008, you may want to add an
application manifest, as described in the MSDN article:
http://msdn2.microsoft.com/En-US/library/bb756929.aspx
To build the test application

1 Install the SDK on your development server.
2 Open the project file TestECMClient.vcproj.
3 You need to tell the compiler where the Enterprise Vault binaries are
located in your environment.
In Visual Studio select
Tools > Options > Projects and Solutions > VC++ directories.
From the Show Directories for drop down list select Executable Files.
Add the folder containing the Enterprise Vault binaries to the list of folders.
Programming notes
4 Now build the test application. The application compiles with warnings,
which can be ignored.
Programming notes
■ As the API interfaces are derived from IDispatch, they can be used by
scripting languages.
■ The APIs can be used from C++, .NET languages (such as Visual Basic .NET
and C#), ASP web pages (using Visual Basic Script), and other languages that
support COM.
■ For best performance in a multi-threaded application, use a separate
instance of an API object, such as a Content Management API object, per
thread.
Using the Enterprise Vault APIs in C++

For each API, the associated DLL includes the type library for all of the classes,
enumerations and interfaces of the API. When using Microsoft Visual Studio
C++ to build an application using the API, the #import directive should be used
to provide C++ definitions of the COM classes, interfaces and types.
For example, to use smart pointers, error wrapper functions and the
EVContentManagementAPILib namespace:
#import “EVContentManagementAPI.dll”
using namespace EVContentManagementAPILib;
To exclude use of smart pointers, error wrapper functions and the
EVContentManagementAPILib namespace:
#import “EVContentManagementAPI.dll” no_namespace, raw_interfaces_only
Using Enterprise Vault APIs .NET managed languages

When using .NET managed languages to build an application using an API,
Interop assemblies provide the .NET definitions for the API COM type library.
You can reference the SDK Primary Interop Assemblies (PIAs), the COM API
library or Interop assemblies generated via tlbimp, depending upon the
deployment model selected.
See “Deploying .NET applications” on page 43.
The Primary Interop Assemblies (PIAs), COM API libraries or Interop assemblies
should be added to the project’s references to provide definitions of the COM
classes, interfaces and types. For example, to reference the Content
Management API via its PIA, add :
KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll
Programming notes
When referencing a PIA the API types are defined in the namespace
KVS.EnterpriseVault.Interop.
When referencing an Interop assembly the API types are defined in the
namespace of the COM type library name. For example the namespace for the
Content Management API is EVContentManagementAPILib.
Using Enterprise Vault APIs in Visual Basic Script

The Content Management API interfaces, IArchive3 and IArchiveMetaData2,
which were introduced at Enterprise Vault 8.0, are not directly accessible by
Visual Basic Script applications. The Content Management API
IDispatchQueryInterface method enables Visual Basic Script applications to
perform a QueryInterface, specifying the required interface's Interface
Identifier (IID) string.
Code samples
In the code samples given in this manual, attention has been paid to the API
specifics only. Other programming aspects, such as error handling, have been
omitted for clarity.
In general, code samples are included for C++ and C#. As Visual Basic .NET is
very similar to C#, separate examples are not included in most cases.
Programming notes
Chapter 4
This chapter provides the following information:
■ An overview of the Content Management API.
■ General guidelines for using the API.
■ Enumerations
■ Detailed reference information on each interface, method and property.
About the Content Management API

The Content Management API comprises the following interfaces:
■ IContentManagementAPI
■ IContentManagementAPI2
■ IVaultStores
■ IVaultStore
■ IArchives
■ IArchive
■ IArchive2
■ IArchive3
■ IItems
■ IItem
■ IItem2
■ IItem3
50 Content Management API
■ IContent
■ IArchiveMetaData
■ IArchiveMetaData2
■ ISimpleIndexMetadata
■ IComplianceData
■ IHolds
■ IHold
■ IExtendedErrorInfo
■ IDiagnosticsAPI
Table 3-1 on page 38 gives a brief summary of the operations that can be
performed using the Content Management API.
The methods and properties exposed by all these interfaces are described in
detail in this chapter.
When working with Lotus Notes databases, you can use the NSF Manager API to
manage NSF databases, and import archived notes into a database or extract
notes to be archived from a database. You can use the Content Management API
to store notes in the archive or retrieve notes from the archive.
Architecture of Content Management API

Figure 4-1 illustrates the organization of the Content Management API objects.
Content Management API 51
Figure 4-1 Hierarchy of Content Management API objects
All the objects shown are exposed by the Content Management API:
■ The ContentManagementAPI object provides a means of accessing the other
objects, such as VaultStores, VaultStore, Archives and Item. These objects
enable the examination of vault stores and archives in Enterprise Vault.
■ The VaultStores object enables applications to enumerate the vault stores
configured in an Enterprise Vault site.The VaultStores object exposes a
standard COM collection interface that manages a collection of VaultStore
objects.
■ The Archives object enables applications to enumerate archives in a vault
store. The properties enable the selection of archives using a combination
of archive name, type and permissions. The Archives object exposes a
standard COM collection interface that manages a collection of Archive
objects.
■ The Items object enables applications to enumerate the items in an archive
in batches. The Enterprise Vault index sequence number of an archived
item is used to determine the first item in a batch. An Items collection can
be enumerated by increasing the index sequence number (oldest archived
item first), or by decreasing the index sequence number (most recently
General guidelines for using the API
archived item first). The Items object exposes a standard COM collection
interface that manages a collection of Item objects.
■ The Archive object enables the creation of archives in an Enterprise Vault
vault store.
■ The Item object provides applications with a way to store and manage items
in Enterprise Vault archives.
The following interfaces are implemented by the Item object:
■ IContent interface provides calling applications with a set of properties
that describe the data being archived or retrieved.
■ IArchiveMetaData interface provides calling applications with a set of
properties that describe how the item is archived. The following
interfaces are exposed by IArchiveMetaData:
IComplianceData interface describes the compliance metadata set on
an item in an archive.
ISimpleIndexMetaData interface enables the calling application to add
custom index metadata to an object as it is archived. This can then be
searched for using the Search API.
■ The Holds object provides calling applications with the ability to place or
release legal holds on multiple items at a time with a single call to the
Enterprise Vault server. It exposes a standard COM collection interface that
manages a collection of IHold objects.
■ The Hold object describes a hold that is placed on an item.
■ The ExtendedErrorInfo object provides calling applications with additional
information on internal errors encountered when using Content
Management API interfaces.
■ The DiagnosticsAPI object enables calling applications to use the Enterprise
Vault tracing utility, Dtrace, and write to the Enterprise Vault event log.

To use the Content Management API you need to obtain an instance of the
ContentManagmentAPI object in the usual manner; by calling CoCreateInstance
(C++), or by using the new operator (.NET managed code), for example.
See “Examples” on page 72.
You can then use the properties and methods on the interface to obtain
instances of other objects.
Consider thread priority if normal Enterprise Vault Exchange Server journal or
mailbox archiving is running in your environment in addition to a Content
Management API application. If the API application archives large numbers of
items, and is considered less important than normal Enterprise Vault Exchange
Server archiving, then the API application should run with a lower thread
priority than THREAD_PRIORITY_NORMAL.
Use of objects
It is best practice for the calling application to keep the ContentManagementAPI
object alive as long as possible, as the ContentManagementAPI object caches
information from Enterprise Vault, and frequent creation and release would
result in poor performance of the client.
Most of the object instances obtained from the ContentManagementAPI object
are designed to be used only once. This prevents reuse of stale data.
Once an object instance has been used (that is, Get, Insert or Create have been
called), it can only be used for querying properties, not for setting them. Before
any of these methods (Get, Insert or Create) can be called again, the existing
object instance should be released and a new one obtained.
For example, the following steps are required when storing an item in an
archive:
■ Obtain an instance of an empty Item object by calling
IContentManagementAPI::Item.
■ Populate its properties (ArchiveId, ArchiveMetaData, Content etc.).
■ Call the Insert method.
■ Retrieve the item’s Id from the object property.
■ Release the Item object instance.
You cannot just repopulate the properties and call Insert again. If you
attempt to do so an error will be reported.
A number of object properties, for example Item.Id, return the default property
value and an S_FALSE return value when reading the property before it has been
written. This is a success return value. When coding in C++ the S_FALSE return
value should be handled using the Windows SUCCEEDED or FAILED macros.
When coding in C# it is not possible to differentiate between the S_OK and
S_FALSE return values.
Enumerating vault stores, archives and items

Archives are held in vault stores, and items are held in archives. When storing
or retrieving items using the Content Management API, or searching for
archived items using the Search API, calling applications need to be able to find
target vault stores and archives. This functionality is provided by the
IVaultStores and the IArchives interfaces. These interfaces enable calling
applications to enumerate and select vault stores and archives, and retrieve
information about these from the Enterprise Vault Directory.
The IItems interface enables the application to enumerate the items in an
archive, and retrieve information about these items from the Enterprise Vault
Storage Service.
The IVaultStores, IArchives and IItems interfaces inherit the properties and
methods of a generic collection enumeration interface, ICollectionBase. How to
use this interface follows the general model for enumerating objects:
■ Obtain an empty collection instance from the ContentManagementAPI.
■ Populate the selection criteria properties.
■ Invoke the Get method to populate the collection.
■ Enumerate through the collection.
You can select archives using the following criteria:
■ By vault store; optionally filtered by archive type.
■ By name or partial name; optionally filtered by archive type.
■ By caller’s access permissions; optionally filtered by archive type. For
example, all FSA archives that the caller has permission to search.
■ By archive type.
With vault stores, you can only select all vault stores in an Enterprise Vault Site.
You select items using the following criteria:
■ By archive.
By start item Index Sequence Number (ISN); optionally in ascending or
descending order.
Saveset IDs and Transaction IDs

An archived item can be identified by either a Saveset ID or a Transaction ID.
The Saveset ID is the long form identifier and fully identifies the archived item.
This form of identifier should be used for long term storage of the archived item
ID.
If an item’s Transaction ID is specified as the IItem::Id property value and then
the Get method is called to retrieve the item, the Id property will then hold the
Saveset ID of the item.
The Id property of an Item in an Items collection will be populated with the
Item's Transaction ID until the Get method is invoked to retrieve the item.
The Transaction ID is a short form identifier, and is an element within the
Saveset ID. It is a GUID, a 128 bit number, that uniquely identifies the archived
item within a vault store. The Transaction ID would typically only be used to
identify an item processed during filtering.
Format of a Transaction ID value

A Transaction ID can be specified as a 32 hexadecimal character string; for
example, “FC0A3C5E5A7D45E6AB3BC5382EB640D”, or in GUID Registry
format (that is, {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx}).
For performance reasons, the latter format is used when the IItem::Id property
is populated by the Items collection object.
Items stored using a version of Enterprise Vault prior to Enterprise Vault 8.0
have a 31 hexadecimal character Transaction ID value.
When such items are copied or moved, the Transaction ID value is extended to
32 hexadecimal characters by appending a zero (‘0’) hexadecimal character.
Property validation
The syntax of a property is validated when the property is set, but validation of
the value is typically delayed until the property is used, for example when
invoking the Get method.
Adding custom index metadata

Applications can add custom index metadata to an item as it is archived using
the ISimpleIndexMetadata interface.
See “IArchiveMetaData :: IndexData” on page 253.
When the item is indexed, this custom metadata will be included in the index for
the item. The Search API can then be used to search archives for items with the
custom information.
See Figure 4-2 on page 56.
Custom filtering is available for both Exchange Server Archiving (for the
Exchange Mailbox Archiving Task, Exchange Public Folder Task and Exchange
Journaling Task) and Domino Server Archiving, and the following methods can
be used to add custom index properties:
■ For Exchange Server filtering, the AddIndexedProperty and
AddIndexedPropertyToSet methods of the IArchivingControl interface can
be used.
See “IArchivingControl interface for Exchange filtering” on page 439.
■ For Domino Server filtering, the Add method in the IndexMetadata class
can be used.
See “IArchivingControl interface” on page 483.
Figure 4-2 Adding metadata to the index of an item
You can check that the metadata has been indexed by performing an archive
search for the custom information.
Audit logging
From Enterprise Vault 8.0, audit logging includes Content Management API
item operations. Auditing for various categories of item operations from all
Enterprise Vault agents can be enabled or disabled.
Table 4-1 lists the operations that can be logged and the associated Enterprise
Vault audit category. Audit logging can be enabled for specific audit categories
using the Enterprise Vault Administration Console.
Table 4-1 Operations logged and the associated audit category
API operation Enterprise Vault Audit Category
Insert Archive
CopyTo
MoveTo Archive
Delete 1
Delete Delete
Table 4-1 Operations logged and the associated audit category
API operation Enterprise Vault Audit Category
Get View
1.MoveTo will support two audit entries; one for the item insertion and another for the item deletion from
the original location.
Diagnostic logging and tracing

The DiagnosticsAPI object enables calling API applications to write to the
Enterprise Vault event log and use the Enterprise Vault tracing utility (Dtrace).
DiagnosticsAPI can be used from any external application, including external
filters.
Enumerations
Enumerations
This section describes the enumerations used by the Content Management API.
EV_API_DELETION_LEVEL enumeration
Deletion level enumeration defines the type of delete permitted for archived
items:
enum EV_API_DELETION_LEVEL
{
DELETION_LEVEL_SOFT_DELETE = 0,
DELETION_LEVEL_HARD_DELETE = 1
};
Items can be deleted completely (hard delete), or moved to the Enterprise Vault
"dumpster" area (soft delete). The default value is
DELETION_LEVEL_SOFT_DELETE.
In the Enterprise Vault Administration Console, in the Site Properties pages, the
administrator can enable the recovery of deleted items and specify how long
soft-deleted items are to be kept.
This enumeration value is set using the Item DeletionLevel property.
See “IItem :: DeletionLevel” on page 190
EV_API_EVENT_TYPE enumeration
Event type enumeration indicates the type of event:
enum EV_API_EVENT_TYPE
{
EVENT_TYPE_ERROR = 1,
EVENT_TYPE_WARNING = 2,
EVENT_TYPE_INFORMATION = 3,
EVENT_TYPE_SUCCESS_AUDIT = 4,
EVENT_TYPE_FAILURE_AUDIT = 5
};
When an application creates a diagnostic message in the Enterprise Vault event
log using the DiagnosticsAPI LogEvent method, this value indicates the type of
message to create.
See “IDiagnosticsAPI : LogEvent” on page 367
EV_API_ITEMS_ORDERBY enumeration
Items collection order defines whether to increase or decrease the index
sequence number when enumerating a collection of items.
Enumerations
enum EV_API_ITEMS_ORDERBY
{
ITEMS_ORDERBY_ASC = 0,
ITEMS_ORDERBY_DESC = 1
};
The default value is ITEMS_ORDERBY_ASC; items are enumerated using
ascending index sequence number order.
See “IItems :: OrderBy” on page 170
EV_API_TRACE_LEVEL enumeration
Trace level enumeration indicates the trace level:
enum EV_API_TRACE_LEVEL
{
TRACE_LEVEL_HIGH = 1,
TRACE_LEVEL_MEDIUM = 2,
TRACE_LEVEL_LOW = 3
};
The method DiagnosticsAPI IsTraceEnabled tests if the specified level of tracing
is enabled in the application for the Enterprise Vault tracing utility (Dtrace).
When sending a trace message to Dtace, the DiagnosticsAPI Trace method uses
this enumeration to set the trace level to be associated with the message.
See “IDiagnosticsAPI : IsTraceEnabled” on page 366 and
“IDiagnosticsAPI : Trace” on page 368
EV_STG_API_ARCHIVE_TYPE enumeration
Archive type enumeration indicates the type of archive:
enum EV_STG_API_ARCHIVE_TYPE
{
ARCHIVE_TYPE_NOT_SET = 0x00000000,
ARCHIVE_TYPE_SHARED = 0x00000001,
ARCHIVE_TYPE_EXCHANGE_MAILBOX = 0x00000002,
ARCHIVE_TYPE_EXCHANGE_JOURNAL = 0x00000004,
ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER = 0x00000008,
ARCHIVE_TYPE_FILE_SYSTEM = 0x00000010,
ARCHIVE_TYPE_SHAREPOINT = 0x00000020,
ARCHIVE_TYPE_DOMINO_JOURNAL = 0x00000040,
ARCHIVE_TYPE_DOMINO_MAILBOX = 0x00000080
};
The properties, Archives ArchiveTypes and Archive Type, select archives based
on the type of archive specified by this enumeration.
See “IArchives :: ArchiveTypes” on page 119
and “IArchive3 :: Type” on page 160
Enumerations
EV_STG_API_AUTHENTICATE_USING enumeration
Storage authentication enumeration indicates the authentication mode to use
when authenticating to Enterprise Vault.
enum EV_STG_API_AUTHENTICATE_USING
{
AUTHENTICATE_USING_DCOM_SECURITY = 0,
AUTHENTICATE_USING_AUTHSERVER = 1
AUTHENTICATE_USING_MOST_APPROPRIATE_MODE = 2
};
AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default value.
This value means that DCOM will be used.
Authentication using the Enterprise Vault authentication server can only be
used by applications installed on a configured Enterprise Vault server, and
should only be used on advice from Symantec Support.
See “IContentManagementAPI :: AuthenticationMode” on page 83
EV_STG_API_CAN_DELETE enumeration
Can delete enumeration indicates whether or not the item can be deleted.
enum EV_STG_API_CAN_DELETE
{
DELETE_ALLOWED = 0,
DELETE_ACCESS_DENIED = 1,
DELETE_RETCAT_ONHOLD = 2,
DELETE_ITEM_ONHOLD = 4,
DELETE_ITEM_COMPLIANCE = 8
};
The Item CanBeDeleted method returns the current value for an item.
Values that indicate that the item cannot be deleted have the following
meanings:
DELETE_ACCESS_DENIED The caller may not have sufficient access to the target
archive to delete the item, or the archive may be in a
read-only state.
DELETE_RETCAT_ONHOLD The item's retention category prevents deletion of the item.
DELETE_ITEM_ONHOLD The item cannot be deleted because a legal hold has been
placed on it.
DELETE_ITEM_COMPLIANCE The compliance device on which the item is stored does not
permit deletion
See “IItem :: CanBeDeleted” on page 206

Enumerations
EV_STG_API_CONVERTED_CONTENT enumeration
When a file is archived, the Enterprise Vault Storage Service converts the file to
HTML, if possible. The HTML version is used by the Indexing Service to index
the item. The HTML version is also presented to users when the item is
previewed or viewed using the Enterprise Vault Web Access application.
Store converted content enumeration indicates whether converted content is
stored with the item, or generated on demand:
enum EV_STG_API_CONVERTED_CONTENT
{
CONVERTED_CONTENT_STORED = 0,
CONVERTED_CONTENT_ON_DEMAND = 1
};
The property, Archive ConvertedContent, is used to set or retrieve the
enumeration value.
See “IArchive :: ConvertedContent” on page 132
EV_STG_API_CP_SETBY enumeration
Compliance set by enumeration is for use with compliance devices only. It
indicates where the compliance retention period is set:
enum EV_STG_API_CP_SETBY
{
SETBY_NOTSET = 0,
SETBY_SELF = 1,
SETBY_RETCAT = 2
};
The property, ComplianceData SetBy, uses this enumeration value to define
where the compliance retention period is set:
SETBY_NOTSET A compliance retention period is

not set.
SETBY_SELF The compliance retention period

is set by the caller using the
ComplianceData object.
SETBY_RETCAT The compliance retention period

is set by the associated Enterprise
Vault retention category.
“IArchiveMetaData :: ComplianceData” on page 247

“IComplianceData :: SetBy” on page 312
Enumerations
EV_STG_API_CP_UNITS enumeration
Compliance units enumeration indicates the units used in specifying the
compliance period:
enum EV_STG_API_CP_UNITS
{
CP_UNITS_DAYS =0,
CP_UNITS_WEEKS = 1,
CP_UNITS_MONTHS = 2,
CP_UNITS_YEARS = 3,
CP_UNITS_DEFAULT = 4,
CP_UNITS_NONE = 5
};
CP_UNITS_NONE is actually the default value, not CP_UNITS_DEFAULT.
See “IComplianceData :: Units” on page 308
EV_STG_API_DELETION_REASON enumeration
Deletion reason enumeration indicates why an item has been deleted from the
archive.
enum EV_STG_API_DELETION_REASON
{
DELETION_REASON_NONE = 0,
DELETION_REASON_USER = 1,
DELETION_REASON_EXPIRY = 2,
DELETION_REASON_SYSTEM = 3
DELETION_REASON_UNKNOWN = 2147483647
}
If an item no longer exists in the archive, the Item DeletionReason property can
be used to find out why the item was deleted. the Item DeletionReason property
uses the EV_STG_API_DELETION_REASON enumeration.
The enumeration values have the following meanings:
DELETION_REASON_NONE (Default) Indicates that the item has not yet been
deleted.
DELETION_REASON_USER Indicates that the item was deleted by a user.
DELETION_REASON_EXPIRY Indicates that the item was deleted by Enterprise Vault

expiry deletion.
DELETION_REASON_SYSTEM Indicates that the item was deleted by the Enterprise

Vault system. This value may be returned, for example,
when the archive has been deleted, or if Enterprise Vault
could not complete the archiving process because the
vault store could not be backed up.
Enumerations
DELETION_REASON_UNKNOWN Indicates that the reason why the item was deleted
cannot be identified.
See “IItem2 :: DeletionReason” on page 215
EV_STG_API_EXPIRE_ITEMS enumeration
Expire items enumeration indicates whether expired items should be deleted
automatically from the archive:
enum EV_STG_API_EXPIRE_ITEMS
{
DONT_EXPIRE_ITEMS = 0,
EXPIRE_ITEMS = 1
};
The property Archive ExpireItems can be used to return the enumeration value
for an existing archive, or set the required value for a new archive before
Archive Create is called.
See “IArchive :: ExpireItems” on page 130
EV_STG_API_INDEX_LEVEL enumeration
Index level enumeration indicates how much of an item is indexed:
enum EV_STG_API_INDEX_LEVEL
{
INDEX_LEVEL_BRIEF = 0,
INDEX_LEVEL_MEDIUM = 1,
INDEX_LEVEL_FULL = 2,
INDEX_LEVEL_DEFAULT = 3
};
The Enterprise Vault Indexing service manages the indexes of archived data to
enable users to search for archived items. When users search the archives to
which they have access, the index volume files are searched. The more
information that is indexed about an item, the quicker it is to find the item.
However, the more information that is indexed about an item, the more disk
space is required for the index.
For more information on indexing levels, see “Introduction to storing and
indexing” on page 517.
FULL indexing is required for phrase searches of the content property
(IndexPropCONT).
The property, Archive IndexLevel, is used to determine the level of detail stored
in the archive’s index.
See “IArchive :: IndexLevel” on page 136
Enumerations
EV_STG_API_INDEX_URGENCY enumeration
Index urgency enumeration indicates whether to index items as they are stored:
enum EV_STG_API_INDEX_URGENCY
{
INDEX_ITEMS_IMMEDIATELY = 0,
INDEX_ITEMS_DEFER_INDEFINITELY = 1
};
Deferring indexing may be useful if you want to store a very large number of
items quickly.
If INDEX_ITEMS_DEFER_INDEFINITELY is set, the items will not be indexed
until the value has been reset to IMMEDIATELY. Thereafter, the next time the
Indexing Service runs, it will process the indexing backlog.
The Archive IndexUrgency property is used to access index urgency
information.
“IArchive :: IndexUrgency” on page 134
EV_STG_API_ITEM_COPYOPTIONS enumeration
The Item CopyOptions property uses this enumeration to identify the source
item property values that are to be copied to the destination item when an
archived item is moved or copied to a different location.
enum EV_STG_API_ITEM_COPYOPTIONS
{
ITEM_COPYOPTIONS_UNSPECIFIED = 0x00000000,
ITEM_COPYOPTIONS_ARCHIVEMETADATA = 0x00000002,
ITEM_COPYOPTIONS_MERGE_INDEXMETADATA = 0x00000004
} ;
The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA.
■ ITEM_COPYOPTIONS_ARCHIVEMETADATA (Default value)
If this is set, then the values of the the following ArchiveMetaData
properties on the source item will be copied to the equivalent properties on
the destination item, unless explicitly provided as part of the CopyTo or
MoveTo method call:
SimpleIndexMetaData
ArchivedDate
RetentionCategory
CurrentLocation
CurrentFolder
CustomIdentifier
CustomQualifier
CustomProperties
Enumerations
■ ITEM_COPYOPTIONS_MERGE_INDEXMETADATA
If this is set, then the resulting destination item will include the custom
index metadata properties on the source item and also any additional
custom index metadata properties that were added to the destination item
before the copy or move operation was performed.
See “IItem :: CopyOptions” on page 192
EV_STG_API_ITEM_DETAIL enumeration
Item detail enumeration indicates the data to populate for an Item.Get request:
enum EV_STG_API_ITEM_DETAIL
{
DETAIL_LEVEL_ITEM_PROPERTIES = 1,
DETAIL_LEVEL_ITEM_CONTENT = 2,
DETAIL_LEVEL_ARCHIVE_METADATA = 4,
DETAIL_LEVEL_COMPLIANCE_DATA = 8,
DETAIL_LEVEL_HOLD_DATA = 16,
DETAIL_LEVEL_CUSTOM_INDEX_METADATA = 32,
DETAIL_LEVEL_SYSTEM_INDEXDATA = 64,
DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA = 128
DETAIL_LEVEL_SENDER_RECIPIENT_INDEXDATA = 256
};
The following table lists the properties that are populated for the different item
detail levels.
Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration

values
Enumeration value Properties populated
DETAIL_LEVEL_ITEM_PROPERTIES IContent.Title
IContent.Author
IContent.FileExtension
IContent.MIMEFormat
IContent.OriginalLocation
IContent.CreatedDate
IContent.ModifiedDate
IContent.OriginalSize
IItem.CanBeDeleted
IArchiveMetadata.IsItemSecured
See “Content object” on page 220
See “Item object” on page 172
See “ArchiveMetaData object” on
page 237
DETAIL_LEVEL_ITEM_CONTENT IContent.Data
Enumerations
Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration

values
Enumeration value Properties populated
DETAIL_LEVEL__ARCHIVE_METADATA IArchiveMetadata.ArchivedDate
IArchiveMetadata.SavesetSize
IArchiveMetadata.RetentionCategory
IArchiveMetadata.CustomIdentifier
IArchiveMetadata.CustomQualifier
IArchiveMetadata.CustomProperties
IArchiveMetadata.CurrentFolderId
IArchiveMetadata.SequenceNum
DETAIL_LEVEL__COMPLIANCE_DATA IArchiveMetadata.ComplianceDevice
IArchiveMetadata.RetentionExpires
DETAIL_LEVEL__HOLD_DATA IItem.Holds
See “Holds object” on page 313
DETAIL_LEVEL__CUSTOM_INDEX_METADATA IArchiveMetadata.IndexData — custom

index properties only. (System
properties are not included).
DETAIL_LEVEL__SYSTEM_INDEXDATA IArchiveMetadata.IndexData — system

properties only, excluding the “menv”
and “sere” properties.
DETAIL_LEVEL__MESSAGE_ENVELOPE_INDEX IArchiveMetadata.IndexData — “menv”

DATA system property only.
DETAIL_LEVEL__SENDER_RECIPIENT_INDEXD IArchiveMetadata.IndexData — “sere”

ATA system property only.
For details of the Get method, see “IItem :: Get” on page 200.
For details of Enterprise Vault properties, see “System properties” on page 664.
EV_STG_API_PERMISSIONS_TYPE enumeration
Archive permissions enumeration indicates archive permissions:
enum EV_STG_API_PERMISSIONS_TYPE
{
PERMISSIONS_UNSPECIFIED = 0x00000000,
Enumerations
PERMISSIONS_SEARCH = 0x00000080,
PERMISSIONS_READ = 0x00000001,
PERMISSIONS_WRITE = 0x00000002,
PERMISSIONS_DELETE = 0x00000004,
PERMISSIONS_FOLDER_READ = 0x00000008,
PERMISSIONS_FOLDER_WRITE = 0x00000010,
PERMISSIONS_FOLDER_DELETE = 0x00000020,
PERMISSIONS_READ_WRITE = PERMISSIONS_READ|PERMISSIONS_WRITE,
PERMISSIONS_READ_WRITE_DELETE= PERMISSIONS_READ
|PERMISSIONS_WRITE
|PERMISSIONS_DELETE,
PERMISSIONS_WRITE_DELETE = PERMISSIONS_WRITE
PERMISSIONS_READ_DELETE = PERMISSIONS_READ
PERMISSIONS_FOLDER_READ_WRITE= PERMISSIONS_FOLDER_READ
|PERMISSIONS_FOLDER_WRITE,
PERMISSIONS_FOLDER_READ_WRITE_DELETE = PERMISSIONSFOLDER__READ
|PERMISSIONS_FOLDER_WRITE
|PERMISSIONS_FOLDER_DELETE,
PERMISSIONS_FOLDER_WRITE_DELETE = PERMISSIONS_FOLDER__WRITE
PERMISSIONS_FOLDER_READ_DELETE = PERMISSIONS_FOLDER_READ
};
The Archives Permissions property uses this enumeration to select archives
based on the archive access permissions of the caller.
The Archive SecurityDescriptor property represents the manually set
permissions on an archive, which are displayed on the Permissions tab of the
archive properties dialog in the Enterprise Vault Administration Console.
EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security
descriptor permissions for an archive.
See “IArchives :: Permissions” on page 117
See “IArchive3 :: SecurityDescriptor” on page 155
EV_STG_API_STATUS enumeration
Vault store or archive status enumeration indicates the status of the vault store
or archive storage:
enum EV_STG_API_STATUS
{
STS_AVAILABLE = 0,
STS_UNAVAILABLE = 1,
STS_TEMPORARILY_UNAVAILABLE = 2
STS_INBACKUPMODE = 3
};
Enumerations
The VaultStore Status and Archive Status properties use this enumeration to
indicate the status of the vault store or archive, and whether it can be accessed.
“IVaultStore :: Status” on page 104
“IArchive2 :: Status” on page 151
ContentManagementAPI object
This object provides top-level access (via the appropriate interfaces) to archives,
items and holds, and enables you to set and retrieve the Directory DNS Alias and
Authentication mode.
This object implements the following interfaces:
■ IContentManagementAPI
■ IContentManagementAPI4 (default)
The IContentManagementAPI interface defines methods and properties
enabling access to archives, vault stores and items. This interface inherits the
methods of the IDispatch interface.
The IContentManagementAPI2 interface provides additional properties for
accessing Enterprise Vault Directory information about vault stores and
archives.
The IContentManagementAPI3 interface provides a property for enumerating
items stored in an archive, and a method to enable applications written in Visual
Basic script to access the IContentManagementAPI3 interface.
The IContentManagementAPI4 interface provides calling applications with
extended error information if an error is encountered when using the Content
Management API methods.
Syntax
interface IContentManagementAPI : IDispatch
interface IContentManagementAPI2 : IContentManagementAPI
interface IContentManagementAPI3 : IContentManagementAPI2
interface IContentManagementAPI4 : IContentManagementAPI3
Member summary
Table 4-3 IContentManagementAPI properties
Property Read/Write Description
Archive Read only Returns an empty instance of an Archive object.
Item Read only Returns an empty instance of an Item object.
Holds Read only Returns an empty instance of a Holds object.

Table 4-3 IContentManagementAPI properties
Hold Read only Returns an empty instance of a Hold object.
DirectoryDNSAlias Read/Write Identifies an Enterprise Vault server running an

Enterprise Vault Directory Service.
AuthenticationMode Read/Write Gets or sets the authentication mode.
Table 4-4 IContentManagementAPI2 properties
VaultStores Read only Returns an empty instance of a VaultStores object.
VaultStore Read only Returns an empty instance of a VaultStore object.
Archives Read only Returns an empty instance of an Archives object.
Table 4-5 IContentManagementAPI3 property
Items Read only Returns an empty instance of an Items object.
Table 4-6 IContentManagementAPI3 method
Method Read/Write Description
IDispatchQueryInterface Read/Write Returns an interface pointer for either the

IArchiveMetaData3 or IArchive3 interface,
depending on the Interface Indentifier string (IID)
passed to it. This enables applications written in
Visual Basic script to access the
IContentManagementAPI3 interface.
Table 4-7 IContentManagementAPI4 method
Method Read Description
LastError Read Returns an interface pointer to an

ExtendedErrorInfo object, which provides
extended error information if an error is
encountered when using a Content Management
API method.
Remarks
This interface returns pointers to instances of other interfaces, such as
IVaultStores, IArchives, IItem, IHold, and IHolds. The properties of these need
to be set so that they can then be used to create, fetch, move, enumerate and
delete items, as required.
The interface also enables you to get and set the Directory DNS Alias and the
authentication mode for accessing Enterprise Vault.
For best practice on using IContentManagementAPI, see “General guidelines for
using the API” on page 52.
Requirements
■ MSXML 3.0 or later is required on the computer where you install the
application using the API.
CLSID E4BE20A4-9EF1-4B05-9117-AF43EAB4B295
Prog ID EnterpriseVault.ContentManagementAPI
Type Library EVContentManagementAPILib
DLL EVContentManagementAPI.dll
.NET Primary Interop

Assembly (PIA) KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll
.NET PIA namespace KVS.EnterpriseVault.Interop
Version information
■ The property, IContentManagementAPI::AuthenticationMode requires
Enterprise Vault 7.0 or later.
■ The IContentManagementAPI2 interface requires Enterprise Vault 2007 or

later.
■ The IContentManagementAPI3 interface requires Enterprise Vault 8.0 or
later.
■ The IContentManagementAPI4 interface requires Enterprise Vault 8.0 SP2
or later.
Examples
C++
#import "c:\program files\Enterprise Vault\

EVContentManagementAPI.dll" no_namespace, raw_interfaces_only
class SomeClass
{
IContentManagementAPI4* m_pCmAPI = NULL;
public:
void SomeClass()
{
CLSID clsid;
CLSIDFromProgID(L"EnterpriseVault.ContentManagmentAPI",
&clsid);
CoCreateInstance(clsid, NUKK, CLSCTX_ALL, __uuidof
(IContentManagementAPI), reinterpret_cast<LPVOID*> (&m_pCmAPI));
//do something else

}
C#
using KVS.EnterpriseVault.Interop;
public class SomeClass

{
IContentManagementAPI4 cmAPI = new ContentManagementClass();
//rest of class
}
IContentManagementAPI :: Archive
This property returns an empty instance of an Archive object that can then be
used to perform various tasks, such as creating an archive, or modifying various
properties.
This property is read only.
Syntax
HRESULT Archive([out,retval] IArchive** pVal)
Parameters
[out,retval] IArchive** pVal A pointer, when successful, to the location of

the IArchive pointer to the newly created
archive object. This parameter is set to NULL
if an error occurs.
Remarks
After the Create method or Get method has been called, this interface pointer
must be released and a new one obtained before calling either of these methods
again.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.
Examples
In the following examples it is assumed a reference to IContentManagmentAPI,
m_pCmAPI (C++) or cmAPI (C#) has already been obtained.
See “Examples” on page 72.
C++
IArchive* pArchive = NULL:
m_pCmAPI->get_Archive(&pArchive);
CComBSTR bstrID(L"1C9EFA88998592944ADB634ACC0D7410D1110000EVSite");
CComBSTR bstrVaultStoreId(L"16D002240AEDFAC45A44E7FBE88FDC7721
210000EVSite");
pArchive->put_Id(bstrID);
pArchive->put_VaultStoreId(bstrVaultStoreId);
pArchive->Get();
//Do something
pArchive->Release();
pArchive = NULL;
C#
IArchive archive = cmAPI.Archive;
archive.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";
archive.VaultStoreId =
"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
archive.Get();
//do something
System.Runtime.InteropServices.FinalReleaseComObject(archive);
archive = null;
IContentManagementAPI :: Item
This property returns an instance of an Item object that can then be used to
perform various tasks, such as creating an item and adding it to an archive,
fetching data, getting item properties, deleting items from an archive, copying
or moving items.
Syntax
HRESULT Item([out, retval] IItem** pVal)
Parameters
[out, retval] IItem** pVal A pointer, when successful, to the location of the
IItem pointer to the newly created item object. This
parameter is set to NULL if an error occurs.
Remarks
After the Insert, Delete or Get method has been called, this interface pointer
must be released and a new one obtained before calling any of these methods
again.
Return value
S_OK Success.
Examples
C++
IItem* pItem = NULL:
m_pCmAPI->get_Item(&pItem);
CComBSTR bstrID(L"68bd9b6a-6355-4468-b647-0ec33ade6340"); //note -

transaction id used
CComBSTR bstrArchId(L"1C9EFA88998592944ADB634ACC0D7410
D1110000EVSite");
pItem->put_Id(bstrID);
pItem->put_ArchiveId(bstrArchId);
//get item properties

pItem->Get(DETAIL_LEVEL_ITEM_PROPERTIES);
//Do something with the properties
pItem->Release();
pItem = NULL;
C#
IItem itm = cmAPI.Item;
itm.Id = "68bd9b6a-6355-4468-b647-0ec33ade6340";
itm.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";
//get item properties

itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);
System.Runtime.InteropServices.Marshal.FinalReleaseComObject(item);
item = null;
See also
■ IContent
■ ISimpleIndexMetaData
IContentManagementAPI :: Holds
This property returns an empty instance of a Holds object that can then be used
to place or release holds on a group of items with a single call to the Enterprise
Vault Server.
It exposes a standard COM interface (IEnumVariant), which manages a
collection of IHold objects.
IHolds is one of the interfaces that provides Legal Hold functionality.
Syntax
HRESULT Holds([out, retval] IHolds** pVal)
Parameters
[out, retval] IHolds** pVal A pointer, when successful, to the location of the
IHolds pointer to the newly created item object.
This parameter is set to NULL if an error occurs.
Remarks
The IHold objects used to populate the Holds collection must be obtained using
the Hold property of IContentManagementAPI.
Return value
S_OK Success.
Examples
C++
IHolds* pHolds = NULL:
m_pCmAPI->get_Holds(&pHolds);
//Do something
pHolds->Release();
pHolds = NULL;
C#
IHolds holds = cmAPI.Holds;
//do something
System.Runtime.InteropServices.FinalReleaseComObject(holds);
holds = null;
See also
■ IHold
IContentManagementAPI :: Hold
This property returns an empty instance of a Hold object that can then be used
to place an item on hold. When a hold has been placed on an item, the item
cannot be deleted from the archive until the hold is released.
IHold is one of the interfaces that provides Legal Hold functionality
Syntax
HRESULT Hold([out, retval] IHold** pVal);
Parameters
[out, retval] IHold** pVal A pointer, when successful, to the location of the
IHold pointer to the newly created item object. This
parameter is set to NULL if an error occurs.
Remarks
The IHold interface is the mechanism by which hold(s) are placed on an item
archived in Enterprise Vault. The interface allows various properties to be set
before the Hold is added to the Holds collection in Enterprise Vault. The Holds
collection is exposed via the IHolds interface.
Return value
S_OK Success.
Examples
C++
IHolds* pHolds = NULL:
m_pCmAPI->get_Holds(&pHolds);
IHold* pHold = NULL;
m_pCmAPI->get_Hold(&pHold);
//Set properties
pHolds->Add(pHold);
pHold->Release();
pHold = NULL;
pHolds->Release();
pHolds = NULL;
C#
IHold hold = cmAPI.Hold;
//add some properties
holds.Add(hold);
System.Runtime.InteropServices.FinalReleaseComObject(holds);
holds = null;
System.Runtime.InteropServices.FinalReleaseComObject(hold);
hold = null;
See also
■ IHolds
IContentManagementAPI :: DirectoryDNSAlias
This property is used to identify a computer running an Enterprise Vault
Directory Service, in order to retrieve information from the Enterprise Vault
Directory.
This property is read/write.
Syntax
HRESULT DirectoryDNSAlias([out, retval] BSTR* pVal);
HRESULT DirectoryDNSAlias([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that, on return, will contain the
current value.
[in] BSTR newVal The new value can be any one of the following:
■ DNS alias of a computer hosting an Enterprise
Vault Directory Service.
■ IP address of a computer hosting an Enterprise
Vault Directory Service.
■ Id of the Enterprise Vault Site.
■ Id of any archive in the Site.
■ Id of any vault store in the Site.
Remarks
The Id of an Enterprise Vault Site can be found in the following registry entry on
an Enterprise Vault server:
HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID
The Id of an archive can be found in the Enterprise Vault Administration
Console, in the properties dialog for an archive.
Similarly, the Id of a vault store can be found in the Administration Console, in
the properties dialog for a vault store.
Return value
S_OK Success.
Examples
C++
CComBSTR bstrDNS(L"EVSERVER1");
m_pCmAPI->get_DirectoryDNSAlias(&bstrDNS);
//Do something
C#
[out]
string dns = cmAPI.DirectoryDNSAlias;
[in]
cmAPI.DirectoryDNSAlias = dns;
IContentManagementAPI :: AuthenticationMode
This property is used to get or set the mode to be used when authenticating to
Enterprise Vault. This can be either DCOM or Enterprise Vault authentication
server.
The property is read/write.
Syntax
HRESULT AuthenticationMode([out, retval]
EV_STG_API_AUTHENTICATE_USING* pVal)
HRESULT AuthenticationMode([in]
EV_STG_API_AUTHENTICATE_USING newVal)
Parameters
[out, retval]EV_STG_API_AUTHENTICATE_USING* pVal Pointer to an EV_STG_API_

AUTHENTICATE_USING
object which will return the
current authentication
mode.
[in]EV_STG_API_AUTHENTICATE_USING newVal New value for the

authentication mode.
Remarks
EV_STG_API_AUTHENTICATE_USING enumerator defines the authentication
mode to use.
See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 60.
In releases prior to Enterprise Vault 7.0, authentication was performed using
DCOM when the API application was not installed on an Enterprise Vault server,
otherwise Enterprise Vault authentication server was used. From Enterprise
Vault 7.0, DCOM authentication is used by default.
From Enterprise Vault 8.0 SP2,
AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default
enumeration value. This value means that DCOM will be used.
Authentication using the Enterprise Vault authentication server can only be
used by applications installed on a configured Enterprise Vault server, and
should only be used on advice from Symantec Support.
Return value
S_OK Success.
Examples
C++
m_pCmAPI->put_AuthenticationMode(AUTHENTICATE_USING_DCOM_SECURITY);
C#
cmAPI.AuthenticationMode =
EV_STG_API_AUTHENTICATE_USING.AUTHENTICATE_USING_DCOM_SECURITY;
IContentManagementAPI2 :: VaultStores
This property returns an empty instance of the VaultStores object, which
enables applications to enumerate details of the vault stores configured in
Enterprise Vault.
Syntax
HRESULT VaultStores([out, retval] IUnknown** pVal);
Parameters
[out, retval] IUnknown** pVal Reference to an empty VaultStores object.
Remarks
When successful, a pointer to an IUnknown* that can be QI'd (cast) for an
IVaultStores interface pointer.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL
Examples
C++
IVaultStores pVaultStores = NULL;
m_pCmAPI->get_VaultStores(&pVaultStores);
CComBSTR bstrComputer(L"EVSERVER1");
pVaultStores->put_Computer(bstrComputer);
pVaultStores->Get();
C#
IVaultStores vaultStores = cmAPI.VaultStores;
vaultStores.Computer = "EVSERVER1";
vaultStores.Get();
See also
■ “VaultStores object” on page 94.
IContentManagementAPI2 :: VaultStore
This property returns an empty instance of the VaultStore object, which can be
used to read the details of a vault store.
Syntax
HRESULT VaultStore([out, retval] IUnknown** pVal);
Parameters
[out, retval] IUnknown** pVal Reference to an empty VaultStore object.
Remarks
To populate the Vault Store object, set the Id property to that of the vault store
then call Get.
Return value
S_OK Success.
EXAMPLES
C++
CComPtr<IVaultStore> spVaultStore;
CComPtr<IUnknown> spUnk;
m_pCmAPI->get_VaultStore(&pUnk);
spUnk->QueryInterface(&spVaultStore);
CComBSTR bstrID(L"16D002240AEDFAC45A44E7FBE88FDC772121
0000EVSite");
spVaultStore->put_Id(bstrID);
spVaultstore->Get();
C#
IVaultStore vaultStore = cmAPI.VaultStore;
vaultStore.ID = "16D002240AEDFAC45A44E7FBE88FDC7721210000
EVSite";
vaultStore.Get();
See also
■ “VaultStore object” on page 98.
IContentManagementAPI2 :: Archives
IContentManagementAPI2 :: Archives
This property returns an instance of the Archives collection object, which
enables applications to enumerate archives configured in the current vault
store.
Syntax
HRESULT Archives([out, retval] IUnknown** pVal);
Parameters
[out, retval] IUnknown** pVal An instance of an Archives object.
Return value
S_OK Success.
EXAMPLES
C++
CComPtr<IArchives> spArchives;
m_pCmAPI->get_Archives(&spUnk);
spUnk->QueryInterface(&spArchives);
CComBSTR
bstrVaultStore(L"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite");
spArchives->put_VaultStore(bstrVaultStore);
spArchives->put_ArchiveTypes(ARCHIVE_TYPE_EXCHANGE_MAILBOX);
See also
■ “Archives object” on page 109.
IContentManagementAPI3 :: Items
IContentManagementAPI3 :: Items
This property returns an empty instance of the Items object, which is populated
by calling IItems::Get. Applications can then enumerate the items in the archive.
Syntax
HRESULT Items([out, retval] IUnknown** pVal);
Parameters
[out, retval] IUnknown** pVal Reference to an empty Items object.
Remarks
An IItems interface pointer can be obtained by calling QueryInterface on the
returned IUnknown* pointer.
Return value
S_OK Success.
Example
C++
// Get empty items collection for populating
CComPtr<IContentManagementAPI3> spCMAPI;
spCMAPI.CreateInstance(CComBSTR(L"EnterpriseVault.ContentManagement
API"));
// Get an Items object for enumeration

spCMapi->get_Items(&spUnk);
CComQIPtr<IItems> spItems(spUnk);
See also
■ “Items object” on page 162.
IContentManagementAPI3 :: IDispatchQueryInterface
IContentManagementAPI3 ::
IDispatchQueryInterface
This method enables calling applications written in Visual Basic Script to access
the properties of the following interfaces:
■ IArchive3
■ IItem2
IArchive3 and IArchiveMetaData2 were introduced at Enterprise Vault 8.0.
IItem2 was introduced at Enterprise Vault 8.0 SP3.
Syntax
HRESULT IDispatchQueryInterface ([in] IDispatch* pUnkObj,
[in] BSTR interfaceId,
[out, retval] IDispatch** ppUnkRetVal);
Parameters
[in] IDispatch* pUnkObj IDispatch interface pointer associated

with the object being queried.
[in] BSTR interfaceId Interface Identifier (IID) string

associated with the interface being
queried.
[out, retval] IDispatch** ppUnkRetVal Pointer for returning the queried

interface object.
Remarks
The pointer for returning the queried interface object returns NULL, and an
error is reported, if the interface is not supported.
Return value
S_OK Success
IContentManagementAPI3 :: IDispatchQueryInterface
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either of pUnkObj or ppUnkRetVal

are NULL, or interfaceId is empty,
is not a valid interface ID (IID), or
the interface is not available on the
object being queried.
Example
The following Visual Basic Script example illustrates how to use this method to
query for an IArchiveMetaData2 interface (with the IID string
“{5C6882BD-24BE-4C32-87EF-C3701D949BAA}” ) from an IArchiveMetaData
object interface, in order to access the IArchiveMetaData2::SequenceNum
property.
dim cmAPI, item, SeqNo, IAMD2

set cmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")
set item = ContentManagementAPI.Item
set IAMD2 = cmAPI.IDispatchQueryInterface(item.ArchiveMetaData,
"{5C6882BD-24BE-4C32-87EF-C3701D949BAA}")
if (IAMD2 is nothing) then
MsgBox "ArchiveMetaData2 API Object create failed!"
end if
SeqNo = IAMD2.SequenceNum
See also
■ “Archive object” on page 120
■ “ArchiveMetaData object” on page 237
IContentManagementAPI4 :: LastError
IContentManagementAPI4 :: LastError
This method provides calling applications with extended error information if an
error is encountered when using the Content Management API methods.
Syntax
HRESULT LastError([out,retval] IUnknown** pVal);
Parameters
[out,retval] IUnknown** pVal A reference to an ExtendedErrorInfo

object.
Remarks
The ExtendedErrorInfo object provides error details for the last call to a Content
Management API method.
It is important to follow recommended best practice, and avoid sharing
IContentManagementAPI interface objects across threads, as this could cause
error information from a call on another thread to be returned.
See “Programming notes” on page 46.
Return value
S_OK Success
See also
■ “ExtendedErrorInfo object” on page 355
VaultStores object
VaultStores object
This object implements the following interface:
■ IVaultStores
The IVaultStores interface inherits the properties and methods of the
ICollectionBase interface.
The IVaultStores interface enables applications to enumerate the vault stores
configured in an Enterprise Vault Site.
Syntax
interface IVaultStores : ICollectionBase
Member summary
Table 4-8 IVaultstores properties
Computer Read/Write Identity of an Enterprise Vault server running a

Directory Service.
Table 4-9 and Table 4-10 list the properties and methods of the ICollectionBase
interface. For more detail see “ICollectionBase : IDispatch” on page 344.
Table 4-9 ICollectionBase properties
Count Read only Number of vault stores in the collection.
_NewEnum Read only Instance of the standard COM enumerator for

the collection.
Item Read only Instance of the vault store at the zero-based

index into the collection.
Maximum Read/Write Maximum number of vault stores in the

collection.
More Read only Whether or not there were more vault stores
than Maximum.
VaultStores object
Table 4-10 ICollectionBase methods
Method Description
Get Populate the collection.
Clear Clear the current collection.
Reset Reset the object back to the initial state.
Remarks
Use the ICollectionBase :: Get method of this interface to obtain a collection of
VaultStore objects, and automatically populate the properties of each
VaultStore object .
See “VaultStore object” on page 98.
Version information
■ This interface is available from Enterprise Vault 2007.
Example
C#
This example code lists all vault stores based on a Computer DNS name.
IContentManagementAPI3 cmAPI = (IContentMangementAPI3)
new ContentManagementAPI();
IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores;
// Populate collection from EV1
vaultStores.Computer = “EV1.Acme.com”;
vaultStores.Get();
// Process each Vault Store
foreach(IVaultStore vaultStore in vaultStores)
{
ProcessIt(vaultStore.Id, vaultStore.Name);
}
IVaultStores :: Computer
This property identifies an Enterprise Vault server running a Directory Service.
Syntax
HRESULT Computer([in] BSTR pVal);
HRESULT Computer([out, retval] BSTR* pVal);
Parameters
[in] BSTR pVal The DNS name of an Enterprise Vault server, or the Id of
an Enterprise Vault entity, such as site or vault store.
[out, retval] BSTR* pVal A pointer to a string that will hold the returned value.
Remarks
This property can be set with any identifier that Enterprise Vault can use to
identify an Enterprise Vault server running a Directory Service, for example:
■ DNS name
■ IP address
■ The Id of an Enterprise Vault entity, for example:
■ Enterprise Vault Site Id
■ Vault store Id
■ Archive Id
If the Computer property is left empty than its value defaults to the current
value of the DirectoryDNSAlias property of the parent IContentManagementAPI
instance.
Return value
S_OK Success.
Example
C#
IContentManagementAPI3 cmAPI = (IContentMangementAPI3)
new ContentManagementAPI();
IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores;
// Populate collection from EV1
vaultStores.Computer = “EV1.Acme.com”;
vaultStores.Get();
// Process each Vault Store
foreach(IVaultStore vaultStore in vaultStores)
{
ProcessIt(vaultStore.Id, vaultStore.Name);
}
VaultStore object
VaultStore object
■ IVaultStore
The IVaultStore interface enables external applications to get details of a vault
store.
Syntax
interface IVaultStore : IDispatch
Member summary
Table 4-11 IVaultstore properties
Id Read/Write Vault store Id.
Name Read only Vault store name.
Description Read only Vault store description.
Status Read only Status of vault store.
ArchiveCount Read only Number of archives in the vault store.
DirectoryDNSAlias Read only Identifies an Enterprise Vault server

running an Enterprise Vault Directory
Service.
Table 4-12 IVaultStore methods
Method Description
Get Get the details of the selected vault store.
Remarks
If you use the ICollectionBase interface to enumerate vault stores (see
“VaultStores object” on page 94), then the IVaultStore properties are populated
automatically for each vault store returned.
Alternatively, if you select a specific vault store using the Id property, you can
call the Get method to populate the VaultStore properties.
VaultStore object
Version information
Example
C#
vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
vaultStore.Get();
//now get vault store properties
string name = vaultStore.Name;
string description = vaultsStore.Description;
string dnsAlias = vaultStore.DirectoryDNSAlias;
EV_STG_API_STATUS evStatus = vaultStore.Status;
long count = vaultStore.ArchiveCount;
IVaultStore :: Id
IVaultStore :: Id
This property contains the Id of the target vault store.
Syntax
HRESULT Id([out, retval] BSTR* pVal);
HRESULT Id([in] BSTR newVal);
Parameters
[in] BSTR pVal Id of the required vault store.
[out, retval] BSTR* pVal String that will contain the Id of the vault store.
Remarks
The Id of a vault store can be found in the Administration Console, in the
properties dialog for a vault store.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, pVal

is not a valid Vault
Store identity, or
the object is
already populated.
Example
C#
vaultStore.Get();

IVaultStore :: Id

IVaultStore :: Name
IVaultStore :: Name
This property contains the name of the selected vault store.
The property is read only.
Syntax
HRESULT Name([out, retval] BSTR* pVal);
Parameter
[out, retval] BSTR* pVal Name of the vault store.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.
Example
C#
vaultStore.Get();
IVaultStore :: Description
IVaultStore :: Description
This property contains the vault store description.
Syntax
HRESULT Description([out, retval] BSTR* pVal);
Parameter
[out, retval] BSTR* pVal Vault store description.
Return value
S_OK Success.
Example
C#
vaultStore.Get();
long count = vaultStore.Count;
IVaultStore :: Status
IVaultStore :: Status
This property contains the status of the vault store.
Syntax
HRESULT Status([out, retval] EV_STG_API_STATUS* pVal);
Parameter
[out, retval] EV_STG_API_STATUS* pVal EV_STG_API_STATUS enumerated

value.
Remarks
EV_STG_API_STATUS is an enumerated type. See “EV_STG_API_STATUS
enumeration” on page 67.
Return value
S_OK Success.
Example
C#
vaultStore.Get();
IVaultStore :: ArchiveCount
This property contains the number of archives in the vault store.
Syntax
HRESULT ArchiveCount([out, retval] long* pVal);
Parameter
[out, retval] long* pVal Number of archives currently in the vault store.
Remarks
This property is populated using an additional call to the Enterprise Vault
server. For this reason, it is only populated when explicitly requested.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory service

is not running.
CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are

currently busy or do not have
sufficient resources to complete the
request. The request should be retried
later.
Example
C#
vaultStore.Get();

IVaultStore :: DirectoryDNSAlias
IVaultStore :: DirectoryDNSAlias
This property contains the DNS Alias created for the Enterprise Vault Site.
Syntax
Parameter
[out, retval] BSTR* pVal DNS alias for the Enterprise Vault Site.
Remarks
When configuring Enterprise Vault, a DNS alias is assigned to the IP address of
the computer that hosts the primary Enterprise Vault Directory Service for the
Enterprise Vault Site.
Return value
S_OK Success.
Example
C#
vaultStore.Get();
IVaultStore :: Get
IVaultStore :: Get
This method returns the properties for the selected vault store.
Syntax
HRESULT Get(void);
Remarks
If you do not enumerate vault stores using the IVaultStores interface, then you
can set the Id property of the IVaultStore interface and call Get to populate the
IVaultStore properties.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The vault store does not exist.
CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory

service is not running.

request. The request should be
retried later.
Example
C#
vaultStore.Get();
Archives object
Archives object
■ IArchives
The IArchives interface inherits the properties and methods of the
ICollectionBase interface.
This interface enables applications to enumerate archives optionally filtered by
archive name, type, permissions or vault store.
Syntax
interface IArchives : ICollectionBase
Member summary
Table 4-13 IArchives properties
Computer Read/Write An Enterprise Vault server running an

Enterprise Vault Directory Service.
VaultStoreId Read/Write Id of the vault store containing the required

archive or archives.
ArchiveName Read/Write Name, or part of the name, of the required

Permissions Read/Write Caller’s access permissions on the required

ArchiveTypes Read/Write Types of archives required.
Count Read only Number of archives in the collection.

the collection.
Archives object
Item Read only Instance of the archive at the zero-based index

into the collection.
Maximum Read/Write Maximum number of archives in the collection.
More Read only Indicates whether there are more archives

available than the maximum allowed in the
collection.
Method Description
Remarks
Use the ICollectionBase :: Get method of this interface to obtain a collection of
Archive objects, and automatically populate the properties of each Archive
object .
The properties of the IArchives interface enable you to select which archives
you want returned.
The ICollectionBase :: Get method supports archive selection using
combinations of properties, subject to the following rules:
■ If you set Computer, you can also set the one of the following properties or
combinations of properties:
■ ArchiveName
■ ArchiveName and ArchiveType
■ Permissions
■ Permissions and ArchiveType
■ ArchiveType
■ If you set VaultStoreId, the only other property that you can set is
ArchiveType.
Archives object
No other combinations of properties are supported.
Version information
■ This interface requires Enterprise Vault 2007 or later.
Example
C#
IArchives archives = (IArchives)cmAPI.Archives;
See also
■ “Enumerating vault stores, archives and items” on page 53.
■ “ICollectionBase : IDispatch” on page 344.
■ “Archive object” on page 120.
IArchives :: Computer
This property identifies an Enterprise Vault server running a Directory Service.
Syntax
HRESULT Computer([in] BSTR pVal);
HRESULT Computer([out, retval] BSTR* pVal);
Parameters
[in] BSTR pVal The DNS name of an Enterprise Vault server, or the Id of
an Enterprise Vault entity, such as site or vault store.
[out, retval] BSTR* pVal A pointer to a string that will hold the returned value.
Remarks
This property can be set with any identifier that Enterprise Vault can use to
identify an Enterprise Vault server running a Directory Service, for example:
■ DNS name
■ IP address
■ The Id of an Enterprise Vault entity in the Directory, for example:
■ Enterprise Vault Site Id
■ Vault store Id
■ Archive Id
If the Computer property is left empty than its value defaults to the current
value of the DirectoryDNSAlias property of the parent IContentManagementAPI
instance.
Return value
S_OK Success.
Example
C#
This example gets all the archives that the user has permission to search.
archives.Computer = "EV1.acme.com";
archives.Permissions =
EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;
archives.Get();
IArchives :: VaultStoreId
IArchives :: VaultStoreId
This property contains the Id of the vault store that contains the required
Syntax
HRESULT VaultStoreId([in] BSTR pVal);
HRESULT VaultStoreId([out, retval] BSTR* pVal);
Parameters
[in] BSTR pVal Id of the required vault store.
[out, retval] BSTR* pVal String that will contain the Id of the vault store.
Remarks
The Id of a vault store can be found in the Administration Console, in the
properties dialog for a vault store, or by enumerating vault stores using the
VaultStores object.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or pVal is not a valid

vault store identity.
Example
This example gets all Exchange Server mailbox archives in a particular vault
store.
C#
IArchives archs = (IArchives)cmAPI.Archives;
archs.VaulStoreId =
"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
archs.ArchiveTypes =
EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX;
archs.Get();
IArchives :: ArchiveName
This property enables archives to be selected by name or partial name.
Syntax
HRESULT ArchiveName([in] BSTR pVal);
HRESULT ArchiveName([out, retval] BSTR* pVal);
Parameters
[in] BSTR pVal Name or partial name of required archive or archives.
[out, retval] BSTR* pVal Pointer to a string that will contain the archive names.
Remarks
Multiple archives can be selected by use of common wildcard syntax. The
following wildcard features are supported:
■ * to match none, one or any number of characters.
■ % to match any single character.
■ [] matches any single character within the specified range or set (case
insensitive). For example
■ [abdf] to match any of the set of characters a,b,d, or f.
■ [a-f] to match any of the range of characters a,b,c,d,e, or f.
■ [^] to match any single character not in the specified range or set (case
insensitive). For example
■ [^abdf] to match any character not in the set of characters a, b,d, or f.
■ [^a-f] to match any character not in the range of characters a,b,c,d,e, or
f.
■ \ escapes *, %, or [ to enable matching on those characters. For example,
50\% is used to match with 50%.
The returned collection is ordered by archive name.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .
Example
This example retrieves all archives with a name ending in ‘Smith’.
C#
IArchives archs = cmAPI.Archives;
archs.Computer = “SERVER1”;
archs.ArchiveName = “*Smith”;
archs.Get();
IArchives :: Permissions
This property enables selection of archives based on the archive access
permissions of the caller.
Syntax
HRESULT Permissions([in] EV_STG_API_PERMISSIONS_TYPE pVal);
HRESULT Permissions([out, retval] EV_STG_API_PERMISSIONS_TYPE*
pVal);
Parameters
[in] EV_STG_API_PERMISSIONS_TYPE pVal New EV_STG_API_

PERMISSIONS_TYPE value.
[out, retval] EV_STG_API_PERMISSIONS_TYPE* pVal Caller's archive access

permissions.
Remarks
EV_STG_API_PERMISSIONS_TYPE is an enumerated type that indicates the
required archive permissions. See “EV_STG_API_PERMISSIONS_TYPE
The permissions checks are based on the current Windows identity of the caller.
If the caller is currently impersonating, then the impersonation identity is used.
Currently there is no support for the Lotus Domino authentication model.
Return value
S_OK Success.
Example
C#
archives.Computer = "EV1.acme.com";
archives.Get();
IArchives :: ArchiveTypes
IArchives :: ArchiveTypes
This property enables the selection of archives based on the type of archive. For
example, Exchange Server mailbox archive, FSA archive, SharePoint archive,
and so on.
Syntax
HRESULT ArchiveTypes([in] LONG pVal));
HRESULT ArchiveTypes([out, retval] LONG* pVal);
Parameters
[in] LONG pVal One or more values of EV_STG_API_ARCHIVE_TYPE.
[out, retval] LONG* pVal One or more values of EV_STG_API_ARCHIVE_TYPE.
Remarks
EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.
See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.
Return value
S_OK Success.
Example
C#
archives.ArchiveTypes =
(int)EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX;
(int)EV_STG_API_PERMISSIONS_TYPE.PERMISSION_SEARCH;
archives.Get();
Archive object
Archive object
■ IArchive
IID is {48092C71-5618-4EB5-9060-01030C191450}
■ IArchive2
IID is {B85C5178-0B9D-4987-8DC5-92F77B33879E}
■ IArchive3
IID is {9E2C0ACF-4CB5-4FB3-A9AB-499BB9EE959C}
These interfaces enable the creation and examination of archives in a vault
store.
IArchive2 provides additional properties to enable querying the type and status
of an archive.
IArchive3 provides additional properties to enable setting and querying the
access security assigned to an archive.
Syntax
interface IArchive : IDispatch
interface IArchive2 : IArchive
interface IArchive3 : IArchive2
Member summary
Table 4-16 IArchive properties
VaultStoreId Read/Write Identifies the vault store in which the archive

resides.
Id Read/Write Archive ID of the archive.
Name Read/Write Name of the archive.
Description Read/Write Provides description of the archive.
ExpireItems Read/Write Enables automatic storage expiry for archive.
ConvertedContent Read/Write Controls whether converted content is stored

with item or generated on demand.
Archive object
Table 4-16 IArchive properties
IndexLevel Read/Write Sets level of indexing.
IndexUrgency Read/Write Control whether items are indexed on

archiving.
Size Read only Size of the archive. (This is not the original item
size)
SecurityDescriptor Write only Security permissions for the archive, specified

as a variant byte array containing a
SECURITY_DESCRIPTOR structure.
ComplianceDevice Read only Indicates whether the archive resides on a

device capable of setting compliance periods.
ItemCount Read only Number of items in the archive.
Table 4-17 IArchive2 properties
Type Read only The type of the archive.
Status Read only Status of the storage where the archive is

located, that is, whether it can be accessed.
HasFolders Read only Whether archive structure is flat or has folders.
Full Read only Whether the archive is full.
DirectoryDNSAlias Read only Directory DNS Alias of the hosting the archive.
SecurityDescriptor Read/Write The security permissions on the archive

specified as a variant byte array containing a
SECURITY_DESCRIPTOR structure.
Archive object
SecurityDescriptorString Read/Write The security permissions on the archive

specified using Security Descriptor String
Format as described in MSDN.
Type Read/Write The type of the archive.
Table 4-19 IArchive methods
Method Description
Create Creates an archive.
Get Retrieves details of the selected archive.
Remarks
After the Create method or Get method has been called on this interface, the
reference must be released and a new one obtained before calling either of these
methods again.
Version information
■ IArchive2 interface requires Enterprise Vault 2007 or later.
■ IArchive3 interface requires Enterprise Vault 8.0 or later.
Example
C#
IArchive arch = cmAPI.Archive
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();
IArchive :: VaultStoreId
IArchive :: VaultStoreId
This property identifies the vault store in which the archive resides or will
reside.
Syntax
HRESULT VaultStoreId([in] BSTR newVal)
HRESULT VaultStoreId([out,retval] BSTR* pVal)
Parameters
[in] BSTR newVal Id of the required vault store.
[out,retval] BSTR* pVal Pointer to a BSTR that contains the Id of the

required vault store
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Incorrect Id format.
Example
arch.VaultStoreId =
arch.Get();
IArchive :: Id
IArchive :: Id
This property contains the Archive Id of the archive.
Syntax
Parameters
[in] BSTR newVal The Archive Id of the archive.

This value is displayed in the properties of
the archive in the Administration Console.
Maximum length of string: 112 characters.
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the
current value.
Remarks
This value must be set prior to calling Get.
If an attempt to change this value on an existing archive is made then an error
will occur.
The following is an example value of the Id property:
“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, pVal is not a valid

archive identity, or the object is
already populated.
IArchive :: Id
Examples
arch.VaultStoreId =
arch.Get();
or
[out]
Assume an Archives object, 'archives', has been populated.
foreach (IArchive archive in archives)
{
SearchArchive(archive.Id);
}
IArchive :: Name
IArchive :: Name
This property is used to set the name for a new archive or retrieve the name of
an existing archive.
Syntax
HRESULT Name([in] BSTR newVal)
HRESULT Name([out,retval] BSTR* pVal)
Parameters
[in] BSTR newVal The name of the archive.

Maximum length: 256 characters.
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the name of an archive.
Remarks
This property must be set before creating an archive, but is not required to get
an archive.
Any attempt to change the name of an existing archive will result in an error.
The value must contain printable characters only, and cannot be blank or an
empty string.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal contains

invalid characters, or the object is
already populated.
Example
[in]
arch.Name = “my new archive”;
arch.Description = “my new archive description”;
arch.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS;
IArchive :: Name
arch.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.
CONVERTED_CONTENT_STORED;
arch.IndexUrgency = EV_STG_API_INDEX_URGENCY.
INDEX_ITEMS_IMMEDIATELY;
arch.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;
arch.Create();
[out]
arch.VaultStoreId =
arch.Get();
string name = arch.Name;

string description = arch.Description;
EV_STG_API_EXPIRE_ITEMS evEI = arch.ExpireItems;
EV_STG_API_CONVERTED_CONTENT evCC = arch.ConvertedContent;
EV_STG_API_INDEX_URGENCY evIU = arch.IndexUrgency;
EV_STG_API_INDEX_LEVEL evIL = arch.IndexLevel;
ulong size = (ulong) arch.Size;
bool complianceDevice = arch.ComplianceDevice;
uint itemCount = (uint) arch.ItemCount;
IArchive :: Description
This property contains a more complete description of the archive.
Syntax
HRESULT Description([in] BSTR newVal)
HRESULT Description([out,retval] BSTR* pVal)
Parameters
[in] BSTR newVal Description of the archive.

Max length: 127 characters.
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the

description of the archive.
Remarks
The [in] property can only be used to set the description of a new archive before
it is created. Any attempt to change the description of an existing archive will
result in an error.
The property is optional. If supplied, the value must contain printable
characters only.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal contains

invalid characters, or the object is
already populated.
Examples
C++
CComBstr bstr = new CComBSTR(L”archive description”);
archive->put_Description(bstr):
//do something – create archive

//then check name
archive->get_ Description (&bstr);
//try changing name

bstr = L”New description”;
archive->put_ Description (bstr); //ERROR
C#
archive. Description = “archive description”;

//then check name
string name = archive. Description;
//try changing name

archive. Description = “New description”; //ERROR
IArchive :: ExpireItems
This property specifies whether or not items should be automatically deleted
(expired) from the archive.
Syntax
HRESULT ExpireItems([out, retval] EV_STG_API_EXPIRE_ITEMS* pVal);
HRESULT ExpireItems([in] EV_STG_API_EXPIRE_ITEMS newVal);
Parameters
[out, retval] EV_STG_API_EXPIRE_ITEMS* pVal Pointer to an

EV_STG_API_EXPIRE_ITEMS
object that will contain the current
value.
[in] EV_STG_API_EXPIRE_ITEMS newVal Sets a new value of ExpireItems.
Remarks
The required value must be set prior to calling Create.
The [in] property can only be used to set the ExpireItems value of a new archive
before it is created. Any attempt to change this value in an existing archive will
result in an error.
Do not attempt to retrieve a value for ExpireItems before creating or getting an
archive, as an error will occur. No default value is set for this property.
EV_STG_API_EXPIRE_ITEMS is an enumeration type that indicates whether
expired items should be deleted automatically from the archive.
See “EV_STG_API_EXPIRE_ITEMS enumeration” on page 63.
It may be necessary to cast this to an integer if using in C#.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or

the object is already populated.
Examples
C++
EV_STG_API_EXPIRE_ITEMS ei = DONT_EXPIRE_ITEMS;
archive->put_ExpireItems(ei);
//do other things and create archive

//Now check value
archive->get_ExpireItems(&ei);
//try changing value
archive->put_ExpireItems(EXPIRE_ITEMS); //ERROR
C#
EV_STG_API_EXPIRE_ITEMS ei =
EV_STG_API_EXPIRE_ITEMS.DONT_EXPIRE_ITEMS;
archive.ExpireItems = ei;

//Now check value
ei = archive.ExpireItems;
//try changing value
archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;
//ERROR
IArchive :: ConvertedContent
This property specifies whether converted content is stored in the item or
generated on demand.
Syntax
HRESULT ConvertedContent([out, retval]
EV_STG_API_CONVERTED_CONTENT* pVal);
HRESULT ConvertedContent([in] EV_STG_API_CONVERTED_CONTENT newVal);
Parameters
[out, retval]EV_STG_API_CONVERTED_CONTENT* pVal Pointer to an

EV_STG_API_CONVERTE
D_CONTENT object that
will contain the current
value.
[in] EV_STG_API_CONVERTED_CONTENT newVal The new value of

ConvertedContent.
Remarks
This property must be set before calling Create. Any attempt to retrieve the
value of this property before Get or Create has been called will result in an error.
Any attempt to change this value on an existing archive will result in an error.
EV_STG_API_CONVERTED_CONTENT enumeration indicates whether to store
converted content with the item.
“EV_STG_API_CONVERTED_CONTENT enumeration” on page 61.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or the

object is already populated.
Examples
C++
EV_STG_API_CONVERTED_CONTENT cc = CONVERTED_CONTENT_STORED;
archive->put_ConvertedContent(cc);

//Now check value
archive->get_ConvertedContent(&cc);
//try and change value
archive->put_ConvertedContent(CONVERTED_CONTENT_ON_DEMAND);
//ERROR
C#
EV_STG_API_CONVERTED_CONTENT cc =
EV_STG_API_CONVERTED_CONTENT.CONVERTED_CONTENT_STORED;
archive.ConvertedContemt = cc;
//do other things – create archive

//check value
cc = Archive.ConvertedContent;
//try and change the value
archive.ConvertedContent =
EV_STG_API_CONVERTED_CONTENT.CONVERTED_ON_DEMAND; //ERROR
IArchive :: IndexUrgency
This property specifies when items are indexed.
Syntax
HRESULT IndexUrgency([out, retval] EV_STG_API_INDEX_URGENCY* pVal);
HRESULT IndexUrgency([in] EV_STG_API_INDEX_URGENCY newVal);
Parameters
[out, retval] EV_STG_API_INDEX_URGENCY* pVal Pointer to an

EV_STG_API_INDEX_URGENCY
object that will contain the
current value
[in] EV_STG_API_INDEX_URGENCY newVal New value of

Remarks
This property must be set before calling Create. Any attempt to retrieve the
value of this property before Get or Create have been called will result in failure.
EV_STG_API_INDEX_URGENCY enumeration indicates whether to index items
as they are stored.
See “EV_STG_API_INDEX_URGENCY enumeration” on page 64.
Deferring indexing may be useful if you want to store a very large number of
items quickly.
INDEX_ITEMS_DEFER_INDEFINITELY was originally introduced to be used
with File System Archiving only. If this value is set, the items will not be indexed
until the value has been reset to IMMEDIATELY, and the next time the Indexing
Service runs it will process the index backlog.
Return value
S_OK Success.

Examples
C++
iu = INDEX_ITEMS_IMMEDIATELY;
;
archive->put_IndexUrgency(iu);
//do more and create archive

//Now check value
archive->get_ IndexUrgency (&iu);
archive->put_ IndexUrgency (INDEX_ITEMS_DEFER_INDEFINITELY);

//ERROR
C#
EV_STG_API_INDEX_URGENCY iu =
EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_IMMEDIATELY;
archive.IndexUrgency = iu;
//do other things – create archive

//check value
iu = Archive. IndexUrgency ;
archive. IndexUrgency =
EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_DEFER_INDEFINITELY; //ERROR
IArchive :: IndexLevel
This property determines the level of detail stored in the archive’s index.
Syntax
HRESULT IndexLevel([out, retval] EV_STG_API_INDEX_LEVEL* pVal);
HRESULT IndexLevel([in] EV_STG_API_INDEX_LEVEL newVal);
Parameters
[out, retval] EV_STG_API_INDEX_LEVEL* pVal Pointer to an

EV_STG_API_INDEX_LEVEL
object that will contain the
current value.
[in] EV_STG_API_INDEX_LEVEL newVal New value of

EV_STG_API_INDEX_LEVEL.
Remarks
EV_STG_API_INDEX_LEVEL enumeration indicates how much of an item is
indexed.
See “EV_STG_API_INDEX_LEVEL enumeration” on page 63.
The Indexing service manages the indexes of archived data to enable users to
search for archived items.
When users search the archives to which they have access, the index volume
files are searched. The more information that is indexed about an item, the
quicker it is to find the item. However, the more information that is indexed
about an item, the more disk space is required for the index.
Return value
S_OK Success.

Examples
C++
EV_STG_API_INDEX_LEVEL il = INDEX_LEVEL_MEDIUM;
EV_STG_API_INDEX_LEVEL il = INDEX_LEVEL_BRIEF;
archive->put_IndexLevel(il);
//do something and create archive

//Now check value
archive->get_ IndexLevel (&il);
archive->put_ IndexLevel (INDEX_LEVEL_FULL); //ERROR
C#
EV_STG_API_INDEX_URGENCY il =
EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_MEDIUM;
EV_STG_API_INDEX_URGENCY il =
EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_BRIEF;
archive. IndexLevel = il;

//check value
il = Archive. IndexLevel;
archive. IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;

//ERROR
IArchive :: Size
IArchive :: Size
This property contains the size of the archive.
Syntax
HRESULT Size([out, retval] VARIANT* pVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain

the size of the archive, expressed in
Kbytes. The VT type is a VT_U18.
Remarks
Property will only contain a value once an archive has been created.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, or the object has not

been populated.
CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or

Storage services are not running

retried later.
Example
arch.VaultStoreId =
arch.Get();

IArchive :: Size

IArchive :: SecurityDescriptor
This property contains the self-relative security descriptor to be used when
creating an archive.
The property is write only.
(A read/write version of the property is available on the IArchive3 interface).
Syntax
HRESULT SecurityDescriptor([in] VARIANT newVal);
Parameters
[in] VARIANT newVal New value of the security descriptor.
Remarks
Any attempt to modify the security descriptor of an existing archive will result
in an error.
The self-relative security descriptor may override the current user.
If the type of the variant is VT_ARRAY then the variant is a byte array
containing the SECURITY_DESCRIPTOR for the user account that will be given
access to the archive.
If the type of the variant is VT_EMPTY then the security descriptor is set to
default (that is, the user creating the archive has full access to the archive).
Finally a type of VT_NULL means that the archive is created without any
permissions.
descriptor permissions for an archive.
See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.
The values of the EV_STG_API_PERMISSIONS_TYPE enumerator may be
combined (using OR) to set the required value. For example, to set search and
read item, you would enter PERMISSIONS_SEARCH|PERMISSIONS_READ.
Version information
At Enterprise Vault 8.0, this property is superceded by the
IArchive3::SecurityDescriptor property.
See “IArchive3 :: SecurityDescriptor” on page 155.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER newVal is invalid, or the object is

already populated.
Example
Creating a Security Descriptor

char aszPrompt[MAX_INPUT_BUFFER];
wcout << L"Domain\\Account: " << flush;
cin.getline(aszPrompt, MAX_INPUT);
// Create Security Identifier from Domain and Account

CSid Sid;
if (!Sid.LoadAccount(aszPrompt))
{
return HRESULT_FROM_WIN32(GetLastError());
}
// Create ACE (access-control entry)

CDacl Dacl;
if (!Dacl.AddAllowedAce(Sid, PERMISSIONS_READ_WRITE_DELETE))
{
return HRESULT_FROM_WIN32(GetLastError());
}
// Set information in a DACL (discretionary access-control list)

CSecurityDesc SecurityDesc;
SecurityDesc.SetDacl(Dacl);
// Convert security descriptor to self-relative format

SecurityDesc.MakeSelfRelative();
// Copy security descriptor to a byte array

UINT SecurityDescLength = SecurityDesc.GetLength();
const SECURITY_DESCRIPTOR *pSecurityDesc =
SecurityDesc.GetPSECURITY_DESCRIPTOR();
CComSafeArray<BYTE> SecurityDescSafeArrayOfBytes;
hr = SecurityDescSafeArrayOfBytes.Add(SecurityDescLength,
(BYTE*)pSecurityDesc);
VARTYPE vt = SecurityDescSafeArrayOfBytes.GetType();
vt = vt | VT_ARRAY;
SecurityDescriptor->vt = vt;
SecurityDescriptor->parray = SecurityDescSafeArrayOfBytes.Detach();
IArchive :: ComplianceDevice
This property tells the caller whether the archive resides on a device capable of
setting compliance periods.
Syntax
HRESULT ComplianceDevice([out, retval] VARIANT_BOOL* pVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which will

contain the current value.
Remarks
If the archive is on a compliance device then TRUE is returned, otherwise FALSE
is returned.
Get must be called before accessing this property, otherwise an error will result.
Return value
S_OK Success.

been populated.

Storage services are not running.

retried later.
Example
arch.VaultStoreId =
arch.Get();

IArchive :: ItemCount
This property tells the caller how many items are currently held in the archive.
Syntax
HRESULT ItemCount([out,retval] VARIANT* pVal)
Parameters
[out,retval] VARIANT* pVal Pointer to a VARIANT that will contain the

current number of items in the archive.
Remarks
This property can only be used after Get or Create have been called.
The type of the variant will be unsigned long, for example, vt= VT_UI4.
Return value
S_OK Success.

been populated.


retried later.
Example
arch.VaultStoreId =
arch.Get();


;
IArchive :: Create
IArchive :: Create
This method is used to create an archive.
Syntax
HRESULT Create(void)
Remarks
To create an archive the calling application must be in a role that includes the
operation, ‘{DIR} Can manage Enterprise Vault Stores’. By default, the
Enterprise Vault Storage Administrator and Power Administrator roles include
this operation.
Before calling this method, the following properties must be set:
■ VaultStoreId
■ Name
■ IndexUrgency
■ ConvertedContent
■ ExpireItems
■ IndexLevel
The following combination of ConvertedContent and IndexUrgency values are
not permitted:
■ CONVERTED_CONTENT_STORED and
INDEX_ITEMS_DEFER_INDEFINITELY
■ CONVERTED_CONTENT_ON_DEMAND and INDEX_ITEM_IMMEDIATELY
If the archive is created successfully, the Id property will be populated with the
archive Id from the Enterprise Vault Directory.
When an archive is created, it is always created as an Enterprise Vault shared
archive.
See “IArchive3 :: Type” on page 160.
Return value
S_OK Success.
IArchive :: Create
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One or more of the mandatory

properties have not been set, an
invalid combination of properties
has been set, or the object is already
populated.


retried later.
CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller not in a role that includes the

operation, ‘{DIR} Can manage
Enterprise Vault Stores’. (The default
Enterprise Vault Storage
Administrator and Power
Administrator roles include this
operation).
Example
C++
archiveName = L”XYZRM_”;
archiveName += username;
archive->put_Name(archiveName);
archive->put_Description(CComBSTR(L“XYZ RM application archive”));
archive->put_VaultStoreId(CComBSTR(L“181E669473B52E64384C9A7D9EACA0
E7E1210000evsite”));
archive->put_ExpireItems(EXPIRE_ITEMS);
archive->put_IndexLevel(INDEX_LEVEL_FULL);
archive->put_ConvertedContent(CONVERTED_CONTENT_STORED);
archive->put_IndexUrgency(INDEX_ITEMS_IMMEDIATELY);
archive->Create();
archive->get_Id(&archiveId); // Remember the assigned Id for future
insertions
C#
archive.Name = ”XYZRM_” + userName;
archive.Description = “XYZ RM application archive”;
archive.VaultStoreId =
“181E669473B52E64384C9A7D9EACA0E7E1210000evsite”;
archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;
archive.IndexLevel = EV_STG_API_INDEX_LEVEL.INDEX_LEVEL_FULL;
IArchive :: Create
archive.ConvertedContent =
EV_STG_API_CONVERTED_CONTENT.CONVERTED_CONTENT_STORED;
archive.IndexUrgency
=EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_IMMEDIATELY;
archive.Create();
archiveId = archive.Id; // Remember the assigned Id for future
insertions
IArchive :: Get
IArchive :: Get
This method is used to retrieve information about an archive.
Syntax
HRESULT Get(void)
Remarks
The Get method tells the Content Management API to retrieve archive details
from the store, populating the properties of the object. Before calling this
method, the ArchiveId must be set.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The archive does not exist.


sufficient resources to complete
the request. The request should
be retried later.
Example
arch.VaultStoreId =
arch.Get();

IArchive2 :: Type
IArchive2 :: Type
This property identifies the type of the archive, for example, Exchange Server
mailbox archive, FSA archive, SharePoint archive, and so on.
Syntax
HRESULT Type([out, retval] EV_STG_API_ARCHIVE_TYPE* pVal);
Parameters
[out, retval] EV_STG_API_ARCHIVE_TYPE* pVal Pointer to an

EV_STG_API_ARCHIVE_TYPE that
contains the current value.
Remarks
Version information
At Enterprise Vault 8.0, this property is superceded by the IArchive3::Type
property.
See “IArchive3 :: Type” on page 160.
Return value
S_OK Success

IArchive2 :: Status
IArchive2 :: Status
This property indicates the status of the archive, that is, whether it can be
accessed.
Syntax
HRESULT Status([out, retval] EV_STG_API_STATUS* pVal);
Parameters
[out, retval] EV_STG_API_STATUS* pVal Pointer to an EV_STG_API_STATUS that

Remarks
EV_STG_API_STATUS enumeration indicates the status of the archive. See
“EV_STG_API_STATUS enumeration” on page 67.
Return value
S_OK Success
Example
IArchive2 arch2 = cmAPI.Archive2;
arch2.VaultStoreId =
arch2.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch2.Get();
EV_STG_API_STATUS evStatus = arch2.Status;
if (evStatus == EV_STG_API_STATUS. STS_AVAILABLE)

{
//store some items
IArchive2 :: HasFolders
IArchive2 :: HasFolders
This property indicates whether the archive is flat or contains a folder structure.
Syntax
HRESULT HasFolders([out, retval] VARIANT_BOOL* pVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL that contains the

current value.
Remarks
In Enterprise Vault some types of archive, such as shared or journal archives,
cannot contain folders.
Return value
S_OK Success
Example
bool hasFolders = arch2.HasFolders;
if (hasFolders == true)
{
//do something
IArchive2 :: Full
IArchive2 :: Full
This property indicates whether the archive is full.
Syntax
HRESULT Full([out, retval] VARIANT_BOOL* pVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL that contains the

current value.
Remarks
If the archive is full, no more items can be stored in it.
Return value
S_OK Success
Example
bool full = arch2.Full;
if (!full)
{
//store some items
IArchive2 :: DirectoryDNSAlias
IArchive2 :: DirectoryDNSAlias
This property contains the DNS Alias created for the Enterprise Vault Site.
Syntax
Parameters
[out, retval] BSTR* pVal Pointer to a string containing the current DNS alias for
the Enterprise Vault Site.
Remarks
When configuring Enterprise Vault, a DNS alias is assigned to the IP address of
the computer that hosts the primary Enterprise Vault Directory Service for the
Enterprise Vault Site.
Return value
S_OK Success
Example
arch.VaultStoreId =
string dnsAlias = arch2.DirectoryDNSAlias;
IArchive3 :: SecurityDescriptor
This property contains the self-relative security descriptor associated with an
existing archive, or to be used when creating an archive. This property
represents the manually set permissions of the archive, which are displayed on
the Permissions tab of the archive properties dialog in the Enterprise Vault
We recommend that you use the SecurityDescriptorString property to retrieve
and set the security descriptor from applications.
See “IArchive3 :: SecurityDescriptorString” on page 157.
Syntax
HRESULT SecurityDescriptor([out, retval] VARIANT* pVal);
HRESULT SecurityDescriptor([in] VARIANT newVal);
Parameters
[out, retval] VARIANT pVal Pointer to a VARIANT structure that will

hold the returned security descriptor value.
[in] VARIANT newVal New value of the security descriptor.
Remarks
If the type of the variant is VT_ARRAY, then the variant is a byte array
containing the SECURITY_DESCRIPTOR for the user account that will be given
access to the archive.
If the type of the variant is VT_EMPTY then the security descriptor is set to
default (that is, the user creating the archive has full access to the archive).
If the type of the variant is VT_NULL, then the archive is created without any
permissions.
descriptor permissions for an archive. The values are logically OR'd to get the
combined permissions.
See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.
Any attempt to modify the security descriptor of an existing archive will result
in an error.
Return value
S_OK Success.

Example
C++
This example illustrates how to fetch the SecurityDescriptor property value.
CComPtr<IArchive> pArchive;
// Get an instance of an IArchive3 object to populate

pCmAPI->get_Archive(&pArchive);
CComQIPtr<IArchive3> pArchive3(pArchive);
if (pArchive3 != NULL)
{
pArchive3->put_Id(CComBSTR(L"240A579483C52B89384A9D7D9EACA0E7E
9350000evsite");
pArchive3->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7
D9EACA0E7E1210000evsite"));
// Retrieve Archive information

//
pArchive3->Get();
// Fetch the SecurityDescriptor property value associated

with archive
//
CComVariant varSecurityDescriptor;
pArchive3->get_SecurityDescriptor(&varSecurityDescriptor);
}
IArchive3 :: SecurityDescriptorString
This property contains the security descriptor string associated with an existing
archive, or to be used when creating an archive. This property represents the
manually set permissions of the archive, which are displayed on the
Permissions tab of the archive properties dialog in the Enterprise Vault
Syntax
HRESULT SecurityDescriptorString ([in] BSTR newVal);
HRESULT SecurityDescriptorString([out, retval] BSTR* pVal);
Parameters
[in] BSTR newVal The security descriptor value formatted as a

text string which conforms to the Security
Descriptor string format.
[out, retval] BSTR* pVal Pointer to a string that will hold the
returned security descriptor value.
Remarks
If specified, this property must be set before calling the Create archive method.
The value of the SecurityDescriptorString property must conform to the MSDN
Security Descriptor String Format. For example,
"O:AOG:DAD:(A;;RPWPCCDCLCSWRCWDWOGA;;;S-1-0-0)".
For information on how to create Security Descriptor strings, see the MSDN
Security Descriptor String Format article:
http://msdn.microsoft.com/en-us/library/aa379570.aspx
The following permissions will be applied to the archive being created based on
the supplied SecurityDescriptorString BSTR property values:
■ If the supplied BSTR value is NULL, then the archive is created without any
permissions.
■ If the supplied BSTR value is an empty (zero length) string, then the user
creating the archive is given full access to the archive.
Security Descriptor strings using C++

The Microsoft SDK includes the functions
ConvertStringSecurityDescriptorToSecurityDescriptor and
ConvertSecurityDescriptorToStringSecurityDescriptor that can be used for
converting a string format security descriptor into a valid
SECURITY_DESCRIPTOR structure and vice-versa.
In addition, the ATL Library includes CSecurityDesc class with FromString
method, which converts a string-format security descriptor into a valid,
functional security descriptor, and a ToString method, which converts a
security descriptor to a string format.
Security Descriptor strings using .NET managed code

String type and StringBuilder class are available for constructing the
SecurityDescriptorString property values.
In addition, the ConvertStringSecurityDescriptorToSecurityDescriptor and
ConvertSecurityDescriptorToStringSecurityDescriptor functions are available
as described in “Security Descriptor strings using C++”.
Return value
S_OK Success.

Examples
Example 1
The following security descriptor string indicates a user who has been granted
full permissions access (Read+Write+Delete) to an archive:
“D:(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-201182662-6419)”
This example shows the value associated with the Manual security descriptor
setting for the archive to which the user has full permissions access.
Example 2
This example includes the access described in “Example 1”, and in addition a
group has been granted full permissions access ( Read+Write+Delete) on the
archive:
“D:(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-2011822662-6419)
(A;;CCDCLCSW;;;S-1-5-21-2986758783-3322231649-3643854221-1255)”
Example 3
This example includes the access described in “Example 1”, and in addition a
group have been denied full permissions access (Read+Write+Delete) on the
archive:
“D:(D;;CCDCLCSW;;;S-1-5-21-2986758783-3322231649-3643854221-1255)
(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-2011822662-6419)”
IArchive3 :: Type
IArchive3 :: Type
This property identifies the type of the archive, for example, Exchange Server
mailbox archive, FSA archive, SharePoint archive, and so on.
Syntax
HRESULT Type([in] EV_STG_API_ARCHIVE_TYPE newVal);
HRESULT Type([out, retval] EV_STG_API_ARCHIVE_TYPE* pVal);
Parameters
[in] EV_STG_API_ARCHIVE_TYPE newVal The new value of Type.
[out, retval] EV_STG_API_ARCHIVE_TYPE* pVal Pointer to an

EV_STG_API_ARCHIVE_TYPE that
Remarks
Currently, newVal can only be set to ARCHIVE_TYPE_SHARED; any other
value is treated as invalid.
The value of the property IArchive::HasFolders will be implied from the Type
property value. Table 4-20 shows the implied values. False means that the
archive is flat. True means that the archive is structured.
Table 4-20 Structure of archive types
EV_STG_API_ARCHIVE_TYPE value HasFolders property value
ARCHIVE_TYPE_SHARED False
ARCHIVE_TYPE_EXCHANGE_MAILBOX True
ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER True
ARCHIVE_TYPE_EXCHANGE_JOURNAL False
ARCHIVE_TYPE_FILE_SYSTEM True
IArchive3 :: Type
Table 4-20 Structure of archive types
EV_STG_API_ARCHIVE_TYPE value HasFolders property value
ARCHIVE_TYPE_SHAREPOINT True
ARCHIVE_TYPE_DOMINO_MAILBOX False
ARCHIVE_TYPE_DOMINO_JOURNAL False
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid,

Example
[out]
arch3.Get();
EV_STG_API_ARCHIVE_TYPE evType = arch3.Type;
if (evType == EV_STG_API_ARCHIVE_TYPE.
ARCHIVE_TYPE_EXCHANGE_MAILBOX)
{
// do something
[in]
arch3.Name = “my new archive”;

arch3.Description = “my new archive description”;
arch3.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS;
arch3.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.
CONVERTED_CONTENT_STORED;
arch3.IndexUrgency = EV_STG_API_INDEX_URGENCY.
INDEX_ITEMS_IMMEDIATELY;
arch3.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;
arch3.Type = EV_STG_API_ARCHIVE_TYPE. ARCHIVE_TYPE_SHARED;
arch.Create();
Items object
Items object
■ IItems
The IItems interface inherits the properties and methods of the ICollectionBase
interface.
This interface enables external applications to enumerate the items in an
archive in order to retrieve details of each item from the Enterprise Vault
Directory.
Syntax
interface IItems : ICollectionBase
Member summary
Table 4-21 IItems properties
ArchiveId Read/Write The ID of the archive holding the items to

enumerate.
StartSequenceNum Read/Write The starting item sequence number to be used

when fetching a collection of item records.
OrderBy Read/Write The index sequence number ordering to be

used when enumerating items in the collection.
Count Read only Number of items in the collection.

the collection.
Item Read only Instance of the item at the zero-based index

Maximum Read/Write Maximum number of items in the collection.

Items object
More Read only Whether or not there were more items than
Maximum.
Method Description
Remarks
Calling applications must have at least Read access to the target archive.
The following properties are populated for each Item object in the collection. If
additional properties are required for an Item, the Get method should be called
specifying the required detail level.
IItem::Id
IItem::ArchiveId
IArchiveMetaData2::SequenceNum
IArchiveMetaData2::CurrentLocation
IArchiveMetaData2::CurrentFolderId
IArchiveMetaData::RetentionCategory
IItem::CopyOptions
IItem::DeletionLevel
IArchvieMetaData::ComplianceDevice
IArchiveMetaData::OverrideOnholdRetCat
Populating these properties avoids the need to call Get to determine the source
item information before calling CopyTo or MoveTo.
Note that the items collection will not include items that have been soft deleted
from the archive, if this has been enabled. The soft delete functionality is
enabled using the Enterprise Vault Administration Console; by selecting the
archive setting, Enable recovery of user deleted items, in Site properties.
Items object
Version information
■ This interface requires Enterprise Vault 8.0 or later.
Example
C++
This example creates an Items collection object, enumerates the required items
in the target archive and retrieves details of the items from the Enterprise Vault
Directory.
// Get empty items collection for populating
CComPtr<IContentManagementAPI3> spCMAPI;
spCMAPI.CreateInstance(CComBSTR(L"EnterpriseVault.ContentManagement
API"));
VARIANT_BOOL vbMore = VARIANT_TRUE;
ULONGLONG LastSequenceNum;
// Get an Items object for enumeration

spCMapi->get_Items(&spUnk);
CComQIPtr<IItems> spItems(spUnk);
// Populate the Items collection

spItems->put_ArchiveId (CComBSTR("1C51F75FFC26EC840A012AD322C579
3AF1e10000LAGUNA4.REA.RND.SYM.COM"));
spItems->put_StartSequenceNum (1) // [Min = 1]
spItems->put_Maximum(500) // [Max = 10,000] (Comment: Ref
ICollectionBase :: Maximum)
spItems->put_OrderBy(ITEMS_ORDERBY_ASC) // Ascending
do
{
CComPtr<IItem> spItem;
// Fetch a batch of items

spItems->Get();
// Process each item in collection

long lCount = 0;
spItems->get_Count(&lCount);
// Iterative loop
for(long idx = 0; idx < lCount; ++idx)
{
//Fetch item
Items object
spItems->get_Item(idx, &spUnk);
CComQIPtr<IItem> spItem(spUnk);
//Do something
spItem->Get(DETAIL_LEVEL_ITEM_CONTENT |
DETAIL_LEVEL_ARCHIVE_METADATA);
...
// Remember the last item seq. no.

CComPtr<IArchiveMetaData> spAMD;
spItem->get_ArchiveMetaData(&spAMD);
CComQIPtr<IArchiveMetaData2> spAMD2(spAMD);
spAMD2->get_SequenceNum(&LastSequenceNum)
}
vbMore = spItems->More();
// Fetch next chunk of items

if (vbMore)
{
// Reset start sequence no to last itemís sequence no.
(of previous collection) + 1
spItems->put_StartSequenceNum = LastSequenceNum+1;
}
} while (vbMore)
See also
■ “Enumerating vault stores, archives and items” on page 53.
■ “ICollectionBase : IDispatch” on page 344.
■ “Item object” on page 172.
■ “ArchiveMetaData object” on page 237.
■ “Content object” on page 220.
IItems :: ArchiveId
IItems :: ArchiveId
This property identifies the archive in which the required items are stored.
Syntax
HRESULT ArchiveId([in] BSTR newVal);
HRESULT ArchiveId([out, retval] BSTR* pVal);
Parameters
[in] BSTR newVal The ID of the target archive.

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the ID of
the current archive.
Remarks
Note that the value used can be either the Archive ID or the ID of a folder in the
archive, as this identifies both the archive and the archive folder.
The Archive ID is displayed in the properties of the archive in the
The following gives an example value of the ArchiveId property:
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is

not a valid archive identity.
Example
IContentManagementAPI4 cmAPI4 = new
(IContentManagementAPI4)ContentManagementAPIClass();
IItems items = cmAPI4.Items;

items.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
items.StartSequenceNum = 1000;
IItems :: ArchiveId
items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC;
items.Get();
IItems :: StartSequenceNum
This property specifies the Index Sequence Number (ISN) of the first item in the
items collection.
Syntax
HRESULT StartSequenceNum([in] ULONGLONG newValue);
HRESULT StartSequenceNum([out,retval] ULONGLONG* pVal);
Parameters
[in] ULONGLONG newValue Index sequence number of the first item in the
required items collection.
[out,retval] ULONGLONG* pVal Integer that will receive the index sequence number
of the first item in the collection.
Remarks
The Index Sequence Number of an archived item is specified in the
IArchiveMetaData2::SequenceNum property. This property can be used to
determine the start Index Sequence Number for the collection enumeration.
See “IArchiveMetaData2 :: SequenceNum” on page 273.
Enterprise Vault item sequence numbers are not always consecutive, as items
may have expired or been deleted.
The default value for this property is 1.
Requirements
Windows Server 2003 supports ULONGLONG types with OLE Automation.
However ULONGLONG types are not supported on Windows Server 2000.
.NET managed code and C++ support ULONGLONG types, but these types are
not supported by Visual Basic Script.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is not a

valid archive identity.
Example

items.Get();
IItems :: OrderBy
IItems :: OrderBy
This property is used to specify the index sequence number order to be used
when enumerating items in the collection.
Syntax
HRESULT OrderBy([in] EV_API_ITEMS_ORDERBY newVal);
HRESULT OrderBy[out,retval] EV_API_ITEMS_ORDERBY* pVal);
Parameters
[in] EV_API_ITEMS_ORDERBY newVal The index sequence number order

to use when enumerating the item
collection.
[out,retval] EV_API_ITEMS_ORDERBY* pVal The index sequence number order

used when enumerating the
current item collection.
Remarks
The default is to order by ascending index sequence number
(ITEMS_ORDERBY_ASC).
See “EV_API_ITEMS_ORDERBY enumeration” on page 58.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is invalid.
Example

IItems :: OrderBy
items.Get();
Item object
Item object
■ IItem
IID is {D96AF252-8216-4907-AF6B-7DBC93028694}
■ IItem2
IID is {9F6D061C-A8E9-4937-8592-762F23B037CA}
■ IItem3
IID is {E5C7F710-36AD-4e24-B00A-E3D709FF76CD}
This object enables the storage and management of items in Enterprise Vault
archives.
The IItem2 interface provides an additional property to help determine why an
item no longer exists in an archive.
The IItem3 interface provides an additional method to recover an item that has
been soft-deleted.
Syntax
interface IItem : IDispatch
Member summary
Table 4-24 IItem properties
ArchiveId Read/Write Archive ID of the archive containing the required

item.
Id Read/Write Identifier of the item in the archive.
Content Read only Instance of a Content object that provides access to

the data that is to be archived, or has been archived.
ArchiveMetaData Read only Pointer to an IArchiveMetaData object that provides

details of how the item will be, or has been archived.
BrowserViewURL Read only URL for viewing the archived item.
DefaultMSGFormat Read/Write Sets the format (ANSI or Unicode) for the item being
retrieved, where the original format has not been
stored.
Item object
Table 4-24 IItem properties
Holds Read only Enables the enumeration of legal holds placed on

the archived item.
NativeItemURL Read only URL for downloading the archived item. The item is
opened in the default application for the type of
item.
DeletionLevel Read/Write Indicates whether deleting the item deletes it

completely (hard delete) or moved to the Enterprise
Vault "dumpster" (soft delete).
CopyOptions Read/Write Identifies source item property values to be copied

to the destination item.
Table 4-25 IItem methods
Methods Description
Get Retrieves archived item, or information about an archived item.
Delete Delete item from archive.
CanBeDeleted Check if archived item can be deleted.
CopyTo Copy archived item to another location.
MoveTo Move archived item to another location.
Insert Stores item in an archive.
Table 4-26 IItem2 property
Property Read/write Description
DeletionReason Read only If the item no longer exists in the archive, this
property can be used to discover why the item was
deleted.
Item object
Table 4-27 IItem3 method
Property Description
Undelete Recover an item that has been soft-deleted.
Remarks
After the Create or Get method has been called on this interface, the current
interface pointer must be released and a new one obtained before calling either
of these methods again.
Version information
■ CopyOptions property requires Enterprise Vault 8.0.
■ IItem2 interface requires Enterprise Vault 8.0 SP3.
■ IItem3 interface requires Enterprise Vault 9.0.
Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);
IItem :: ArchiveId
IItem :: ArchiveId
This property identifies the archive in which the item is stored, or to be stored.
Syntax
Parameters
[in] BSTR newVal The Archive ID of the archive.

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the ID of
the current archive.
Remarks
Note that the value used can be either the Archive ID or the ID of a folder in the
archive, as this identifies both the archive and the archive folder.
This property must be set before calling Get.
An error will result if an attempt is made to change the value of an existing item.
This value is displayed in the properties of the archive in the Administration
Console.
The following gives an example value of the ArchiveId property:
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, or newVal is not a

valid Archive Id.
IItem :: ArchiveId
Examples
C#
IItem itm = cmAPI.Item;
itm.ArchiveId = "“181E669473B52E64384C9A7D9EACA0E7E1110000evsite";
itm.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7
9f3298dc8a1e60";
IItem :: Id
IItem :: Id
This property identifies the item in the archive.
Syntax
Parameters
[in] BSTR newVal Id of stored item.
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the

current value of this item’s ID.
Remarks
This property sets or retrieves the identifier of the item in the archive. It is only
populated once an item has been stored in an archive, and must be set before
calling the Get method.
It should not be set before calling an Insert method, as this will result in an
error.
Any attempt to change the value of an existing item will result in an error.
This property can hold the item’s Transaction ID or Saveset ID.
Version information
Enterprise Vault 7.0 or later is required to support a Transaction ID value for
this property.
Return value
S_OK Success.
S_FALSE Success. The default value (NULL) is

returned.
IItem :: Id
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL,

or newVal is not a valid Saveset ID or
Transaction ID,
or an attempt has been made to set the
Saveset ID of an existing item.
Examples
C++
CComBSTR bstr(L“161000000000000~200501051649270000~0~9039eb282e3d4
083b79f3298dc8a1e60“)
item->put_Id(bstr);
//DO Get and check the id
bstr.Clear();
item->get_Id(&bstr);
C#
item.Id = “161000000000000~200501051649270000~0~9039eb282e3d4083b7
9f3298dc8a1e60“;
itm.Archive.Id = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite";
IItem :: Content
IItem :: Content
This property returns an instance of a Content object that gives access to the
data that is to be archived, or has been archived (depending on when it is used).
The interface pointer to IContent is read only, however, the methods and
properties exposed by IContent allow the content, including the item data, to be
modified.
Syntax
HRESULT Content([out, retval] IContent** pVal);
Parameters
[out,retval] IContent** pVal Instance of a Content object.
Remarks
The IContent interface makes the following properties available. Each of these is
described in more detail in the relevant section.
■ Title
■ OriginalLocation
■ FileExtension
■ MimeFormat
■ CreatedDate
■ ModifiedDate
■ Data
■ OriginalSize
■ Author
See “Content object” on page 220.
Return value
S_OK Success.
IItem :: Content
Examples
C++
IContent* pContent = NULL;
item->get_Content(&pContent);
C#
item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);
IContent content= item.Content;
LogContentProperties(content, item.Id);
IItem :: ArchiveMetaData
This property returns a pointer to an IArchiveMetaData interface that provides
details of how the item will be or has been archived.
The interface pointer to IArchiveMetaData is read only. However, the methods
and properties exposed by IArchiveMetaData allow the metadata to be modified.
Syntax
HRESULT ArchiveMetaData([out, retval] IArchiveMetaData** pVal);
Parameters
[out,retval] IArchiveMetaData** pVal Pointer to an IArchiveMetaData pointer.
Remarks
The IArchiveMetaData interface makes available properties that hold
information about the item, such as the assigned Retention Category and the
date and time when the item was archived. Each of these is described in more
detail in the relevant section.
See “ArchiveMetaData object” on page 237.
Return value
S_OK Success.
Example
item.Get((int)EV_STG_API_ITEM_DETAIL.
IArchiveMetaData amd = item.ArchiveMetaData;

See also
■ See “ArchiveMetaData object” on page 237.
IItem :: BrowserViewURL
This property returns a string containing the URL that should be entered into a
web browser (for example) to view the item.
Syntax
HRESULT BrowserViewURL([out,retval] BSTR* pVal)
Parameters
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the URL.
Remarks
This property will return an error if the archive Id and item Id have not been set
previously.
The URL returned includes the IIS virtual directory for the Enterprise Vault
Web access application, but not a specific Web server name. Enterprise Vault
dynamically generates the full URL as needed, with the appropriate server name
for each caller.
This form of URL is compatible with Enterprise Vault Building Blocks architec-
ture.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the Archive Id or Saveset Id

have not been set or the Saveset Id is
invalid.

Service is not running.

request. The request should be retried
later.
Examples
C++
CComBSTR bstr;
item->put_Id(L”161000000000000~200501051649270000~0~9039eb282e3d408
3b79f3298dc8a1e60“);
item->put_ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsi
te“);
item->get_BrowserViewURL(&bstr);
C#
item.Id = ”161000000000000~200501051649270000~0~9039eb282e3d4
083b79f3298dc8a1e60“;
Item.arhiveId = “181E669473B52E64384C9A7D9EACA0E7E1110000evsite“;
String url = Item.BrowserViewURL;

IItem :: DefaultMSGFormat
This property allows the caller to set the format as ANSI or Unicode for the item
being retrieved, where the original format has not been stored with the saveset.
The property is optional.
Syntax
HRESULT DefaultMSGFormat([in] BSTR newVal);
HRESULT DefaultMSGFormat([out,retval] BSTR* pVal);
Parameters
[in] BSTR newVal New value to be set.

See “Remarks”.
[out,retval] BSTR* pVal Pointer to a BSTR that will hold the current value.
Remarks
The following values can be assigned to newVal:
“N” Perform no conversion.
"U" Return as Unicode.
"A:nnnn" Return as ANSI code page. For example, "A:932" return as Japanese ANSI.
DefaultMSGFormat allows the caller to set the default format as ANSI or

Unicode for the item being retrieved, where the original format has not been
stored with the saveset.
From Enterprise Vault 6.0 SP1, items are stored in Enterprise Vault as Unicode.
In addition, items archived using File System Archiving, SharePoint archiving,
or API methods, store details of the original format with the saveset. If details of
the original format were stored, then the item will always be returned in its
original format, irrespective of the value of DefaultMSGFormat.
However, items stored using Exchange Server archiving tasks (or PST
migration) do not record details of the original format. The value set for
DefaultMSGFormat, will be applied to any such items that do not have the
original format recorded.
If no value is specified for DefaultMSGFormat, then no conversion is performed
and the archive format is used. On a system with messages archived using an
earlier release than Enterprise Vault 6.0 SP1, this means that items archived
prior to Enterprise Vault 6.0 SP1 are returned in ANSI format, and items
archived since the upgrade to Enterprise Vault 6.0 SP1 are returned in Unicode
format.
If a value has not been explicitly set, then this property will return null.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an

attempt has been made to change an
existing value.
Examples
C++
item->put_DefaultMSGFormat(L“U“);
//do something, put ids etc

Item->Get(DETAIL_LEVEL_ALL);
Itm->put_DefaultMSGFormat(L”N”); // ERROR
C#
itm.DefaultMSGFomart = “U”;
//do something – set ids etc

Itm.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ALL));
Itm.=defaultMSGFormat = “N”; //ERROR
IItem :: Holds
IItem :: Holds
This property gives access to the set of holds currently placed on the item. The
property is read only. For a description of a hold, see “About Legal Hold” on
page 313.
Syntax
HRESULT Holds([out,retval] IHolds** pVal);
Parameters
[out,retval] IHolds** pVal Pointer to an IHolds pointer which will contain the
current IHolds pointer.
Remarks
This property is a collection of IHold pointers, each of which defines a hold
placed on the particular item.
The caller must have called the IItem.Get method with the
DETAIL_LEVEL_HOLD_DATA flag set prior to calling this property.
See “IItem :: Get” on page 200.
This property is a collection of IHold pointers, each of which defines a hold
placed on the particular item.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or could not

find the HOLDS collection.
Example
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA);
IHolds holds = Item.Holds;

IItem :: NativeItemURL
The URL downloads the item that was archived and attempts to open the item
using the default application for the type of the item.
Syntax
HRESULT NativeItemURL([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal A pointer to a BSTR that will contain the current value.
Remarks
There will be an error if either the item Id or the archive Id have not been set
before using this property.
for each caller.
ture.
Return Value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,

or either the Item Id or Archive Id
have not been set.
Examples
C++
CComBSTR bstr;
item->get_NativeItemURL(&bstr); //ERROR
item->put_Id(L”200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e6
0”)
item->put_ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evsit
e”);
item->get_NativeItemURL(&bstr); //SUCCESS
C#
string url = item.NativeItemURL; //ERROR
item.Id(“200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”);
item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
string url = item.NativeItemURL; //SUCCESS
IItem :: DeletionLevel
This property indicates the type of delete to be used for the archived item. Items
can be deleted completely (hard delete), or moved to the Enterprise Vault
"dumpster" area (soft delete).
Syntax
HRESULT DeletionLevel([in] EV_API_DELETION_LEVEL newVal);
HRESULT DeletionLevel([out,retval] EV_API_DELETION_LEVEL* pVal);
Parameters
[in] EV_API_DELETION_LEVEL newVal New EV_API_DELETION_LEVEL

value.
[out,retval] EV_API_DELETION_LEVEL* pVal Current EV_API_DELETION_LEVEL

value.
Remarks
EV_API_DELETION_LEVEL is an enumerated value.
See “EV_API_DELETION_LEVEL enumeration” on page 58.
The default value for this property is DELETION_LEVEL_SOFT_DELETE. For a
period of time after deletion (configured by the administrator), users can
recover a soft-deleted item.
In the Enterprise Vault Administration Console, in the Site Properties pages, the
administrator can enable the recovery of deleted items and specify how long
soft-deleted items are to be kept.
The Item Undelete method can be used to recover a soft-deleted item.
See “IItem3 :: Undelete” on page 217
Version information
■ The ability to retrieve deleted items in Enterprise Vault is available from
Enterprise Vault 2007.
Return Value
S_OK Success.

or newVal is invalid.
Example
[in]
item.DeletionLevel = EV_API_DELETION_LEVEL.
DELETION_LEVEL_SOFT_DELETE;
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
item.Insert();
[out]
DETAIL_LEVEL_ITEM_PROPERTIES);
EV_API_DELETION_LEVEL evDL = item.DeletionLevel;

IItem :: CopyOptions
This property identifies the source item property values to be copied to the
destination item.
Syntax
HRESULT CopyOptions([in] EV_STG_API_ITEM_COPYOPTIONS newVal);
HRESULT CopyOptions([out,retval] EV_STG_API_ITEM_COPYOPTIONS*
pVal);
Parameters
[in] EV_STG_API_ITEM_COPYOPTIONS newVal New bit mask value specifying

which item elements are to be
copied from the source item
equivalents.
This value can be one or more
of the enumerated values. Use
more than one by joining them
with ‘OR'.
[out,retval] EV_STG_API_ITEM_COPYOPTIONS* pVal Current bit mask value.
Remarks
The calling application sets the CopyOptions property on the destination item
object that is supplied in calls to the CopyTo or MoveTo methods.
The value of CopyOptions can be one or more of the
EV_STG_API_ITEM_COPYOPTIONS enumeration values. The default value is
ITEM_COPYOPTIONS_ARCHIVEMETADATA. If this is set, then the values of
the following ArchiveMetaData properties on the source item will be copied to
the equivalent properties on the destination item, unless explicitly provided as
part of the CopyTo or MoveTo method call:
■ SimpleIndexMetaData
■ ArchivedDate
■ RetentionCategory
■ CurrentLocation
■ CurrentFolder
■ CustomIdentifier
■ CustomQualifier
■ CustomProperties
See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 64.
Specifying item property override values

Before calling CopyTo or MoveTo, item property values can be explicitly set on
the destination item object in order to override the behavior of the CopyOptions
property. Any specified override value will take precedence over the
CopyOptions property value setting.
For example, if the CopyOptions value is set to copy ArchiveMetaData
properties, ITEM_COPYOPTIONS_ARCHIVEMETADATA, from the source item,
but the caller wants the ArchivedDate property on the destination item to be the
current date and time (rather than copied from source), then the caller would set
the ArchivedDate property value on the destination item as the current date.
Table 4-28 indicates the expected behaviour when setting override values for
specific item properties with the CopyOptions enumeration value,
ITEM_COPYOPTIONS_ARCHIVEMETADATA.
Table 4-28 Effect of setting override item property values with

ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value
Item property Option Override Property value in copied item

selected value set on
destination
item
ArchivedDate Yes (Default) Yes Set to override value.

Set to current date/time if the override
value supplied as a null (VT_NULL)
variant property value.
No Yes As above.
Yes (Default) No Copied from source item.
No No Set to current date/time.
RetentionCategory Yes (Default) Yes Set to override value.

Set to the site default Retention Category
if override value specified as a zero
length string value.
No Yes As above.
Table 4-28 Effect of setting override item property values with

ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value
Item property Option Override Property value in copied item

selected value set on
destination
item
Yes (Default) No Copied from source item. 1
No No Set to the site default Retention

Category.
CustomIdentifier Yes (Default) Yes Set to override value. 2

CustomQualifier Set to zero value if override specified as
CustomProperties zero value.
No Yes As above.
Yes (Default) No Copied from source item.
No No Set to zero value.
CurrentLocation Yes (Default) Yes Set to override value.

CurrentFolderId
No Yes See “Which properties determine the

current archive folder” on page 267.
Yes (Default) No Copied from source item. 3
No No See “Which properties determine the

current archive folder” on page 267.
1.Preserving the source item's RetentionCategory value on the copied or moved item assumes that the source
and destination archives are associated with the same site.
2. FSA and SharePoint Archiving use these custom properties to hold information for restoring items, when
copying or moving items from one FSA or SharePoint archive to another. The property values should not be
changed for such items.
3.Where the source item is being copied or moved from a flat archive to a structured archive, the CurrentLo-
cation value on the destination item will be set to the value of OriginalLocation on the source item.
Return value
S_OK Success.

attempt has been made to set the
CopyOptions of an existing item,
or the value set is not within
enumeration.
Examples
Visual Basic Script example

In the following example the source item’s ArchiveMetaData values are
preserved on the destination item.
Dim ecmAPI
Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")
Dim oItem, oDestItem
' Establish the source item
Set oItem = ecmAPI.Item
' Establish the destination item
Set oDestItem = ecmAPI.Item
oDestItem.ArchiveId =
' Set the CopyOptions flags to set the copied item's TransactionId
' and ArchiveMetaData values
' from the source item (Ref EV_STG_API_ITEM_COPYOPTIONS)
oDestItem.CopyOptions = 3
oItem.CopyTo (oDestItem)
IItem :: Insert
IItem :: Insert
This method is used to store an item in an archive.
Syntax
HRESULT Insert(void);
Remarks
It is important to make sure that this interface pointer has not been used before
to perform an Insert or Get action.
The caller must have WRITE access permissions on the destination archive,
otherwise an error will occur. For structured archives, the caller must have write
access to the destination archive folder.
If an override value is specified for the ArchivedDate property, the calling
application must be in an Enterprise Vault role that includes the operation,
“{API} Can Use Extended API Features”. This operation is included in the default
Enterprise Vault Power Administrator and Storage Administrator roles.
The Insert method stores an item in the specified archive. Before calling Insert,
the following properties must be populated:
■ IItem :: ArchiveId
■ IContent :: Data
■ Either IContent :: FileExtension or IContent :: MIMEFormat. Enterprise
Vault uses the supplied extension or MIME type to enhance indexing and
storage functionality for content types such as Outlook messages. If you
assign any other values to an item, Enterprise Vault archives and indexes
the item as a file. Enterprise Vault provides enhanced indexing and storage
functionality for the following content types:
Content type File extension MIME format
Outlook messages .msg application/vnd.ms-outlook
SMTP messages .eml message/rfc822
When you call Insert, the IItem :: Id property must be empty.

After this method has been called, and assuming the operation was successful,
the Id property will be populated with the identifier of the item in the archive.
Calling this method on an Item that already contains an Id (that is, an item that
has already been stored) will cause an error condition.
IItem :: Insert
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One of the required property

values has not been set (see
“Remarks”),
or both of
IArchiveMetadata2::CurrentL
ocation and
IArchiveMetadata2::CurrentFo
lderId have been set but they
refer to different archive
folders,
or either
ocation and
IArchiveMetadata2::CurrentFo
lderId have been set and the
target archive is a flat archive,
or this item has previously
been used, in which case this
one must be destroyed and a
new one created.
CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault

Directory or Storage services
are not running.
CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently

busy or has insufficient
resource to complete the
insertion, or Enterprise Vault
is currently being backed up
and is not accepting insert
requests. This error indicates
that the caller should retry
later.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is

unknown or has been deleted,
or the selected retention
category is not known or has
been deleted.
CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The target archive is full or

exceeds its quota limit.
IItem :: Insert
CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have write

access to the target archive or
archive folder,
or the archive is in a read-only
state,
or an override value has been
specified for ArchivedDate,
but the caller is not in a role
that includes the operation,
“{API} Can Use Extended API
Features”. (The default
Administrator roles include
this operation).
CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID Item Id is not unique in the

target vault store.
CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to insert items

into a structured archive
containing multiple root
folders (for example, a public
folder archive).
Examples
C+ +
spItem.put->ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evs
ite”);
IContent* pContent = null;
spItem->get_Content(&pContent);
pContent->put_Title(L"new title");
pContent->put_FileExtension(L"msg");
pContent->put_Data(L“C:\\temp\\test.msg”);
spItem->Insert();
C#
item.Insert();
IItem :: Insert
See Also
“Content object” on page 220
IItem :: Get
IItem :: Get
This method is used to retrieve an archived item or information about an item.
Syntax
HRESULT Get([in] LONG DetailLevel);
Parameters
[in] LONG DetailLevel A bit-mask that specifies the item related data to retrieve.
This value can be one or more of the
EV_STG_API_ITEM_DETAIL enumerated values. Use more
than one by joining them with ‘or'.
See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.
Remarks
The item's ArchiveId and either its Id property or
IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier
properties must be set prior to calling this method.
When retrieving hold data only, the item's Id property must be used
(DetailLevel = DETAIL_LEVEL_HOLD_DATA).
The item's CustomIdentifier and CustomQualifier properties can only be used
when together they uniquely identify an item.
See “IIArchiveMetaData :: CustomIdentifier” on page 257.
EV_STG_API_ITEM_DETAIL indicates the data to retrieve for an item.
See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.
The caller can “bitwise OR” the bit masks together. For example, IItem.Get(255)
returns the item properties and the metadata.
If the soft delete feature has been enabled, items that have been soft deleted
from the archive are retrieved. The soft delete functionality is enabled using the
Enterprise Vault Administration Console; by selecting the archive setting,
Enable recovery of user deleted items, in Site properties.
To retrieve the item content, the caller must populate the IContent::Data
property with a file location on disk, or to an IStream or ILockbytes object that
has been created ready to receive the item content.
Note: If you specify a file, any existing content will be overwritten.

IItem :: Get
The Content Management API supports IStream and ILockBytes

implementations where the input data length provided by the Stat method is not
known.
See “IContent :: Data” on page 232.
When DETAIL_LEVEL__SYSTEM_INDEXDATA is requested, the “cont” property
is included in the properties returned. This is the HTML representation
(converted content) of the item or attachment. If the size of the item’s converted
content is larger than 5MB, then the converted content is not returned. Instead,
a content missing reason (“comr”) property is returned with the reason,
vmrVALUENOTOBTAINED (2).
This limit can be changed using the registry setting:
HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\MaxIndexDataHTMLContentKB
This registry setting is described in the Registry Values guide.
Return values
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer passed in is NULL,

or the item's Archive Id and
either its Id property, or
CustomIdentifier and
CustomQualifier properties,
have not been set.

or Storage services are not
running.

request. This error indicates
later.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is

unknown or has been deleted,
or the selected item is not
present or has been deleted.
IItem :: Get
CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have read

archive folder.
CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER More than one item identified

by combined CustomIdentifier
and CustomQualifier
properties.
Version information
■ Retrieving expanded distribution list information using the
DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA value of
EV_STG_API_ITEM_DETAIL enumeration is available in Enterprise Vault
6.0 SP4 and Enterprise Vault 7.0 SP2.
See “Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault
6.0 SP4” on page 33.
Note that this feature requires MSXML 3.0 or later.
■ When the enumerated value, DETAIL_LEVEL_ITEM_CONTENT, is included
as part of the input parameter for IItem::Get, the correct date and time is
now returned by IContent::ModifiedDate and IContent::CreatedDate. This is
fixed in Enterprise Vault 6.0 SP4 and Enterprise Vault 7.0 SP2, and later.
See “Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault
■ IArchiveMetaData::CustomIdentifier and
IArchiveMetaData::CustomQualifier require Enterprise Vault 8.0.
See “Enterprise Vault 8.0” on page 25.
Examples
Refer to Microsoft documentation for details and usage of IStorage and IStream.
C++
item->put_Id(
L” 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”);
item->put_ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000site“
);
IStorage* pStorage = NULL;
StgCreateStorageEx(NULL, STGM_READWRITE | STGM_CREATE, STGFMT_FILE,
0, NULL, 0, NULL, IID_IStorage,
reinterpret_cast<void**>(&pStorage));
IStream* pStream = NULL;
IItem :: Get
pStorage->CreateStream(„Test Stream“, STGM_READSWRITE |

STGM_CREATE, 0, 0, &pStream);
IContent* pContent = NULL;

item->get_Content(&pContent);
pContent->put_Data(pStream);
item->Get(DETAIL_LEVEL_ITEM_CONTENT);
//do something
pStream->Release();
pStream = NULL;
pStorage->Release();
pStorage = NULL;
pContent->Release();
pContent = NULL;
item->Release();
item = NULL;
C#
item.Id = ” 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
Item.ArchiveId = “181E669473B52E64384C9A7D9EACA0E7E1110000evsite“;
IContent content = null;

content = item.Content;
content.Data = "C:\\temp\\temp.msg";
item.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_CONTENT));
//do something
IItem :: Delete
IItem :: Delete
This method is used to delete an item from an archive.
Syntax
HRESULT Delete(void);
Remarks
Calling the Delete method will remove the item from its archive. The value of the
DeletionLevel property will determine whether a hard or soft delete is
performed.
Prior to calling this method, the application programmer must have set the
ArchiveId (to identify the archive containing the item), and the Id property to
identify the item within its container.
It cannot be called on an item whose ArchiveId and Id properties have not been
set, as this will cause an error.
The calling user must have the appropriate permissions to delete the item. It is
also possible that the server will reject the request because an item is “On Hold”
or cannot be removed for compliance reasons.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in,

or either the Archive Id or Item Id
have not been set.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or

has been deleted.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or

has insufficient resource to
complete the request. This error
indicates that the caller should retry
later.
IItem :: Delete
CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have delete

archive folder,
or the archive is in a read-only state.
CONTENTMANAGEMENTAPI_E_DELETION_BARRED The item cannot be deleted because

deletions are not permitted; the
item's Retention Category does not
permit deletion and the
IArchiveMetadata
OverrideOnHoldRetCat was not
selected, or the item is on legal hold.
Examples
C++
item->put_Archive_Id(L”181E669473B52E64384C9A7D9EACA0E7E1110000evsi
te”);
item->putId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evsite“);
item->Delete();
C#
object obj = item.CanBeDeleted;

int canBeDeleted = (int)obj;
if (obj == 0)
{
item.Delete();
}
IItem :: CanBeDeleted
This method determines if an item can be deleted from an archive.
Syntax
HRESULT CanBeDeleted([out,retval] VARIANT* CanDelete);
Parameters
[out,retval] VARIANT* CanDelete Pointer to a VARIANT containing the

current value.
Remarks
CanBeDeleted returns a value to indicate whether or not the item can be deleted.
For possible values, see “EV_STG_API_CAN_DELETE enumeration” on page 60.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER ANULL pointer has been passed in,

or
either the Item Id or Archive Id has
not been set.


has insufficient resource to complete
the request. This error indicates that
the caller should retry later.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or

has been deleted, or
the selected item is not present or
has been deleted.
CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have read access

to the target archive or archive
folder.
Example
object obj = item.CanBeDeleted;

int canBeDeleted = (int)obj;
if (obj == 0)
{
item.Delete();
}
IItem :: CopyTo
IItem :: CopyTo
This method is used to copy an item from one archive to another.
Syntax
HRESULT CopyTo([in] IItem* DestinationItem);
Parameters
[in] IItem* DestinationItem IItem interface pointer that represents the

destination item.
Remarks
The source and destination archive and vault store may be different, but the
source and destination site must be the same.
The caller must have READ access to the source archive, and WRITE access
permissions on the destination archive, otherwise an error will occur. For
structured archives, the caller must have READ access to the source archive
folder and WRITE access to the destination archive folder.
When copying an item:
■ Create the destination item object.
■ Set the ArchiveId on the destination item object.
■ Set CopyOptions properties on the destination item object.
■ Optionally set any ArchiveMetadata override property values if the copy
option, ITEM_COPYOPTIONS_ARCHIVEMETADATA, is selected.
The CopyOptions property on the destination item object specifies the item
elements to be copied across to the destination item.
See “IItem :: CopyOptions” on page 192.
From Enterprise Vault 8.0, the default action has changed; the item content and
its associated ArchiveMetaData and IndexData elements are copied from the
source item. This means that the default behaviour preserves the original
ArchivedDate and OriginalLocation on the destination item, if override values
are not specified.
IItem :: CopyTo
For backwards compatibility, the calling application can set suitable override
values on the destination item object.
For important considerations when specifying the destination archive folder,
see “Which properties determine the current archive folder” on page 267.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the destination archive

or Item Id has not been set,
or both
ocation and
IArchiveMetadata2::CurrentF
olderId have been set but they
refer to different archive
folders,
or either
ocation and
olderId have been set and the
destination archive is a flat
archive,
or the destination site is not
the same as the source site.

are not running.

resource to complete the copy,
or Enterprise Vault is
currently being backed up and
is not accepting copy
later.
IItem :: CopyTo
CONTENTMANAGEMENTAPI_E_NOT_FOUND The source or destination

Archive Id is unknown or has
been deleted,
been deleted
or the source item cannot be
found or has been deleted.
CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is full

or exceeds its quota limit.
CONTENTMANAGEMENTAPI_E_NO_ACCESS No access to the archive or

archive folder, or
or the target archive is in a
read-only state,
an override value has been
Features”. (By default, the
this operation).
CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to copy items to a

structured archive containing
multiple root folders (for
example, a public folder
archive).
Examples
C++
IItem* pItemSrc = NULL;
pCmAPI->get_Item(&pItemSrc);
pItemSrc->put_ArchiveId(CComBSTR(L”181E669473B52E64384C9A7D9EACA0E7
E1110000evsite”));
pItemSrc->put_Id(CComBSTR(L“334880000000000~200707251102240000~0~D3
962A35951E4B03AE9CFB68AFE1218“));
IItem* pItemDst = NULL;

pCmAPI->get_Item(&pItemDst);
IArchiveMetaData* pDstAMD = NULL;

IItem :: CopyTo
pItemDst->get_ArchiveMetaData(&pDstAMD);
pDstAMD->put_RetentionCategory(CComBSTR(L”Business”));
IComplianceData* pDstComp = NULL;

pDstAMD->get_ComplianceData(&pDstComp);
pDstComp->SetBy(SETBY_RETCAT);
pItemSrc->CopyTo(pItemDst);
C#
IItem itemSrc = cmAPI.Item;
IItem itemDst = cmAPI.Item;
itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000ev
site”;
itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218”;
itemDst.ArchiveMetaData.RetentionCategory = “Business”;
itemDst.ArchiveMetaData.ComplianceData.SetBy =
EV_STG_API_CP_SETBY.SETBY_RETCAT;
itemSrc.CopyTo(itemDst);
IItem :: MoveTo
IItem :: MoveTo
This method is used to move an item from one archive to another.
Syntax
HRESULT MoveTo([in] IItem* DestinationItem);
Parameters
[in] IItem* DestinationItem Pointer to the destination item object.
Remarks
The source and destination archive and vault store may be different, but the
source and destination site must be the same.
The caller must have DELETE access to the source archive and archive folder,
and WRITE access permissions on the destination archive and archive folder,
otherwise an error will occur.
The MoveTo method is identical to the CopyTo operation, but it additionally
removes the source item from the source archive after the copy has completed.
See “IItem :: CopyTo” on page 208.
The CopyOptions property on the destination item object specifies the item
elements to be copied across to the destination item.
See “IItem :: CopyOptions” on page 192.
Return value
S_OK Success.
IItem :: MoveTo
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the destination

archive or Item Id has not
been set,
or both
ocation and
olderId have been set but
they refer to different archive
folders,
or either
ocation and
olderId have been set and the
destination archive is a flat
archive,
or the destination site is not
the same as the source site.

are not running.

copy, or Enterprise Vault is
currently being backed up
and is not accepting copy
later.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The source or destination

Archive Id is unknown or has
been deleted,
been deleted
or the source item is not
found or has been deleted.
CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is

full or exceeds its quota limit.
IItem :: MoveTo
CONTENTMANAGEMENTAPI_E_DELETION_BARRED The source item cannot be

deleted because deletions are
not permitted for the archive;
the item's Retention Category
does not permit deletion and
the IArchiveMetadata
OverrideOnHoldRetCat was
not selected, or the item is on
legal hold.
CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have

delete access to the source
archive or archive folder,
or does not have write access
to the destination archive or
archive folder,or
or the source or destination
archive is in a read-only
state,
an override value has been
Features”. (By default, the
this operation)
CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to move items to

a structured archive
containing multiple root
folders (for example, a public
folder archive).
Example
site”;
itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218”;
itemSrc.MoveTo(itemDst);
IItem2 :: DeletionReason
If an item no longer exists in the archive, this property can be used to find out
why the item was deleted.
Syntax
HRESULT DeletionReason([out,retval]
EV_STG_API_DELETION_REASON* pVal)
Parameters
[out,retval] EV_STG_API_DELETION_REASON* pVal Current EV_STG_API_

DELETION_REASON value.
Remarks
If an attempt to retrieve an item fails because the item cannot be found, then the
DeletionReason property can be used to determine if the item has been deleted.
The property is populated only when it is accessed.
To retrieve the DeletionReason property, Item::Id and Item::ArchiveId
properties must be specified on the Item object.
EV_STG_API_DELETION_REASON is an enumeration value that identifies why
the item was deleted.
See “EV_STG_API_DELETION_REASON enumeration” on page 62
Return value
S_OK Success.
S_FALSE Success. The default value (NULL)

is returned.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is

NULL, or
the item's Archive Id or Id
property have not been set.
CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have read access to

the archive.
CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND There is no evidence that the

requested item existed in the
specified archive; the item does
not exist in the archive and there
is no current record of deletion.
Examples
C#
Item2 destItem = (IItem2)cmAPI.Item;
destItem.ArchiveId = ="1BFE65542AFD18F418824B15EF3288CD51110000
EVServer.corp.com";
destItem.Id = "200908040000000~200908041247260000~Z~80BD742AD7B88D0
850524974B9F44901";
try
{
// Try to get the item
destItem.Get((int)(
EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES
|EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA
|EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_SYSTEM_INDEXDATA));
}
catch (COMException e)
{
// If ITEM NOT FOUND error is thrown,
// check the deletion reason of the item.
if (e.ErrorCode == (int)EV_STG_API_ErrorCodes.
CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND)
{
EV_STG_API_DELETION_REASON delReason =
EV_STG_API_DELETION_REASON.DELETION_REASON_UNKNOWN;
try
{
delReason = destItem.DeletionReason;
}
finally
{
// Log that the item was not found together with the
// deletion reason
LogItemNotFound(destItem, delReason);
}
}
}
IItem3 :: Undelete
IItem3 :: Undelete
If an item has been moved to the Enterprise Vault "dumpster" area (soft deleted),
this method can be used to recover the item. The item is restored from the
dumpster area to the archive.
Syntax
HRESULT Undelete([out, retval] VARIANT_BOOL* pVal)
Parameters
[out,retval] VARIANT_BOOL* pVal A value of TRUE indicates that the item has
been recovered.
Remarks
The caller must be in an Enterprise Vault role that allows the operation “Can
undelete items in any archive”. (The task definition, "EVT Execute undelete
from archives", is included in the role, "Placeholder Application".)
Before calling Undelete, both the Archive ID and the Item ID must be set on the
Item object.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id has not been

found.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is

NULL, or
the item's Archive Id or Item Id
property have not been set.
CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have undelete

access to the archive. That is, the
caller is not in a role that allows
the operation, “Can undelete items
in any archive”.
IItem3 :: Undelete
CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND The item could not be found in the

archive, or has been removed from
the Enterprise Vault dumpster
area.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy

or has insufficient resources to
complete the request. This error
indicates that the caller should
retry later.
Version information
■ IItem3 interface requires Enterprise Vault 9.0.
See also
■ “IItem :: DeletionLevel” on page 190
Examples
C#
IItem3 item = (IItem3)cmAPI.Item;
item.ArchiveId =
“118F819534E391C43B6854E2DD3A708C61110000EV.example.com”;
item.Id =
“201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51
651”;
bool UnDeleted = item.Undelete();
Visual Basic Script

Dim ecmAPI, oItem, oItem3

set oItem = ecmAPI.Item
set oItem3 =
ecmAPI.IDispatchQueryInterface(oItem,"{E5C7F710-36AD-4e24-B00A-E3D7
09FF76CD}")
IItem3 :: Undelete
oItem3.ArchiveId =
"118F819534E391C43B6854E2DD3A708C61110000EV.example.com"
oItem3.ID =
"201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51
651"
dim results
result = oItem3.Undelete
if (Err.number <> 0) then

WScript.Echo "Error: " & Err.Description
end if
if result then
WScript.Echo "Item Undeleted"
else
WScript.Echo "Item has not been Undeleted"
end if
Content object
Content object
■ IContent
The IContent interface is obtained from an instance of IItem using the Content
property and provides calling applications with a set of properties that describe
the data being archived.
Syntax
interface IContent : IDispatch
Member summary
Table 4-29 IContent Properties
Title The name, title or subject of the item.
OriginalLocation The original location of the item. Folder hierarchy is represented

using back slashes as separators.
FileExtension File extension describing the format of the item.
MIMEFormat Optional property describing the MIME file format of the item.
CreatedDate Optional property that contains the UTC date and time that the
item was created.
ModifiedDate Optional property that contains the UTC date and time that the
item was last modified.
Data The Data property is used to pass the raw content of the item to or
from the archive. The parameter can be the path to a file that
contains the content to be archived, or an IStream or ILockBytes
object containing the content to be archived.
OriginalSize This property contains the size in bytes of the original item that
was archived.
Author Optional property. The author of the item.
Example
Content object

item.Insert();
IContent :: Title
IContent :: Title
This property holds the name, title or subject of the item.
Syntax
HRESULT Title([out, retval] BSTR* pVal);
HRESULT Title([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal The title of this item.
[in] BSTR newVal The new title of this item.
Remarks
If an attempt is made to change the title after a call to Insert or Get, an error will
occur.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or the

title of this item has already been
set in a previous call to Insert.
Example
C#
IContent content = itm.Content;
string title = content.Title;
IContent :: OriginalLocation
IContent :: OriginalLocation
This property holds the original location of the item.
Syntax
HRESULT OriginalLocation([out, retval] BSTR* pVal);
HRESULT OriginalLocation([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the original
location
[in] BSTR newVal The original location value to be set.
Return value
S_OK Success.

returned.

or this property has already been set.
Example
item.Insert();
IContent :: FileExtension
This property holds the file extension describing the format of the item.
Syntax
HRESULT FileExtension([out, retval] BSTR* pVal);
HRESULT FileExtension([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current
file extension.
[in] BSTR newVal The file extension to use.
Remarks
This property describes the format of the item.
For example, use ‘ .txt’ where the content is simple text, or ‘.msg’ where the
content is in Outlook message file format.
It is required so that the item can be indexed when it is archived, and opened
correctly by a web browser using IItem :: BrowserViewURL. The default value is
“.bin”.
The preceding period in a file extension can be included or omitted when setting
a value. It will be added by the API when the item is archived.
Once this value has been set it cannot be changed.
Return value
S_OK Success.

attempt has been made to change
an existing value.
Example
item.Insert();
IContent :: MIMEFormat
This property is optional and describes the MIME file format of the item.
This property is useful for HTTP Web-based client applications that process
byte streams with the MIME type parameter (content-type), rather than files.
Syntax
HRESULT MIMEFormat([out, retval] BSTR* pVal);
HRESULT MIMEFormat([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current value
of the property
[in] BSTR newVal The new value of the property to be set
Remarks
For example, use ‘text/plain’ where the content is simple text, or
‘application/vnd.ms-outlook’ where the content is in Outlook message file
format.
If the property is set, it cannot be changed after the item has been archived.
Return value
S_OK Success.

attempt has been made to change the
value of this property after the item
has been archived.
Example
content.MIMEFormat = "text/plain";
content.OriginalLocation = “C:\\temp”;
content.Data = "C:\\temp\\test.txt";
item.Insert();
IContent :: CreatedDate
This property contains the UTC date and time that the item was created.
Syntax
HRESULT CreatedDate([out, retval] VARIANT* pVal);
HRESULT CreatedDate([in] VARIANT newVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the value
of the property.
[in] VARIANT newVal The new value to set this property.
Remarks
Once this item has been archived it is not possible to change the value of this
property.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or

either an attempt to modify the
property value after the item has
been archived has been made, or
the data passed in is corrupt and
of the wrong data type.
Example
IContent cont = item.Content;

object obj = content.CreatedTime;

DateTime dt = (DateTime)obj;
IContent :: ModifiedDate
This property contains the UTC date and time that the item was last modified.
Syntax
HRESULT ModifiedDate([out, retval] VARIANT* pVal);
HRESULT ModifiedDate([in] VARIANT newVal);
Parameters
[out, retval] VARIANT* pVal The UTC date and time that the item was last
modified.
[in] VARIANT newVal Optional property that contains the UTC date and
time that the item was last modified.
Return value
Once this item has been archived it is not possible to change the value of this
property.
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or either

this property is being modified after
the item has been saved in the
archive, or the value passed into the
property is not in the correct
format.
Example
object obj = content.ModifiedTime;

IContent :: Data
IContent :: Data
This property is used to pass the raw content of the item to or from the archive.
Syntax
HRESULT Data([out, retval] VARIANT* pVal);
HRESULT Data([in] VARIANT newVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the actual
item data.
[in] VARIANT newVal Variant containing the data.
Remarks
One important point to remember is that the item data, properties and archive
metadata is not archived until the Insert method has been called.
This property must be set to the path of a file on disk, or an IStream or
ILockBytes object.
Note: If you specify a file, any existing content will be overwritten when
retrieving an item.
If the calling application is a .NET application, and the overhead of saving the
item content to a file is not acceptable, you will need to create a managed
implementation of the
System.Runtime.InteropServices.ComTypes.IStream interface.
For example, you can create a .NET class that inherits from
System.Runtime.InteropServices.ComTypes.IStream and
implements its methods using an instance of a managed stream,
System.IO.Stream.
The Content Management API supports IStream and ILockBytes
implementations where the input data length provided by the Stat method is not
known.
IContent :: Data
Handling items larger than 4MB prior to Enterprise Vault 8.0

When using a version of the Enterprise Vault API runtime prior to Enterprise
Vault 8.0, .NET applications should ensure the following recommendations are
implemented in order to support the insertion or retrieval of items larger than
4MB:
■ The application's entry point, the Main method, is not set to use the COM
single-threaded apartment (STA) model.
■ The application's entry point, the Main method, invokes
CoInitializeSecurity via PInvoke, with the following parameter values:
CoInitializeSecurity(NULL, -1, NULL, NULL,
RPC_C_AUTHN_LEVEL_CALL, RPC_C_IMP_LEVEL_IDENTIFY, NULL,
EOAC_NONE, NULL);
■ All use of the Content Management API is from threads set to use the COM
single-threaded apartment; the Content Management API is not invoked
from the application's entry point method.
Applications where these conditions cannot be met, such as Windows Forms
applications, applications hosted by IIS, or any other executable where COM
security has already been initialized to restrict remote access, cannot support
insert or retrieval of items larger than 4MB.
Return value
S_OK Success.

attempt has been made to modify this
property after the item has been
stored in the archive.
Example
C#
IContent content = itm.Content;
content.Data = “C:\\temp\\temp.msg”;
A C# implementation of IStream can be used instead:
MemoryStream itemCont = new MemoryStream();
content.Data = (IStream) new ComStreamAdaptor(itemCont);
IContent :: OriginalSize
IContent :: OriginalSize
This property returns the size of the original item, in bytes, before it was
archived.
Syntax
HRESULT OriginalSize([out, retval] VARIANT* pVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the
value of this property.
The VARIANT should have been set to
VARTYPE vt = VT_R8
Remarks
This property is only available after an item has been archived.
No error will be returned if this property is called before archiving and the
returned value will be 0.
Return value
S_OK Success.
Example
object obj = content.OriginalSize;

double size = (double)obj;
IContent :: Author
IContent :: Author
This property contains the author of the item.
The property is read/write and optional.
Syntax
HRESULT Author([out, retval] BSTR* pVal);
HRESULT Author([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current value
of this property.
[in] BSTR newVal The new value of the property to be set
Remarks
This is an optional property and does not need to be populated before archiving
an item. However, once set and the item archived, an error will occur if an
attempt is made to change the value.
Return value
S_OK Success.

attempt has been made to change
the value of this property after the
item has been archived.
Example
C#
[in]
IContent :: Author
content.Author = “Charles Dickens”

item.Insert();
[out]

string author = content.Author;

ArchiveMetaData object
IID is {4A0AAD67-882B-4fd6-A76C-4F7B0864F5D6}
IID is {5C6882BD-24BE-4C32-87EF-C3701D949BAA}
The interface is accessed using the ArchiveMetaData property of IItem, and
provides calling applications with a set of properties that describe how the Item
is archived.
IArchiveMetaData2 provides additional properties for determining the location
of an item, the Index Sequence Number (ISN) of an item and a read/write version
of the ArchivedDate property.
Syntax
interface IArchiveMetaData : IDispatch
interface IArchiveMetaData2 : IArchiveMetaData
Member summary
Table 4-30 IArchiveMetaData properties
RetentionCategory Read/Write This mandatory property contains the name or Id of

the retention category assigned to the item. Typical
category is "Business." for example.
ComplianceDevice Read only This property will be set to TRUE if the item is stored
on a compliance device on which retention periods can
be set.
OverrideOnHoldRetCat Read/Write This property is set TRUE to delete an item that

Enterprise Vault will normally prevent because the
Retention Category On-hold flag is enabled.
ArchivedDate Read only This property contains the UTC date and time that the
item was originally stored into the archive.
ComplianceData Read only This property returns a valid pointer to an instance of

the IComplianceData interface that allows the caller to
set compliance values for the archived item.
Table 4-30 IArchiveMetaData properties
SavesetSize Read only This property contains the saveset size (that is, the
final size of the archived item as stored on disk)
rounded to the nearest KB.
RetentionExpires Read only This property that contains the UTC date and time
that the item will be able to be deleted from the
archive.
IndexData Read only Pointer to a SimpleIndexMetaData object.

ISimpleIndexMetaData methods and properties
enable the calling application to retrieve the index
properties of an archived item, or add custom index
properties to an item as it is archived. The Search API
can be used to find items with specific index data.
IsItemSecured Read only Property that indicates that is it safe to delete the
original item from the source store. If the original item
is deleted before the archive item is secured, then the
item may not be restored as part of a disaster recovery
of the Enterprise Vault server.
CustomIdentifier Read/write This property, together with CustomQualifier can be

used to provide proprietary identity information for
the item.
CustomQualifier Read/write This property, together with CustomIdentifier can be

used to provide proprietary identity information for
the item.
CustomProperties Read/write This property can be used to hold proprietary

information about the stored item.
Table 4-31 IArchiveMetaData method
Method Description
Update Used to apply ComplianceData changes to a stored item.

Table 4-32 IArchiveMetaData2 properties
CurrentLocation Read/write Specifies the archive folder path to the current

location of the item in the archive. The property is
only intended for use with structured archives.
CurrentFolderId Read/write The ID of the current archive folder for the item.
The property is only intended for use with
structured archives.
SequenceNum Read only The Index Sequence Number (ISN) of the archived
item.
ArchivedDate Read/write The UTC date and time that the item was
originally stored in the archive.
Remarks
Version information
IArchiveMetaData2 interface requires Enterprise Vault 8.0.
Example

IArchiveMetaData :: RetentionCategory
This property contains the name or Id of the retention category assigned to the
item.
Syntax
HRESULT RetentionCategory([out, retval] BSTR* pVal);
HRESULT RetentionCategory([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR containing the current value of
this property.
[in] BSTR newVal New value to set this property to.
Remarks
An example of this would be "Business" or any other retention category created
using the Enterprise Vault Administrator Console.
The retention category Id may be specified as an alternative.
The Retention API can be used to discover or create retention categories.
See “Retention API” on page 387.
This property may be modified after the item has been archived.
Return value
S_OK Success.

returned.

Service is not running.

retried later.
Example
string retCat = amd.RetentionCategory;

IArchiveMetaData :: ComplianceDevice
IArchiveMetaData :: ComplianceDevice
This property indicates whether the item is stored on a compliance device on
which retention periods can be set.
Syntax
HRESULT ComplianceDevice([out, retval] VARIANT_BOOL* pVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which will contain

the current value of this property
Remarks
A value of true is returned if this item is on a compliance device.
Return value
S_OK Success.
Example
bool compDevice = amd.ComplianceDevice;
if (conpDevice == true)
{
//do something
IArchiveMetaData :: OverrideOnHoldRetCat
This property enables deletion of an item even if the retention category on-hold
flag is enabled.
Syntax
HRESULT OverrideOnHoldRetCat([out, retval] VARIANT_BOOL* pVal);
HRESULT OverrideOnHoldRetCat([in] VARIANT_BOOL newVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to an VARIANT_BOOL which will

contain the current value of this property
[in] VARIANT_BOOL newVal VARIANT_BOOL containing the value to be set.
Remarks
This property is set to 'true' if the item can be deleted even if the retention
category on-hold flag is set.
Once an item has been archived this property cannot be changed.
Return value
S_OK Success.

attempt was made to modify this
property after the item had been stored
in an archive.
Example
[in]
IArchiveMetaDate amd = item.ArcxhiveMetaData;

amd.OverrideOnHoldRetCat = true;
item.Insert();
[out]

bool override = amd. OverrideOnHoldRetCat;
if (override == true)
{
//do something
IArchiveMetaData :: ArchivedDate
This property contains the UTC date and time that the item was originally
stored in the archive.
Syntax
HRESULT ArchivedDate([out, retval] VARIANT* pVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived
date of this item
Remarks
This property is optional.
Version information
At Enterprise Vault 8.0, this property becomes a read/write property.
See “IArchiveMetaData2 :: ArchivedDate” on page 275.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or

the value input is not a valid date time..
Example
object obj = amd.ArchivedDate;

DateTime dt = (DateTime) obj;

IArchiveMetaData :: ComplianceData
This property returns a valid pointer to an instance of the
IComplianceDataInterface that allows the caller to set and view compliance
values for the archived item.
Syntax
HRESULT ComplianceData([out, retval] IComplianceData** pVal);
Parameters
[out, retval] IComplianceData** pVal Pointer to a valid IComplianceData

pointer.
Remarks
Although this property itself is read-only, its own properties allow compliance
data to be added/modified.
The IComplianceData interface enables compliance metadata to be set on an
item in an archive.
See “ComplianceData object” on page 307.
Return value
S_OK Success.
Example
IComplinceData compData = amd.ComplianceData;

EV_STG_API_CP_UNITS evUnits = compData.Units;

object obj = compData.Value;
ulong val = (ulong)obj;
IArchiveMetaData :: SavesetSize
This property holds the size of the archived item saveset, rounded to the nearest
KB.
Syntax
HRESULT SavesetSize([out, retval] VARIANT* pVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the current
value of the property
Remarks
This property is only available after an item has been archived. The VARIANT
type of this property should be vt = VT_UI4.
Although it is marked as read/write, this property cannot be modified on an item
that has already been archived.
Return value
S_OK Success.

attempt has been made to modify
this property after it has been stored
in an archive.
Example
object obj = amd.SavesetSize;

ulong size = (ulong)obj;

IArchiveMetaData :: RetentionExpires
This property contains the UTC date and time when the item can be deleted
from a compliance storage device.
Syntax
HRESULT RetentionExpires([out,retval] VARIANT* pVal);
Parameters
[out,retval] VARIANT* pVal Pointer to a VARIANT that will contain the current
value.
Remarks
This property value is populated when the item detail level,
DETAIL_LEVEL_COMPLIANCE_DATA, is set on the item Get method.
“EV_STG_API_ITEM_DETAIL enumeration” on page 65.
If the item is stored on a compliance device, then the property value is the UTC
date and time when the item can be deleted from the device.
If the storage device is not a compliance device, then then the property value is
30/12/1899 00:00:00, which is equivalent to an Automation date of 0.
The VARTYPE of the variant should be vt = VT_DATE.
Return value
S_OK Success.
Example
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_COMPLIANCE_DATA)));
object obj = amd.RetentionExpires;

IArchiveMetaData :: IndexData
This property returns a pointer to a SimpleIndexMetadata object, which allows
the calling application to enumerate system and custom index properties for the
current item, and add custom index properties when the item is archived.
Syntax
HRESULT IndexData([out, retval] ISimpleIndexMetadata** pVal);
Parameters
[out, retval] ISimpleIndexMetadata** pVal Pointer to a SimpleIndexMetadata object.
Remarks
The properties and methods of the ISimpleIndexMetadata interface can also be
used to add custom index data to an item as it is archived. The additional index
data is then available in the archive's index.
The Search API can be used to find items with specific index properties and
values.
For an overview of adding index properties to items, see “Adding custom index
metadata” on page 55.
Return value
S_OK Success.

attempt has been made to access
this property after the item has
been archived.
Requirements
Requires KVS.EnterpriseVault.Common.dll.
Example
ISimpleIndexMetadata simple = amd.IndexData;
See also
■ “IItem :: Get” on page 200.
■ “SimpleIndexMetadata object” on page 277.
IArchiveMetaData :: IsItemSecured
This property indicates that is it safe to delete the original item from the source
store.
Syntax
HRESULT IsItemSecured([out, retval] VARIANT_BOOL* pVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which contains

the current value of this property
Remarks
If the original item is deleted before the archive item is secured, then the item
may not be restored as part of a disaster recovery of the Enterprise Vault server.
The meaning of “secured” depends upon the storage device; it may mean that
the item has been backed-up, or that the storage device has replicated the item
to a duplicate device.
Return value
S_OK Success.
Example
item.Get((int)(EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA)
bool isSecured = amd.IsItemSecured;
if (isSecured == true)
{
//safe to delete original item from the source
IIArchiveMetaData :: CustomIdentifier
This property, together with the CustomQualifier property, can be used to
provide proprietary identity information for the item. For example, this
property could be used to hold the source store's identifier for the original item.
Syntax
HRESULT CustomIdentifier ([in] BSTR newVal);
HRESULT CustomIdentifier ([out, retval] BSTR* pVal);
Parameters
[in] BSTR newVal New value to set for this property.
[out, retval] BSTR* pVal Pointer to a BSTR containing the current value of this
property.
Remarks
The maximum length of this property is 255 characters.
This property is used in conjunction with the CustomQualifier property, which
defaults to zero.
It is possible to duplicate values using the CustomIdentifier/CustomQualifier
properties. To ensure uniqueness, the CustomIdentifier value should use an
application namespace, for example a GUID, as a prefix to the application
identifier. For example, <application GUID>.<application Id>.
As FSA and SharePoint Archiving use this property to hold information for
restoring items, the property value should not be changed for items archived
using FSA or SharePoint Archiving.
Return value
S_OK Success.

returned.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or either an

property after it has been stored in an
archive, or the value exceeds 255
characters.
Example
Visual Basic Script

This example shows how CustomIdentifier, CustomQualifier and
CustomProperties can be set.
const CUSTOM_PROPERTIES = "<?xml version='1.0'?><properties><key =
'1' value='some value'/></properties>"
const CUSTOM_ID = "AcmeWidgetId-00002"

const CUSTOM_QUALIFIER = 1
Dim oItem
oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID
oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES
oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER
IIArchiveMetaData :: CustomQualifier
This property, together with the CustomIdentifier property, can be used to
provide proprietary identity information for the item. For example, if different
versions of a document are archived, this property could hold the document
version information.
Syntax
HRESULT CustomQualifier ([in] LONG newVal);
HRESULT CustomQualifier ([out, retval] LONG* pVal);
Parameters
[in] LONG newVal New value to set for this property.
[out, retval] LONG* pVal Pointer to a LONG containing the current value of
this property.
Remarks
This property is used in conjunction with the CustomIdentifier property. The
property can only be set after the CustomIdentifier property has been set.
If a CustomIdentifier has been set this property defaults to zero.
Return value
S_OK Success
S_FALSE Success. The default value (0) is

returned.

archive, or the CustomIdentifier
property has not been set.
Example
Visual Basic Script

'1' value='some value'/></properties>"

Dim oItem
IIArchiveMetaData :: CustomProperties
This property can be used to hold proprietary information about the stored item.
Syntax
HRESULT CustomProperties ([in] BSTR newVal);
HRESULT CustomProperties ([out, retval] BSTR* pVal);
Parameters
[in] BSTR newVal New value to set for this property.
[out, retval] BSTR* pVal Pointer to a BSTR containing the current value of
this property.
Remarks
The maximum length of this property is 2500 characters.
Return value
S_OK Success

returned.

archive, or the value exceeds 2500
characters.
Example
Visual Basic Script

'1' cost='543'/></properties>"

Dim oItem
IArchiveMetaData :: Update
The Update method is used to effect changes made to the ICompliance interface
by the calling application to the item stored in Enterprise Vault.
Syntax
HRESULT Update(void)
Remarks
The ArchiveId and Id properties must be set prior to calling the Update method.
The operation will only be performed if the compliance device allows it. If this is
not the case, a bad HRESULT will be returned, indicating the cause of the failure.
Note the following when extending the compliance period on an item:
■ You cannot change the compliance period if the item is stored on a device
that has no compliance period or does not support extending the
compliance period.
■ The new retention period must be longer than the original retention period.
■ You can only extend the retention period of the retention category assigned
to the item; you cannot assign a different retention category.
■ You cannot remove the compliance period completely by setting values to
"NONE”.
■ The only values that can be changed currently are the compliance unit and
value properties.
See “ComplianceData object” on page 307.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in,

or either the archive or item Id has
not been set,
or there is an error with the retention
category, or an attempt has been
made to change it.
CONTENTMANAGEMENTAPI_E_INVALID_DEVICE The storage device is not a

compliance device.


the update request, or Enterprise
Vault is currently being backed up and
is not accepting update requests. This
error indicates that the caller should
retry later.
CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have write access

to the target archive or archive folder.
Example
DETAIL_LEVEL_COMPLIANCE_DATA)));
compData.Units = EV_STG_API_CP. CP_UNITS_MONTHS;

compData.Value = 18;
amd.Update();
IArchiveMetaData2 :: CurrentLocation
This property specifies the path of the archive folder in which the item is
currently stored, or is to be stored when performing insert, copy or move item
operations.
This property is only intended for use with structured archives, that is, archives
that contain folders.
Syntax
HRESULT CurrentLocation ([in] BSTR newVal);
HRESULT CurrentLocation ([out, retval] BSTR* pVal);
Parameters
[in] BSTR newVal Folder path to be set as the item’s current location in
the archive.
[out, retval] BSTR* pVal Archive folder path set as the item’s current location.
Remarks
The Items collection object can be used to populate this property automatically.
The property value is automatically populated by any of the following methods:
■ Insert
■ MoveTo
■ CopyTo
The folder path specifies the archive folder path relative to the root, or default,
archive folder. The following examples illustrate the default root archive folder
path used by the CurrentLocation property for the different types of archives:
■ Mailbox archives.
The CurrentLocation property value does not contain any folder path
elements for the default root archive folder.
The example value “Inbox\Accounts” represents the location of an item in
the folder “Accounts”, which is subfolder of “Inbox” archive folder.
■ Public Folder archives.
The default root archive folder path in the CurrentLocation property value
represents the location of the Exchange Public Folder archiving target.
For example, if the folder path for an Exchange Public Folder archiving
target is “EXCHSVR\Sales\Documents”, and the value of the
CurrentLocation property is “EXCHSVR\Sales\Documents\FolderA”, then
the item is located in the folder “FolderA”, which is subfolder of the root
archive folder for the Public Folder archiving target.
■ FSA archives.
represents the location of the FSA volume archiving target.
For example, if the folder path for an FSA volume archiving target is
“\\FileSVR1.Example.COM\FSA Volume\5”, and the value of the
CurrentLocation property is
“\\FileSVR1.Example.COM\FSA Volume\5\NewFolder”, then the item is
located in the folder “NewFolder”, which is subfolder of the root archive
folder for the FSA volume archiving target.
■ SharePoint archives.
represents the URL of the SharePoint site collection archiving target.
For example, if the URL for a SharePoint site collection archiving target is
“http://sharepoint/sites/marketing”, and the value of the CurrentLocation
property is “http://sharepoint/sites/marketing/UK”, then the item is
located in the folder “UK”, which is subfolder of the root archive folder for
the SharePoint site collection target.
Note that the syntax rules applied to SharePoint archive folder paths differ
from those applied to folder paths in other types of archive.
The following syntax rules apply when retrieving or setting the CurrentLocation
property value for archives other than SharePoint archives;
■ The backslash character (‘\’) is treated as the folder path subfolder
separator character.
■ Double backslash (‘\\’) is used for preserving a backslash character in the
folder path string.
■ Leading backslash characters will be ignored.
If the CurrentLocation property is specified for a flat archive (for example,
shared or journal archives, which do not contain folders), then the property
value returned is an empty string.
You can use the IArchive2::HasFolders property to determine if the archive is
flat or has a folder structure.
Which properties determine the current archive folder

For item insert, copy or move operations, each of the following properties can be
used to set the archive folder:
■ IArchiveMetaData2:: CurrentFolderId
The following conditions should be noted:
■ CurrentFolderId and CurrentLocation properties are only intended for use
with archives that contain folders.
■ CurrentFolderId and CurrentLocation are mutually exclusive.
■ CurrentFolderId and CurrentLocation are optional.
■ When copying or moving an item, then the destination archive folder is
defined by IArchiveMetaData2::CurrentLocation (if the source archive
contains a folder structure), or IContent::OriginalLocation (if the source
archive is flat). If neither of these properties is specified, then the root
folder of the archive is used.
For insert, copy or move operations, if the value of ArchiveId is an archive
folder ID, then the ArchiveId property can be used instead of
CurrentFolderId or CurrentLocation to define the archive folder for the
item.
■ If the folder identified by CurrentLocation (or IContent::OriginalLocation,
when defaulting) has not yet been created, it is created automatically,
together with any missing parent folders.
The caller must have write access on the destination archive in order to
create new folders. When creating new folders, folder permissions are
inherited from the parent folder.
■ If IContent::OriginalLocation property is omitted, the value is populated
with the path of the item’s archive folder (insert operation), or the path of
the item’s archive folder in the source archive (copy or move operation).
Methods to enumerate, create, delete (if empty) and update archive folders are
not currently available. Also, caller applications cannot manage folder level
permissions using the Content Management API.
Table 4-33 summarizes how the archive folder is determined when different
combinations of the following properties are set:
■ IArchiveMetaData2::CurrentFolderId
Table 4-33 Determining the target archive folder for insert, move and copy operations
ArchiveId CurrentFolderId CurrentLocation OriginalLocation Archived to Saveset

Property Property Property Property folder… OriginalLocation1
Archive Id Not specified Not specified Not specified Root folder “” (i.e. Empty string)
Archive Id Not specified Not specified Specified Folder matching Value of

CurrentLocation or OriginalLocation
OriginalLocation property
property (Folder
created as necessary
– viz current refile
behaviour)
Archive Id Not specified Specified Not specified Folder matching Value of

CurrentLocation CurrentLocation
property (Folder property
created as necessary)
Archive Id Not specified Specified Specified Folder matching Value of

CurrentLocation OriginalLocation
property (Folder property
created as necessary)
Archive ID Specified Not specified Not specified Specified folder. Path of the specified
(It must be a folder in CurrentFolderId
the archive) from the Directory
Archive ID Specified Not specified Specified Specified folder. Value of

(It must be a folder OriginalLocation
within the archive) property
Archive ID Specified Specified Irrelevant Not supported;

error with invalid
arguments 2
Archive folder ID Not specified Not specified Not specified Folder specified in Path of specified
ArchiveId property Archive folder ID
from the Directory
Archive folder ID Not specified Not specified Specified Folder specified in Value of
ArchiveId property OriginalLocation
property
Table 4-33 Determining the target archive folder for insert, move and copy operations
ArchiveId CurrentFolderId CurrentLocation OriginalLocation Archived to Saveset

Property Property Property Property folder… OriginalLocation1
Archive folder ID Not specified Specified Not specified Folder matching Value of
CurrentLocation CurrentLocation
property. property
(Folder created as
necessary)
Archive folder ID Not specified Specified Specified Folder matching Value of

CurrentLocation OriginalLocation
property. property
(Folder created as
necessary)
Archive folder ID Specified Not specified Not specified Specified folder. Path of the specified
(It must be a folder in CurrentFolderId
the archive) from the Directory
Archive folder ID Specified Not specified Specified Specified folder. Value of

(It must be a folder in OriginalLocation
the archive) property
Archive folder ID Specified Specified Irrelevant Not supported;

error with invalid
arguments 2
1.(CopyTo and MoveTo) If OriginalLocation is not specified, then it is copied from the source item saveset value.
2.Allowed if the archive folder ID associated with the specified CurrentLocation matches the specified CurrentFolderId value.
Return value
S_OK Success.
S_FALSE Success. The default value (NULL) is returned.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or newVal is not a syntactically valid

folder path.
CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not

running.
CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource

to complete the request. This error indicates that the caller
should retry later.
Example
C++
IItem* pItem = NULL;
pCmAPI->get_Item(&pItem);
// Identify ArchiveID of archive in which item is stored

CComBSTR ArchiveId
(L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
pItem->put_ArchiveId(ArchiveId);
// Identify Id of stored item

CComBSTR ItemId (L” 161000000000000~200501051649270000~0~9039
eb282e3d4083b79f3298dc8a1e60”)
pItem->put_Id(ItemId);
pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA );
IArchiveMetaDatat* pAMD = NULL;

pItem->get_ArchiveMetaData(&pAMD);
//Fetch the item’s current archive folder path location

CComBSTR CurrentLocation;
CComQIPtr<IArchiveMetaData2> pAMD2(pAMD);
pAMD2->get_CurrentLocation(&CurrentLocation);
IArchiveMetaData2 :: CurrentFolderId
This property specifies the ID of the archive folder in which the item is currently
stored, or is to be stored when performing insert, copy or move item operations.
This property is only intended for use with structured archives, that is, archives
that contain folders.
Syntax
HRESULT CurrentFolderId ([in] BSTR newVal);
HRESULT CurrentFolderId ([out, retval] BSTR* pVal);
Parameters
[in] BSTR newVal The ID of the archive folder to set as current folder
for the item.
[out, retval] BSTR* pVal The ID of the item’s current archive folder.
Remarks
The Items collection object populates this property automatically.
The property value is automatically populated by any of the following methods:
■ IItem::Insert
■ IItem::MoveTo
■ IItem::CopyTo
For item insert, copy or move operations on structured archives, each of the
following properties can define the destination archive folder:
■ IArchiveMetaData2:: CurrentFolderId
See “Which properties determine the current archive folder” on page 267.
If the CurrentFolderId property is specified for a flat archive (for example,
shared or journal archives, which do not contain folders), then the property
value is populated with the archive Id value after an Item property retrieval
operation.
You can use the IArchive2::HasFolders property to determine if the archive is

flat or has a folder structure.
Return value
S_OK Success.
S_FALSE Success. The default value (NULL) is returned.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or newVal is an not a valid archive

folder Id.
Example
C++
IItem* pItem = NULL;
pCmAPI->get_Item(&pItem);
// Identify ArchiveID of archive in which item is stored

CComBSTR ArchiveId
(L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
pItem->put_ArchiveId(ArchiveId);
// Identify Id of stored item

CComBSTR ItemId (L” 161000000000000~200501051649270000~0~9039
eb282e3d4083b79f3298dc8a1e60”)
pItem->put_Id(ItemId);
pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA );
IArchiveMetaDatat* pAMD = NULL;

pItem->get_ArchiveMetaData(&pAMD);
//Fetch the item’s current archive folder ID

CComBSTR CurrentFolderId;
CComQIPtr<IArchiveMetaData2> pAMD2(pAMD);
pAMD2->get_CurrentFolderId(&CurrentFolderId);
IArchiveMetaData2 :: SequenceNum
This property specifies the Index Sequence Number of the archived item.
Syntax
HRESULT SequenceNum ([out, retval] ULONGLONG* pVal)
Parameters
[out, retval] ULONGLONG* pVal The Index Sequence Number (ISN) of the archived
item.
Remarks
This property uniquely identifies the item in the archive. It can be used to
identify the start Index Sequence Number when enumerating collections of
archived items using the Items collection object.
See “IItems :: StartSequenceNum” on page 168.
The Items collection object populatesthis property automatically. This is useful
for bulk moving or copying items.
The property value is automatically populated immediately after any of the
following operations:
■ IItem::Insert
■ IItem::MoveTo
■ IItem::CopyTo
Enterprise Vault item sequence numbers are not always consecutive, as items
may have expired or been deleted.
Requirements
Windows Server 2003 supports ULONGLONG types with OLE Automation.
However ULONGLONG types are not supported on Windows Server 2000.
.NET managed code and C++ support ULONGLONG types, but these types are
not supported by Visual Basic Script.
Return value
S_OK Success.
Example
C#
This example shows how to use the IArchiveMetaData2 interface to fetch the
SequenceNUm property.
Item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite”;
Item.Id = "200808070000000~200808070940280000~Z~BFA0C1B1FAB1468DB82
2E2473B4AAB05"
Item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA);
// Fetch the item's sequence no property

//
IArchiveMetaData2 IAMD2 = (IArchiveMetaData2)EVItem.
ArchiveMetaData;
ulong SeqNo = EVIAMD2.SequenceNum;
IArchiveMetaData2 :: ArchivedDate
This property enables the caller to retrieve and set the original archived date
and time (UTC) for the item.
Syntax
HRESULT ArchivedDate([in] VARIANT newVal);
HRESULT ArchivedDate([out, retval] VARIANT* pVal);
Parameters
[in] VARIANT newVal The required UTC date and timeto be set for this
item
[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived
date of this item
Remarks
Setting this property is optional. Typically it is only set to retain the archived
date when copying or moving items.
Note: Setting the archived date can affect the item's retention period.
To specify an ArchivedDate when storing an item, set the ArchivedDate

property value before calling the Insert method.
When copying or moving an item, the default action is to retain the item's
archived date. To reset the achived date to the current date time, simply set a
null value on the destination ArchiveMetadata object.
Return value
S_OK Success.
S_FALSE Success. The default value (0) is

returned.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Supplied Variant type not VT_NULL

or VT_DATE,
or an attempt was made to modify
this property after the item had been
stored in an archive,
or pVal is NULL.
Example
site”;
itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218”;
IArchiveMetaData2 amd =
(IArchiveMetaData2)itemDest.ArchiveMetaData;
amd.ArchivedDate = DateTime.Now();
itemSrc.CopyTo(itemDst);
SimpleIndexMetadata object
■ ISimpleIndexMetadata
A SimpleIndexMetadata object is a collection of SimpleIndexProperty objects.
You can use the ISimpleIndexMetadata methods and properties to add new
custom index properties before an item is archived, and to enumerate the
individual properties that belong to an item.
Syntax
interface ISimpleIndexMetadata : IDispatch
Member summary
Table 4-34 ISimpleIndexMetadata properties
NewEnum Read only Enumerator which returns a standard

enumerator to a collection of
SimpleIndexProperty objects
DateTimesUTC Read/Write Sets or retrieves whether the date and time

properties are input and output in UTC or local
system time.
Table 4-35 ISimpleIndexMetadata methods
Method Description
Count Gives the number of custom index metadata properties for the
current item.
Add Adds a value for a custom index property.
Clear Clears all properties from the SimpleIndexMetadata object for

the current item.
ToXML Returns the metadata in XML format.
FromXML Loads a set of properties that have previously been defined and
stored using the ToXML method.
ToLocalTime Converts a UTC time to local system time.

Table 4-35 ISimpleIndexMetadata methods
Method Description
ToUTCTime Converts a local system time to UTC time.
Remarks
The type of properties returned in the collection can be controlled using the
enumeration, EV_STG_API_ITEM_DETAIL, on the Get method of the IItem
interface.
Examples
C#
VBScript
The following VBScript excerpt gives an example of how metadata can be read
from the instance returned by Content Management API:
' Get the Index Metadata from the retrieved item
Set IMData = oItem.ArchiveMetaData.IndexData
if (IMData.Count() = 0) then
WScript.Echo "No properties loaded!", vbOKOnly + vbExclamation,
"Index Metadata"
Err.Clear
else
'Use local system date/times
IMData.DateTimesUTC = false
' Loop through the properties displaying the details of each
Dim idxprop
for each idxprop in IMData
Dim propInfo
Dim pVal
propInfo = "Set: " + idxprop.Set + vbCrLf + "Name: " +
idxprop.Name
propInfo = propInfo + vbCrlf + "Searchable: " +
CStr(idxprop.Searchable)
propInfo = propInfo + vbCrlf + "Retrievable: " +
CStr(idxprop.Retrievable)
pVal = idxprop.Value
propInfo = propInfo + vbCrLf + "Value (" + TypeName(pVal) +
"): " + CStr(pVal)
WScript.Echo propInfo, vbOKOnly, "Index Metadata Properties

List"
next
if (Err.number <> 0) then
WScript.Echo "Enumerating failed!" + vbCrLf + "Reason: " +
Hex(Err.number) + vbCrLf + "Description: " +
Err.Description, vbOKOnly + vbExclamation,
"Index Metadata"
Err.Clear
end if
end if
Requirements
Implemented in KVS.EnterpriseVault.Common.dll.
See also
■ “SimpleIndexProperty object” on page 293.
■ “IItem :: Get” on page 200.
ISimpleIndexMetadata :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the SimpleIndexMetadata collection object. This property is
hidden in Visual Basic Scripting Edition (VBScript).
Syntax
HRESULT _NewEnum([out,retval] IUnknown** enumerator);
Parameters
[out,retval] IUnknown** enumerator Returned reference to the IUnknown

interface of the object.
Remarks
This property is a standard property used to support enumerating collections, it
is automatically used internally when you use the For Each construct in C#, or
VBScript.
A collection of SimpleIndexProperty objects is returned.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive

property value.
Example
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

foreach (ISimpleIndexProperty ip in simple)

{
string set = ip.Set;
string name = ip.Name;
object val = ip.Value;
bool searchable = ip.Searchable;
bool retrievable = ip.Retrievable;
//do something with the values obtained

}
ISimpleIndexMetadata :: DateTimesUTC
ISimpleIndexMetadata :: DateTimesUTC
This boolean property sets or retrieves whether the date and time properties are
input and output in UTC or local system time.
Syntax
HRESULT DateTimesUTC([out, retval] VARIANT_BOOL* pRetVal);
HRESULT DateTimesUTC([in] VARIANT_BOOL pRetVal);
Parameters
[out, retval] VARIANT_BOOL* pRetVal Whether time property values are UTC
times or as local system times.
[in] VARIANT_BOOL pRetVal Whether time property values are UTC

times or as local system times.
Remarks
By default, items are always archived using UTC time.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL.
Examples
'Use local system date/times
ISimpleIndexMetadata :: Count
ISimpleIndexMetadata :: Count
This method gives the number of custom index metadata properties for the
current item.
Syntax
HRESULT Count([out, retval] long* pRetVal);
Parameters
[out, retval] long* pRetVal Number of custom index metadata properties.
Return value
S_OK Success.
Example
if (simple.Count > 0)
{
//do something
ISimpleIndexMetadata :: Add
This method is used to add a custom index property to an item before it is
archived. The property is then available in the index document for the item.
The Search API can be used to search for specific index data.
Syntax
HRESULT Add
[in] BSTR propertySet,
[in] BSTR propertyName,
[in] VARIANT propertyValue,
[in] VARIANT_BOOL propertySearchable,
[in] VARIANT_BOOL propertyRetrievable);
Parameters
[in] BSTR propertySet Name of the property set to which the property belongs,
or is to be added. If no property set is specified, the
property is added to the default (global) property set.
[in] BSTR propertyName Name of the property.
[in] VARIANT propertyValue Property value. A Variant containing a value of any of the
support types as follows:
Value type Variant type Note
String VT_BSTR
Datetime VT_DATE Limited to the

UTC date range
of 1st January
100 to 31st
December 2148
Integer VT_UI1, VT_UI2, Limited to the

VT_UI4, VT_UI8, range 0 to
VT_I1, VT_I2, 4,294,967,294
VT_I4, VT_I8,
VT_INT,
VT_UINT, or
VT_DECIMAL
[in] VARIANT_BOOL Defines whether the property is added to the item index.
propertySearchable Setting the value of this property to true means that the
property will be indexed.
The default value is true.
[in] VARIANT_BOOL Defines whether the property values can be requested in

propertyRetrievable search results. Setting the value to true means that
property information can be retrieved and displayed
later with the item in search results.
The default value is false.
Remarks
Custom index data can only be added when the item is inserted, copied or
moved. It is not possible to update custom index data for an archived item.
The method can be called repeatedly to add multiple properties or to add
multiple values to the same property.
When you use Add to add a property to the index, the property will be added to
the property set specified by the propertySet parameter.
If a property set is specified that does not exist, then the property set will be
created and the property and value will be added to that new set.
It is good practice to use a named property set for properties added by an
application in order to avoid name clashes with other custom additions. Suitable
names would be your company name or the application name. The following
property set names are reserved:
■ Vault
■ EnterpriseVault
■ Any property set name starting with EV
■ KVS
■ Veritas
■ Symantec
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER propertySet is NULL,

or propertyName is NULL or an
empty string,
or propertyValue is NULL or an
invalid type or is an invalid value, for
example out of supported range.
Example
ISimpleIndexMetaData simple = amd.IndexData;
//add some custom index data

simple.Add(“My set”, “My name”, 32, true, true);
item.Insert();
ISimpleIndexMetadata :: Clear
ISimpleIndexMetadata :: Clear
This method is used to clear all properties from the SimpleIndexMetadata object
for the current item.
Syntax
HRESULT Clear();
Return value
S_OK Success.
Example

simple.Clear();
ISimpleIndexMetadata :: ToXML
This method returns the metadata in XML format.
Syntax
HRESULT ToXML(
[in] VARIANT_BOOL formattedLayout,
[out, retval] BSTR* pRetVal);
Parameters
[in] VARIANT_BOOL formattedLayout If true, the XML returned will be in

human-readable format.
[out, retval] BSTR* pRetVal An XML string is returned.
Return value
S_OK Success.
Examples
The following code excerpt gives an example of how metadata can be added and
returned as XML, using the ToXML method:
Option Explicit
'On Error Resume Next
Dim ecmAPI
Dim oItem
set oItem = ecmAPI.Item
oItem.ArchiveId =
“137100ED24187DB43A884B0C0B8D3FF511110000EVServer”
// populate the Data property from a file
oItem.Content.Data = “c:\data file.doc”
oItem.Content.Title = “function design document.doc”
oItem.ArchiveMetaData.RetentionCategory = “Technical Documents”
oItem.ArchiveMetaData.ComplianceData.SetBy = RetCat
Dim IMData
set IMData = oItem.ArchiveMetaData.IndexData
IMData.Clear
‘ Use local date and time
‘ Add a property called Agent, with the string value,
‘ "EgApplication" to the default, global property set. This property
‘ is searchable and retrievable.
IMData.Add vbNullString, "Agent", "EgApplication",true, true
‘ Add the following properties to the property set called "EgApp".

IMData.Add "Egapp", "File", "EgFilename", false, true
IMData.Add "EgApp", "TimeStamp", CDate("2006-10-23 12:00:00"),
false, true
‘ return the property information as formatted XML

WScript.Echo IMData.ToXML(true)
oItem.Insert() // actually performs the insert

...
The ToXML method in this example would display the custom metadata as
formatted XML, as shown in Figure 4-3‚ ”ToXML result”.
Figure 4-3 ToXML result
See also
■ “ArchiveMetaData object” on page 237
ISimpleIndexMetadata :: FromXML
ISimpleIndexMetadata :: FromXML
This method enables you to load a set of properties that have previously been
defined and stored using the ToXML method.
Syntax
HRESULT FromXML([in] BSTR xmlIndexMetadata);
Parameters
[in] BSTR xmlIndexMetadata The XML stream to input.
Remarks
Use the Add method to add item specific values.
The XML schema is not published, as the Add method should always be used to
add metadata properties.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER xmlIndexMetadata supplied as

NULL, or is invalid XML.
Example
ISimpleIndexMetaData simple = amd.IndexData;
//add some custom index data from xml

simple. FromXML(xmlData); //xmlData is a pre-populated string
containing the xml
item.Insert();
ISimpleIndexMetadata :: ToLocalTime
ISimpleIndexMetadata :: ToLocalTime
This is a helper method to convert a UTC time to local system time.
Syntax
HRESULT ToLocalTime(
[in] DATE utcDateTime,
[out, retval] DATE* pRetVal);
Parameters
[in] DATE utcDateTime The UTC date and time to convert.
[out, retval] DATE* pRetVal The local date and time are returned.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL,

or utcDateTime is not a syntactically
valid UTC date time value.
ISimpleIndexMetadata :: ToUTCTime
ISimpleIndexMetadata :: ToUTCTime
This is a helper method to convert a local system time to UTC date and time.
Syntax
HRESULT ToUTCTime(
[in] DATE localDateTime,
[out, retval] DATE* pRetVal);
Parameters
[in] DATE localDateTime The local date and time to convert.
[out, retval] DATE* pRetVal The local date and time are returned.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL,

or localDateTime is not a
syntactically valid local date time
value.
SimpleIndexProperty object
SimpleIndexProperty object
The SimpleIndexProperty object implements the following interface:
■ ISimpleIndexProperty
Syntax
interface ISimpleIndexProperty : IDispatch
Member summary
This read-only interface has the following properties defined:
Table 4-36 ISimpleIndexProperty properties
Parameter Read/Write Description
Set Read only Name of the property set.
Name Read only Name of the property.
Value Read only Value assigned to the property.
Searchable Read only Whether the property is to be added to the item

index.
Retrievable Read only Whether the property can be included in search

results.
System Read only Whether the property is one that is indexed by

default during the archiving process.
Remarks
Properties added to the item index using the Add method of the
ISimpleIndexMetadata interface are held as SimpleIndexProperty objects.
Example

{
ISimpleIndexProperty :: Set
This property returns the property set name.
Syntax
HRESULT Set([out, retval] BSTR* value);
Parameters
[out, retval] BSTR* value Property set name.
Remarks
If empty, the property is a member of the global property set.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive

property value.
Example

{

}
ISimpleIndexProperty :: Name
This property returns the property name.
Syntax
HRESULT Name([out,retval] BSTR* value);
Parameters
[out,retval] BSTR* value Name of the property.
Remarks
The name of a property can be a predefined name, such as IndexPropSUBJ, the
numeric identification of an attachment (for example, 1.1), or a custom name.
If the value is a formatted number (1, 1.1, 1.2 and so on), then the property refers
to a message attachment, which may be a file or a message. In this case, the
value is another instance of a SimpleIndexMetadata object, detailing the index
properties of the attachment.
If the property is a top-level message, then the Name is “1”. The first attachment
would be “1.1”. The first attachment on a nested message would be “1.1.1”.
Figure 4-4 illustrates the naming convention for messages and attachments.
Figure 4-4 Naming format for messages
Top-level message
Message Attachments
1.1 1.2 1.3
1.1.2 1.2.1
1.1.1
1.2.1.1
Each of the nested items has their own set of properties, which can be
enumerated.
The property, IndexPropANUM, also contains the numeric identity of a message
attachment. The value of this property differs from the property Name.
Figure 4-5 shows the values of IndexPropANUM for a message with an attached
document and an attached message, which also has attached documents.
Figure 4-5 Example values of IndexPropANUM
Top-level message
anum=0
Message attachments
anum=1 anum=4 anum=7
anum
anum=2 =3 anum=5
anum=6
If content items are missing, the COMR (content missing) property is returned in
the index data. The value of this property indicates the reason for the missing
content. For predefined values for this property, see “Note 4” on page 677.
Return value
S_OK Success.

property value.
Version information
■ Numeric identity of a message attachments in IndexPropANUM is available
in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise
Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on
page 31.
■ Content missing reasons returned in the index data COMR property is

available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See
“Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault
■ For a message attachment, the value of ISimpleIndexProperty :: Name can
be a formatted number (1, 1.1, 1.2 and so on) in Enterprise Vault 6.0 SP4 and
Enterprise Vault 7.0 SP2. See “Enterprise Vault 2007, Enterprise Vault 7.0
SP2, and Enterprise Vault 6.0 SP4” on page 33.
Example

{

}
See also
■ “System properties” on page 664.
ISimpleIndexProperty :: Value
This property returns the property value.
Syntax
HRESULT Value([out,retval] VARIANT* value);
Parameters
[out,retval] VARIANT* value Property value. A Variant containing a value of any of

the support types as follows:
Value type Variant type Note
String VT_BSTR
Datetime VT_DATE Limited to the

UTC date range of
1st January 100 to
31st December
2148
Integer VT_UI1, Limited to the

VT_UI2, range 0 to
VT_UI4, 4,294,967,294
VT_UI8, VT_I1,
VT_I2, VT_I4,
VT_I8, VT_INT,
VT_UINT, or
VT_DECIMAL
SimpleIndexMeta VT_UNKNOWN An
data object ISimpleIndexProp
erty instance
Remarks
If the Name property is a formatted number (1.1, 1.2 and so on), then the
property refers to a message attachment, which may be a file or a message. In
this case, the Value property is a SimpleIndexMetadata object, detailing the
index properties of the attachment.
Return value
S_OK Success.

property value.
Example

{

}
ISimpleIndexProperty :: Searchable
This property returns whether the property is indexed, and hence can be
searched for using the Search API.
Syntax
HRESULT Searchable([out,retval] VARIANT_BOOL* value);
Parameters
[out,retval] VARIANT_BOOL* value
Return value
S_OK Success.

property value.
Example

{

}
See also
ISimpleIndexProperty :: Retrievable
This property returns whether the property can be retrieved and displayed with
search results in the search application.
Syntax
HRESULT Retrievable([out,retval] VARIANT_BOOL* value);
Parameters
Return value
S_OK Success.

property value.
Example
DETAIL_LEVEL_ARCHIVE_METADATA) |
(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

{

}
See also
ISimpleIndexProperty :: System
This property indicates that the property is an Enterprise Vault system
property.
See “System properties” on page 664.
Syntax
HRESULT System([out,retval] VARIANT_BOOL* value);
Parameters
Remarks
For custom properties that are added using Add, the value of System is always
false.
Return value
S_OK Success.

property value.
Example
DETAIL_LEVEL_ARCHIVE_METADATA) |
(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA) |
(EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_SYSTEM_INDEXDATA)));

{

bool isSystem = ip.System;

}
See also
ComplianceData object
ComplianceData object
■ IComplianceData
The IComplianceData interface is obtained by using the ComplianceData
property of the IArchiveMetaData interface.
Syntax
interface IComplianceData : IDispatch
Remarks
The IComplianceData interface is for use only with compliance devices.
Member summary
Table 4-37 IComplianceData properties
Value Read/Write Combined with the Units property specifies the duration of
the compliance period.
Units Read/Write Specifies the compliance period units, for example, days,
weeks, months, years.
SetBy Write only Defines where the compliance period is set; the
ComplianceData object, the retention category, or not set.
Example

IComplianceData :: Units
This property, combined with the Value property, specifies the duration of the
compliance period.
Syntax
HRESULT Units([out, retval] EV_STG_API_CP_UNITS* pVal);
HRESULT Units([in] EV_STG_API_CP_UNITS newVal);
Parameters
[out, retval] EV_STG_API_CP_UNITS* pVal Pointer an EV_STG_API_CP_UNITS

enumerated type that contains the
current value of this property
[in] EV_STG_API_CP_UNITS newVal The new value to be set.
Remarks
EV_STG_API_CP_UNITS indicates the units used in specifying the compliance
period.
See “EV_STG_API_CP_UNITS enumeration” on page 62.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or the

value passed in to the property does
not match one of the enumeration
values.
Example


IComplianceData :: Value
This property, combined with the Units property, specifies the duration of the
compliance period.
Syntax
HRESULT Value([out, retval] VARIANT* pVal);
HRESULT Value([in] VARIANT newVal);
Parameters
[out, retval] VARIANT* pVal Pointer to a VARIANT that will hold the current
[in] VARIANT newVal VARIANT containing the new value to set
Remarks
The VARTYPE of the VARIANT should be vt = VT_UI4
For example, for a compliance period of 6 days, Value = 6 and Units =
CP_UNITS_DAYS
Return value
S_OK Success.

or newVal is invalid.
Example


IComplianceData :: SetBy
IComplianceData :: SetBy
This property indicates where the retention period was defined.
Syntax
HRESULT SetBy([in] EV_STG_API_CP_SETBY newVal);
Parameters
[in] EV_STG_API_CP_SETBY newVal EV_STG_API_CP_SETBY containing the new

Remarks
EV_STG_API_CP_SETBY indicates where the compliance retention period is set.
See “EV_STG_API_CP_SETBY enumeration” on page 61.
This property should only be used during a copy/move operation and should not
be called once an item has added to the archive.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Invalid pointer passed to receive

property value,
or the value passed in does not
conform to one of the enumeration
type values.
Holds object
Holds object
■ IHolds
■ IHolds2
These interfaces enable calling applications to place holds on groups of items (to
prevent them from being deleted), remove existing holds and list the holds that
have been placed on items in a vault store.
The IHolds2 interface inherits from IHolds, and provides the method
ReleaseHolds2, which returns information in XML about the success or failure
of removing holds on items in each vault store.
Syntax
interface IHolds : IDispatch
interface IHolds2 : IHolds
About Legal Hold

Legal Hold is the ability to prevent deletion of documents that are relevant to a
legal case; items that are placed on hold cannot be deleted by a user or by
Enterprise Vault (using storage expiry).
Legal Hold functionality is provided by the IHolds and IHold interfaces in the
Content Management API. These interfaces allow Enterprise Vault Accelerator
products and third-party applications to put items on hold, remove holds from
items and enumerate all existing holds on an item.
Existing functionality in Discovery Accelerator allows the administrator to put
items on hold.
Items can be placed on hold by specifying the following:
■ A Consumer ID, to identify the calling application.
■ A Group ID, to identify the group of items with a particular hold applied.
The Group ID could, for example, identify the legal case.
■ Metadata, to provide additional information about the hold.
■ The list of items that the calling application wants to place on hold.
Holds object
The metadata may be useful when there are several consumers of the Legal Hold
API at the same time. For example, metadata could be used to say why one
consumer has put the item on hold, and this information could then be accessed
by other consumers. The metadata is in XML format, for example:
<MetaData>
<Reason Value="John Doe against EG Corp" />
</MetaData>
Using the IItem.Holds property, an application can enumerate all the holds
which have been placed on an item; the API returns a list of holds (Hold IDs) on
that item along with the metadata that was supplied when the item was put on
hold.
Holds may be removed from items in two ways:
■ By specifying the Consumer ID and the Group ID. This will remove all holds
which have been placed on an item with the supplied Consumer ID and
Group ID.
■ By supplying the Consumer ID and a list of Hold IDs of items from which the
consumer wants to remove holds. This allows the consumer to remove
holds from items in batches rather than a whole group at once.
Member summary
Table 4-38 IHolds Properties
_NewEnum This property gives access to an IEnumVariant interface (which

acts an enumerator) and allows script clients to enumerate the
collection of IHold interface pointers and iterate through the
collection using a for...next loop.
Item This property gives access to a particular instance of IHold in the

collection using the index.
Count This read only property returns the number of IHolds in the
collection.
GroupId The GroupId property is set to identify a group of holds placed at

one time. This would typically be an identifier of a particular legal
case, for example. The same GroupId used to place holds can also
be used to release all the holds in that group.
ConsumerGUID The ConsumerGUID is the unique identifier of the application

calling the API.
Holds object
Table 4-38 IHolds Properties
Metadata The metadata property contains the metadata to be passed with

the holds to the Enterprise Vault server. The same metadata will
be applied to each hold in the group.
Table 4-39 IHolds Methods
Method Description
Add Adds an IHold interface pointer to the collection.
PlaceHolds Places a hold on each item in the collection.
ReleaseHolds Releases a hold on each item in the collection.
Table 4-40 IHolds2 Method
Method Description
ReleaseHolds2 Releases a hold on each item in the collection, and returns success
or failure information, in XML format, for each vault store
processed.
Version information
IHolds2 interface requires Enterprise Vault 8.0 SP1.
See also
“Hold object” on page 332
IHolds :: _NewEnum
IHolds :: _NewEnum
used to enumerate the IHolds collection object. This property is hidden in Visual
Basic Scripting Edition (VBScript).
Syntax
Parameters

Remarks
VBScript.
A collection of IHold objects is returned.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive

property value.
Example
foreach (IHold hold in holds)

{
IHolds :: Item
IHolds :: Item
This property gives access to a particular hold in a collection.
Syntax
HRESULT Item([in] VARIANT index;
HRESULT Item([out, retval] LPVARIANT pRetVal);
Parameters
[in] VARIANT index VARIANT holding the value of the index of the
required hold.
[out, retval] LPVARIANT pRetVal Pointer to a VARIANT that will return the
current index value.
Remarks
The VARTPYE of this property should be vt = VT_I4.
Note that the index supplied to the property is 1-based not 0-based.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL,

or data type of variant was incorrect,
or index is out of range.
Example
for (int i = 0; i < holds.Count ; i++)

{
IHold hold = (IHold)holds.Item(i + 1);
IHolds :: Count
IHolds :: Count
This read only property returns the number of Holds in the collection.
Syntax
HRESULT Count([out, retval] long* pRetVal);
Parameters
[out, retval] long* pRetVal Current number of holds in the collection.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL.
Example

{
IHolds :: GroupId
IHolds :: GroupId
This property is set to identify a group of holds placed at one time. This would
typically be an identifier of a particular legal case, for example.
Syntax
HRESULT GroupId([in] BSTR newVal);
HRESULT GroupId([out,retval] BSTR* pVal);
Parameters
[in] BSTR newVal BSTR containing the new group Id.
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the current group Id.
Remarks
The same GroupId used to place holds can also used to release all the holds in
that group.
A GroupId should consist of printable characters and should not contain any of
the following characters: <> & ' "
Return value
S_OK Success.

or newVal contains invalid
characters,
or one or more holds have already
been placed for the current group.
Example
holds.GroupId = “Group 1”;

holds.ConsumerGUID = “{1D938946-329D-4bfa-87FF-9D30B808ADD1}”;
holds.MetaData = “Some metadata”;

IHolds :: GroupId
hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
//add more hold’s if necessary
holds.PlaceHolds();
IHolds :: ConsumerGUID
This property is the unique identifier of the application calling the API.
Syntax
HRESULT ConsumerGUID([in] BSTR newVal);
HRESULT ConsumerGUID([out,retval] BSTR* pVal);
Parameters
[in] BSTR newVal BSTR containing any valid GUID value. Set by caller.
[out,retval] BSTR* pVal Pointer to a BSTR containing the current GUID
Remarks
The value should remain the same for all calls made to the ContentManagement
API by the same calling application.
It must be set before holds can be placed or released.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER PlaceHolds has been called so it is not

possible to change this value or a valid
CLSID could not be obtained from the
BSTR passed in.
Example


hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
holds.PlaceHolds();
IHolds :: Metadata
IHolds :: Metadata
This property contains the metadata to be passed with the holds to the
Enterprise Vault server.
Syntax
HRESULT Metadata([in] BSTR newVal);
HRESULT Metadata([out,retval] BSTR* pVal);
Parameters
[in] BSTR newVal BSTR containing the new MetaData value.
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the current value
of the metadata.
Remarks
The same metadata will be applied to each hold in the group.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER An attempt was made to modify this

property once the PlaceHolds had
been called.
Example


hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
IHolds :: Metadata
holds.PlaceHolds();
IHolds :: Add
IHolds :: Add
This method allows a client to add a new hold to the collection.
Syntax
HRESULT Add([in] IHold* newHold);
Parameters
.[in] IHold* newHold IHold interface pointer to add to the collection.
Remarks
The IHold interface pointer must be obtained through the
IContentManagementAPI property, Hold.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Hold object has been used,

or it has already been added with this
Saveset Id, Transaction Id or Hold Id.
Example


hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
holds.PlaceHolds();
IHolds :: PlaceHolds
This function is used to actually place a hold on each item in the collection.
Syntax
HRESULT PlaceHolds();
Remarks
After the call has been placed, any errors in placing holds are reported in the
Status property of the hold objects in the collection.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed to

receive the property value,
or the hold is already placed, the
groupId is missing, or there is an
error with the ConsumerGUID.


Example


hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);

holds.PlaceHolds();
IHolds :: ReleaseHolds
This function is used to release a hold on each item in the collection.
Syntax
HRESULT ReleaseHolds();
Remarks
The IContentManagementAPI :: DirectoryDNSAlias property should be set by
the caller before releasing holds by GroupId. This is required to identify the
Enterprise Vault server hosting the directory that will be used to enumerate the
Enterprise Vault Storage service computers that the group of holds spans.
When using a GroupId, if any of the holds in the group fail to be released, then
the whole group is considered to have failed.
Note that some holds may actually have been released, but the caller will need to
repeat the release on the group as whole until it succeeds, after establishing the
reason for failure and correcting it.
When not using a GroupId, if the holds are spread over multiple vault stores,
and any of the holds within a vault store fails to be released, all the holds in the
vault store will also be marked as failed. In this case, the caller can interrogate
the Hold objects in the group to find out what went wrong (using the Status
property).
Finally, when all holds in a group are eventually released, then to dispose of the
group itself, you must also call ReleaseHolds( ) specifying the GroupId as before.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointerhas been passed to

receive property value,
or the object has already been used,
or the consumer GUID is incorrect,
or if the groupId has been set then the
DNS alias has not been set.


Example
cmAPI.DirectoryDNSAlias = “SERVER1”;

holds.ReleaseHolds();
IHolds2 :: ReleaseHolds2
This method is similar to ReleaseHolds, in that it can be used to release a hold on
each item in a collection, but this method also returns a summary status report,
in XML, for each vault store in which items were processed.
Syntax
HRESULT ReleaseHolds2([out, retval] BSTR* pVal);
Parameters
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the status report
in XML.
Remarks
The IContentManagementAPI :: DirectoryDNSAlias property should be set by
the caller before releasing holds by GroupId. This is required to identify the
Enterprise Vault server hosting the directory that will be used to enumerate the
Enterprise Vault Storage service computers that the group of holds spans.
When using a GroupId, if any of the holds in the group fail to be released, then
the whole group is considered to have failed.
Note that some holds may actually have been released, but the caller will need to
repeat the release on the group as whole until it succeeds, after establishing the
reason for failure and correcting it.
When not using a GroupId, if the holds are spread over multiple vault stores,
and any of the holds within a vault store fails to be released, all the holds in the
vault store will also be marked as failed.
Finally, when all holds in a group are eventually released, then to dispose of the
group itself, you must also call ReleaseHolds2( ) specifying the GroupId as
before.
The XML returned by the method indicates the success or failure of the action
for each vault store as a whole. In the XML, the vault store is identified by the Id
field, and success or failure of the operation is indicated by the hr field
(HRESULT). If the hold was released successfully on all affected items in a vault
store, then the HRESULT returned for the vault store is 0. If the hold could not
be released on some or all of the affected items in the vault store, then the hr
field contains the error code value.
Version information
ReleaseHolds2 method requires Enterprise Vault 8.0 SP1.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointerhas been passed to

receive property value,
or the object has already been used,
or the consumer GUID is incorrect,
or if the groupId has been set then
the DNS alias has not been set.


Example
cmAPI.DirectoryDNSAlias = “SERVER1”;
IHolds2 holds = (IHolds2)cmAPI.Holds;

holds2.GroupId = “Group 1”;
holds2.ConsumerGUID = “{1D938946-329D-4bfa-87FF-9D30B808ADD1}”;
string xml holds2.ReleaseHolds2();
The following example shows XML returned by ReleaseHolds2. The HRESULT
returned for the second vault store is not zero, indicating that the attempt to
release the hold on items in this vault store failed.
<VaultStores>
<VaultStore Id="16918E349851B39307B57E2FC4603DDB2121
0000VS2.eg.com" hr="0"/>
<VaultStore Id="157E2F1B39307B86918E3498C4603DDB2121
0000VS2.eg.com" hr="0x80040300"/>
<VaultStore Id="1B39307B86918E3498557E2FC4603DDB2121
0000VS.eg.com" hr="0"/>
</VaultStores>
Hold object
Hold object
■ IHold
The IHold interface contains properties that relate to a particular hold placed on
a particular item. It is a collection of IHold interface pointers that are stored in
the IHolds collection.
Syntax
interface IHold : IDispatch
Member summary
Table 4-41 IHold properties
ArchiveId This property specifies the ArchiveID where the item to which this
hold object refers is stored. This property must be set before a hold
is placed or released.
ItemId This property specifies the identifier of the item to which this hold
object refers. This property must be set before a hold is placed.
Id This property identifies the hold object. It is returned once a hold

has been placed, and must be set before a hold can be released.
Status This read only property returns the status of the hold after an
attempt either to place or release a hold.
Metadata This read only property returns the metadata that is stored with
the hold.
ConsumerGUID This read only property returns the unique identifier of the calling
application that placed the hold.
GroupId This read only property returns the identifier of the group of holds
to which the hold belongs.
Remarks
Being derived from IDispatch, this interface can be used by scripting languages.
Hold object
Example
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
IHold :: ArchiveId
IHold :: ArchiveId
This property specifies the ArchiveID of the archive where the item that this
hold object refers to is stored.
Syntax
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the archive Id of
the archive holding the item referred to by this hold.
[in] BSTR newVal BSTR containing the value of the archive Id where
the current item, to which this hold is about to be
applied, is stored.
Remarks
This property must be set before a hold is placed or released.
Return value
S_OK Success.

or the value is not a syntactically
valid Archive Id.
Example
[in]

hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
IHold :: ArchiveId
[out]

{
string archId = hold.ArchiveId;

IHold :: ItemId
IHold :: ItemId
This property specifies the identifier of the item to which the hold object refers.
Syntax
HRESULT ItemId([out, retval] BSTR* pVal);
HRESULT ItemId([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current
item Id held by this hold.
[in] BSTR newVal BSTR containing the item Id to set for this hold.
Remarks
This property must be set before a hold is placed.
The identifier can be a Saveset Id or a Transaction Id.
Return value
S_OK Success.

or value passed in is not a
syntactically valid Saveset Id or
Transaction Id.
Example
[in]

hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
IHold :: ItemId
[out]

{
string itemID = hold.ItemId;

IHold :: Id
IHold :: Id
This property identifies the hold object.
Syntax
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current hold Id.
[in] BSTR newVal BSTR that will contain the new value of the hold Id.
Remarks
The maximum length for this property is 128 characters.
This property is returned after a hold has been placed, and must be set before a
hold can be released.
Return value
S_OK Success.

or newVal is not a syntactically valid
Hold Id.
Example
[in]
hold.Id = 123;
IHold :: Id
holds.Add(hold);
//add more holds
holds.ReleaseHolds;
[out]

{
string ID = hold.Id;
IHold :: Status
IHold :: Status
This property returns the status of the hold after an attempt to either place or
release a hold.
Syntax
HRESULT Status([out, retval] VARIANT* pVal);
Parameters
current status value.
Remarks
The VARTYPE of the variant must be vt = VT_I4
Return value
S_OK Success.

IHold :: Metadata
IHold :: Metadata
This property returns the metadata that is stored with the hold.
Syntax
HRESULT Metadata([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the metadata for this
hold.
Remarks
This property is only populated when the IItem.Get method is called and the
DetailLevel parameter includes the HoldData bit.
Return value
S_OK Success.
Example

{
string metadata = hold.MetaData;

IHold :: ConsumerGUID
IHold :: ConsumerGUID
This property returns the unique identifier of the calling application that placed
the hold.
Syntax
HRESULT ConsumerGUID([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the consumer GUID
of the application that placed the hold.
Remarks
The format of the consumer GUID should be as in the following example:
{3BC4797A-3238-478b-9CA6-5CC9989078DE}
Any other format will generate an error.
Return value
S_OK Success.

or pVal is not a valid GUID.
Example

{
string conGUID = hold.ConsumerGUID;

IHold :: GroupId
IHold :: GroupId
This property returns the identifier of the group of holds to which the hold
belongs.
Syntax
HRESULT GroupId([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current group Id.
Remarks
See “IHolds :: GroupId” on page 319.
Return value
S_OK Success.
Example

{
string groupID = hold.GroupId;

ICollectionBase : IDispatch
ICollectionBase : IDispatch
The ICollectionBase interface provides common collection functionality for
Enterprise Vault API collections, for example, Archives and VaultStores
collections. The interface provides the count of items, a standard COM
enumerator interface, a zero-based array style indexer, and methods to manage
the collection.
Syntax
interface ICollectionBase : IDispatch
Member summary
Count Read only Number of items in the collection.

the collection.
Item Read only Instance of the item at the zero-based index

Maximum Read/Write Maximum number of items in the collection.
More Read only Whether or not there were more items than
Maximum.
Method Description
Version information
■ This interface is available in Enterprise Vault 2007 or later.
ICollectionBase :: Count
ICollectionBase :: Count
This property returns the current number of items in the collection.
Syntax
HRESULT Count([out,retval] long* value);
Parameters
[out,retval] long* value Number of items in the collection.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL.
Example
C#
archives.Get();
for (long i = 0; i < archives.Count; i++)
{
ProcessArchive(archives.Item(i));
ICollectionBase :: _NewEnum
ICollectionBase :: _NewEnum
used to enumerate the collection object. This property is hidden in Visual Basic
Scripting Edition (VBScript).
Syntax
Parameters

Remarks
VBScript.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER enumerator is NULL.
Example
C#
archives.Get();
{
ICollectionBase :: Item
ICollectionBase :: Item
This property returns an instance of the item at the zero-based index into the
collection treated as a virtual array.
Syntax
HRESULT Item([in] long index, [out,retval] IUnknown** item);
Parameters
[in] long index Zero-based index.
[out,retval] IUnknown** item Reference to an instance of the collection.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER item is NULL, or index is invalid.
Example
C#
archives.Get();
{
IArchive archive = (IArchive)archives.Item(i);
ICollectionBase :: Maximum
This property sets the maximum number of items for the collection.
Syntax
HRESULT Maximum([out,retval] long* value);
HRESULT Maximum([in] long value);
Parameters
[out,retval] long* value Maximum number of items in the collection.
[in] long value Required maximum number of items for the

collection.
Remarks
The default value depends on the collection type but the value for both initial
collection types, vault stores and archives, is 5000.
The default value is set to provide reasonable performance together with
reasonable resource usage. Attempting to build large collections may result in
poor performance and failures due to lack of resources, for example, lack of
available memory.
The defaults are as follows:
■ Vault stores 5000
■ Archives 5000
■ Items 10000
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL, or value is invalid.

Example
C#
archives.Maximum = 6000;
archives.Get();
ICollectionBase :: More
ICollectionBase :: More
This property indicates whether there were more items available in the
collection than specified by Maximum.
Syntax
HRESULT More([out,retval] VARIANT_BOOL* value);
Parameters
[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain

true, if there are more items in the collection
than the Maximum number specified. Otherwise
it will contain false.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL.
Example
C#
archives.Maximum = 6000;
archives.Get();
if (archives.More == true)
{
//do something,
ICollectionBase :: Get
This method populates the collection with items that match the selection
criteria up to the maximum number of items specified by Maximum.
Syntax
HRESULT Get(void);
Remarks
Any existing collection is cleared prior to attempting to repopulate the
collection.
Return value
S_OK Success.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The combination of properties used for

the collection selection criteria are
invalid.
See “VaultStores object” on page 94,
“Archives object” on page 109, or
“Items object” on page 162.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently

busy or do not have sufficient
resources to complete the request. The
request should be retried later, if there
are insufficient resources the
maximum number of records
requested should be reduced.
Example
C#
archives.Computer = ""EV1.acme.com";
archives.ArchiveTypes =
EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_SHARED;
archives.Get();
ICollectionBase :: Clear
ICollectionBase :: Clear
This method clears the current collection.
Syntax
HRESULT Clear(void);
Remarks
Clears all items from the current collection setting it back to the empty state;
Count returns zero.
Return value
S_OK Success.
Example
C#
archives.Get();
{
}
//now clear archives before doing another get with different filters
set
archives.Clear();
ICollectionBase :: Reset
ICollectionBase :: Reset
This method resets the collection back to the initial empty state.
Syntax
HRESULT Reset(void);
Remarks
All items are cleared from the current collection, if any, and all selection criteria
properties are reset back to their default empty values.
Return value
S_OK Success.
Examples
C#
archives.Get();
{
}
//now reset archives before doing another get with different filters
set
archives.Reset();
ExtendedErrorInfo object
■ IExtendedErrorInfo
This interface makes available properties that provide additional details about
the return value of the most recent call to a child object of the parent Content
Management API object instance.
Syntax
interface IExtendedErrorInfo : IDispatch
Member summary
Table 4-44 IExtendedErrorInfo properties
Error Read only The Content Management API return

value associated with the most recent
call to a Content Management API
method.
Description Read only The description for the Content

Management API return value.
InnerError Read only The associated internal return value.
InnerErrorDescription Read only The description for the internal return

value.
Source Read only This property is not currently

implemented.
Remarks
The ExtendedErrorInfo object is read-only, and is not updated by any
subsequent Content Management API call — a new instance of the
ExtendedErrorInfo object must be requested from the Content Management API
object.
The inner error can be any Windows or Enterprise Vault COM return value. It is
provided for additional information only; for example, to add to extended
logging details. The list of values is not documented, and it is not guaranteed
that the same error scenario will return the same inner error value with future
versions of Enterprise Vault.
Version information
■ This interface is available from Enterprise Vault 8.0 SP2.
Examples
In the following example, the additional information returned by the
IExtendedErrorInfo interface shows that the Enterprise Vault server is in
Backup Mode:
API Error Code:

0x80040302 (Ref: CONTENTMANAGEMENTAPI_E_BUSY)
API Error Description:

Enterprise Vault is temporarily unable to process the request.
The server is busy, or has insufficient resources, or is only
able to read data due to ongoing backups. Wait a while and then
try again.
EV Internal Error Code:

0xC0041B85 (Ref STORAGE_E_VAULTSTORE_INBACKUPMODE)
EV Internal Error Description:

The Vault Store is currently in Backup Mode.
C++ example
The following example code shows how the ExtendedErrorInfo object is used.
CComPtr<IContentManagementAPI4> pCMAPI;
CComPtr<IItem> pItem;
HRESULT hr = pItem->CopyTo(pDestItem);
if (FAILED(hr))
{
HRESULT hrGLE (S_OK);
CComPtr<IUnknown> pIUnkErrInfo;
hrGLE = pCMAPI->get_LastError(&pIUnkErrInfo);
if (SUCCEEDED(hrGLE))
{
CComQIPtr<IExtendedErrorInfo> pExtErrInfo(pIUnkErrInfo);
if (pExErrInfo != NULL)
HRESULT hrError = S_OK;

HRESULT hrInnerError = S_OK;
CComBSTR bsErrorDesc;
CComBSTR bsInnerErrorDesc;
pExErrInfo->get_Error(&hrError);
pExErrInfo->get_InnerError(&hrInnerError);
pExErrInfo->get_Description(&bsErrorDesc);
pExErrInfo->get_InnerErrorDescription(&bsInnerErrorDesc);
// *** Use error info

AddExtendedErrorToLogFile(L"Failed to copy archived
item", hrError, bsErrorDesc, hrInnerError,
bsInnerErrorDesc);
}
}
}
VBScript example
The following example code shows how the ExtendedErrorInfo object is used.
private Sub ReportCMAPIError(byref ecmAPI)
dim oExtErr
dim szErrorDesc, szInnerErrorDesc
dim vbError, vbExtError
dim Msg
Err.Clear
set oExtErr = ecmAPI.LastError
vbError = oExtErr.Error
vbExtError = oExtErr.InnerError
szErrorDesc = oExtErr.Description
szInnerErrorDesc = oExtErr.InnerErrorDescription
Msg = "***************************" & vbCrLf & vbCrLf

Msg = Msg & "** CM API EXTENDED ERROR INFO" & vbCrLf & vbCrLf
Msg = Msg & " Error Code: 0x" & Hex(vbError) & vbCrLf & vbCrLf
Msg = Msg & " Error Description: " & szErrorDesc & vbCrLf &
vbCrLf
Msg = Msg & " InnerError Code: 0x" & Hex(vbExtError) & vbCrLf &
vbCrLf
Msg = Msg & " InnerError Description: " & szInnerErrorDesc &
vbCrLf & vbCrLf
Msg = Msg & "***************************"
WScript.Echo Msg
Err.Clear
end sub
IExtendedErrorInfo :: Error
IExtendedErrorInfo :: Error
This property provides the Content Management API return value associated
with the most recent call to a Content Management API method.
Syntax
HRESULT Error([out, retval] long* pVal);
Parameters
[out,retval] long* pVal Pointer to a long data type containing the Content
Management API return value.
Remarks
For a list of the return values, see “Content Management API return values” on
page 685.
Return value
S_OK Success.
E_INVALIDARG pVal is Null.

IExtendedErrorInfo :: Description
IExtendedErrorInfo :: Description
This property provides the error description for the Content Management API
return value.
Syntax
Parameters
[out,retval] BSTR* pVal Pointer to a BSTR containing the error description.
Remarks
The error description strings are supplied in English only.
Return value
S_OK Success.
E_INVALIDARG pVal is Null

IExtendedErrorInfo :: InnerError
IExtendedErrorInfo :: InnerError
This property provides the internal return value associated with the most recent
call to a Content Management API method.
Syntax
HRESULT InnerError([out, retval] long* pVal);
Parameters
[out,retval] long* pVal Pointer to a long data type containing the internal return
value.
Remarks
The inner error can be any Windows or Enterprise Vault COM return value. It is
provided for additional information only, for example, to add to extended
logging details.
The list of values is not documented, and it is not guaranteed that the same
error scenario will return the same inner error value with future versions of
Enterprise Vault.
Return value
S_OK Success.

IExtendedErrorInfo :: InnerErrorDescription
IExtendedErrorInfo :: InnerErrorDescription
This property provides the error description for the Enterprise Vault internal
return value.
Syntax
HRESULT InnerErrorDescription([out, retval] BSTR* pVal);
Parameters
[out,retval] BSTR* pVal Pointer to a BSTR containing the error description.
Remarks
The error description strings are supplied in English only.
Return value
S_OK Success.

IExtendedErrorInfo :: Source
IExtendedErrorInfo :: Source
This property provides the GUID of the Content Management API object that
was the source of the error information.
Syntax
HRESULT Source([out, retval] GUID* pVal);
Parameters
[out,retval] GUID* pVal GUID of the Content Management API object.
Remarks
This property is not currently implemented, and returns E_NOTIMPL.
Return value
E_NOTIMPL Not implemented.

DiagnosticsAPI object
DiagnosticsAPI object
■ IDiagnosticsAPI
This interface enables applications to write to Enterprise Vault event log and to
use Enterprise Vault tracing functionality (Dtrace).
Syntax
interface IDiagnosticsAPI : IDispatch
Member summary
Table 4-45 IDiagnosticsAPI properties
Name Read/Write Name of application
Table 4-46 IDiagnosticsAPI methods
Method Description
IsTraceEnabled Test whether trace is enabled for the selected level.
LogEvent Creates an entry in the Enterprise Vault event log.
Trace Traces a message, if trace enabled for the selected level.
Remarks
For a description of the Dtrace utility, see the Enterprise Vault Utilities guide.
Version information
IDiagnosticsAPI : Name
IDiagnosticsAPI : Name
This property holds the name of the application.
Syntax
HRESULT Name([in] BSTR pVal);
Parameters
[out, retval] BSTR* pVal Pointer to a string containing the name of the
application.
[in] BSTR pVal Name of application. Maximum of 50 characters. Default

is “API”.
Remarks
The default value for the Name property is “API”, it is limited to a maximum of
50 characters and is a write-once property. The application name is included in
the event log description logged by the LogEvent method. For example with
Name set to Acme.RM and with the message
“Failed to determine archive.\nIdentity: John Paul Jones\nError:
Entry not found (0x0002)”
then the log entry would appear something like…
Application: Acme.RM
Failed to determine archive.

Identity: John Paul Jones
Error: Entry Not Found (0x0002)
Return value
S_OK Success.
E_POINTER pVal is NULL, or is invalid.
E_ACCESSDENIED The property has already been set.

IDiagnosticsAPI : IsTraceEnabled
IDiagnosticsAPI : IsTraceEnabled
This method tests whether tracing is enabled for the selected level.
Syntax
HRESULT IsTraceEnabled([in] EV_API_TRACE_LEVEL traceLevel,
[out, retval] VARIANT_BOOL* enabled);
Parameters
[in] EV_API_TRACE_LEVEL traceLevel EV_API_TRACE_LEVEL value to check.
[out, retval] VARIANT_BOOL* enabled Whether the trace level is enabled.
Remarks
EV_API_TRACE_LEVEL is an enumerated value that indicates the level of
tracing.
See “EV_API_TRACE_LEVEL enumeration” on page 59.
This method can be used to optimize the cost of building the trace message for
the normal case, where trace is not enabled.
Return value
S_OK Success.
E_POINTER enabled is NULL.

IDiagnosticsAPI : LogEvent
IDiagnosticsAPI : LogEvent
This method creates an entry in the Enterprise Vault event log.
Syntax
HRESULT LogEvent([in] EV_API_EVENT_TYPE eventType,
[in] BSTR message);
Parameters
[in] EV_API_EVENT_TYPE eventType EV_API_EVENT_TYPE value.
[in] BSTR message Message to write.
Remarks
EV_API_EVENT_TYPE is an enumerated value that indicates the type of event.
See “EV_API_EVENT_TYPE enumeration” on page 58.
The events are logged under a single Event Id, 7002. The event source is set to
Enterprise Vault and the event category is determined by the executable logging
the event. If the executable is not an Enterprise Vault executable then the
category is None.
Return value
S_OK Success.
E_INVALIDARG eventType is invalid or message is

NULL.
IDiagnosticsAPI : Trace
This method traces a message, if trace is enabled for the selected level.
Syntax
HRESULT Trace([in] EV_API_TRACE_LEVEL traceLevel,
[in] BSTR message);
Parameters
[in] EV_API_TRACE_LEVEL traceLevel EV_API_TRACE_LEVEL value for trace

level.
[in] BSTR message Trace message.
Remarks
EV_API_TRACE_LEVEL is an enumerated value that indicates the trace level.
See “EV_API_TRACE_LEVEL enumeration” on page 59.
In the trace output, the application name is enclosed in brackets and prefixed to
the trace message content to enable filtering in the DTrace utility. For example
with Name set to the value Acme.RM, the message “Initialization complete”
would appear as:
4553 10:42:04.101 [5016] (AcmeRMServer) <4342> EV:L [Acme.RM]
Initialization complete
Trace messages are captured dynamically by the Enterprise Vault DTrace utility
if the component (that is, the executable) is enabled for tracing within the
utility. The DTrace monitoring level setting for the component determines
whether or not the Trace method generates a trace entry and hence whether or
not the trace message is captured by the DTrace utility as shown in the table
below.
Table 4-47 Mapping of API trace levels to Dtrace monitoring level settings
EV_API_TRACE_LEVEL value: TRACE_LEVEL_ TRACE_LEVEL_ TRACE_LEVEL_

HIGH MEDIUM LOW
Off No No No
DTrace
monitoring Brief Yes No No
level Medium Yes Yes No
setting:
Verbose Yes Yes Yes
The standard coding advice for tracing is to use TRACE_LEVEL_MEDIUM by

default, use TRACE_LEVEL_HIGH to provide a high level view of the application
progress, and reserve use of TRACE_LEVEL_LOW for situations requiring
low-level debugging.
Return value
S_OK Success.
E_INVALIDARG message is NULL.

Chapter 5
NSF Manager API
This chapter describes the Enterprise Vault NSF Manager API, and its interface
and methods.
NSF Manager API

The NSF Manager API interacts with the Content Management API to enable
items in Notes databases to be stored in, or retrieved from, Enterprise Vault
archives.
NSF Manager API creates and uses an NSF database file to hold data being
passed to, or received from, the Content Management API.
The following steps outline how an application might use the NSF Manager and
Content Management API to store a Note in an archive:
■ Use InitializeNotes to initialize the API.
■ Use SwitchToID to set the Notes security context (optional).
■ Use OpenNSF or CreateNSF to open or create an NSF database to hold the
item to be stored.
■ Use ExportNote to export the item from the NSF database to the Content
Management API.
The following Content Management API properties and method can then be
used to store the item in an archive:
■ IContent::Data holds the item content (as a file, or an IStream or
ILockBytes object).
“IContent :: Data” on page 232.
■ IContent::FileExtension defines the type of the item (“dvns” or
IContent.MIMEFormat = “application/x-evnotestream”).
372 NSF Manager API
NSF Manager API
See “IContent :: FileExtension” on page 224 and “IContent ::

MIMEFormat” on page 226.
■ IItem::ArchiveId determines the destination archive for the item.
See “IItem :: ArchiveId” on page 175.
■ IItem::Insert stores the item in the archive.
“IItem :: Insert” on page 196.
■ Use DeleteNote to delete the note from the NSF database (optional).
■ Use CloseNSF to release the open NSF database.
■ Use TerminateNotes to terminate the NSF Manager API.
The following steps outline how an application can use the NSF Manager and
Content Management API to retrieve a Note from an archive and view it in the
Notes client:
■ Use InitializeNotes to initialize the API.
■ Use SwitchToID to set the Notes security context (optional).
■ Use OpenNSF or CreateNSF to open or create an NSF database to hold the
item to be retrieved and viewed.
■ Use ImportNote to import the item from Content Management API to the
NSF database.
The following Content Management API properties and method can be used
to retrieve the item from the archive:
■ IItem::ArchiveId defines the archive where the item is stored.
See “IItem :: ArchiveId” on page 175.
■ IItem::Get retrieves the item from the archive.
■ IContent::Data holds the item content (as a file, or an IStream or
ILockBytes object).
“IContent :: Data” on page 232.
■ IContent::FileExtension specifies the type of the item (“dvns” or
IContent::MIMEFormat = “application/x-evnotestream”).
See “IContent :: FileExtension” on page 224 and “IContent ::
MIMEFormat” on page 226.
■ Use ViewNote to open the item in the Notes client.
■ Use DeleteNote to delete the item from the NSF database (optional).
■ Use CloseNSF to release the open NSF database.
■ Use TerminateNotes to terminate the NSF Manager API.
NSF Manager API 373
NSF Manager API
Components
The NSF Manager API contains one apartment-threaded, automation-friendly
COM class:
■ NSFManager
Security
When you interact with databases on a server, you must use an ID file that has
appropriate permissions.
374 NSF Manager API
Enumerations
Enumerations
This section describes enumerations used by the NSF Manager API.
InitializeNotes enumeration
InitializeNotes is an enumerated value that is used in conjunction with the
InitializeNotes and TerminateNotes methods:
enum EV_NOTES_INIT_MODE
{
EV_NOTES_INIT_APPLICATION,
EV_NOTES_INIT_THREAD
};
NSF Manager API 375
NSFManager object
NSFManager object
The NSFManager object implements the following interface:
■ INSFManager
Syntax
interface NSFManager : IDispatch
Member summary
Method Description
OpenNSF Opens an existing database.
CreateNSF Creates a new database.
CloseNSF Closes the open database and optionally deletes it.
ViewNote Launches the Notes client and opens the specified note.
ImportNote Imports a note from a file, or an IStream or ILockBytes object.
ExportNote Exports a note to a file, or an IStream or ILockBytes object.
DeleteNote Deletes the specified note.
InitializeNotes Initializes the Notes runtime on the main application thread, or on

a worker thread.
TerminateNotes Terminates the Notes runtime on the main application thread, or

on a worker thread.
SwitchToID Switches to the specified ID file.
Requirements
CLSID FBD0FA42-EF3C-4761-B3E4-9C39422273CE
Prog ID KVS.EnterpriseVault.LotusDomino.NSFManager
Type Library EVContentManagementAPILib
DLL KVS.EnterpriseVault.NSFManager.dll
376 NSF Manager API
NSFManager object

Assembly (PIA) KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll

NSF Manager API 377
INSFManager :: OpenNSF
INSFManager :: OpenNSF
This method opens an existing NSF database.
Syntax
HRESULT OpenNSF([in] BSTR bsFilePath);
Parameters
[in] BSTR bsFilePath Specifies the full path to the database.
Return value
S_OK (success) or standard COM error codes.
Example
The following example shows how to use OpenNSF to open a database:
Type type = Type.GetTypeFromProgID(

"KVS.EnterpriseVault.LotusDomino.NSFManager");
INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type);
try
{
nsfMgr.InitializeNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf");
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
}
378 NSF Manager API
INSFManager :: CreateNSF
INSFManager :: CreateNSF
This method creates a new NSF database.
If you supply the name of a template on which to base the new database, the
template must exist on the local machine.
Syntax
HRESULT CreateNSF(
[in] BSTR bsTemplateName,
[in] BSTR bsFilePath);
Parameters
[in] BSTR bsTemplateName The full path and file name of the template on which
you want to base the new database.
[in] BSTR bsFilePath The full path and file name of the new database.
Return value
Example
The following example shows how to use CreateNSF to create a database based
on a specified template:

try
{
nsfMgr.CreateNSF(
@"c:\Program Files\Lotus\Notes\Data\mail8.ntf",
@"c:\DBs\TestDB.nsf");
}
finally
{
}
NSF Manager API 379
INSFManager :: CloseNSF
INSFManager :: CloseNSF
This method closes the open NSF database and optionally deletes it.
Syntax
HRESULT CloseNSF([in] VARIANT_BOOL bDeleteNSF);
Parameters
[in] VARIANT_BOOL bDeleteNSF Use VARIANT_TRUE to delete the database.

Use VARIANT_FALSE to retain the database.
Return value
Example
The following example shows how to use CloseNSF to close a database, without
deleting it:

try
{
}
finally
{
}
380 NSF Manager API
INSFManager :: ViewNote
INSFManager :: ViewNote
This method launches the Notes client and opens the specified note.
Syntax
HRESULT ViewNote([in] ULONG ulNoteId);
Parameters
[in] ULONG ulNoteId The ID of the note, which must exist in the database.
Return value
Example
The following example how to use ViewNote to open a note:

try
{
uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns");
nsfMgr.ViewNote(noteId);
}
finally
{
}
NSF Manager API 381
INSFManager :: ImportNote
INSFManager :: ImportNote
This method imports a note from a file, or an IStream or ILockBytes object.
The note to be imported is in the proprietary Enterprise Vault format, as
returned from the Content Management API or by the ExportNote method.
Syntax
HRESULT ImportNote(
[in] VARIANT vInputNote,
[out, retval] ULONG *pulNoteId);
Parameters
[in] VARIANT vInputNote Variant that contains the data to be

imported.
[out, retval] ULONG *pulNoteId Returns the ID of the imported note.
Return value
Example
The following example how to use ImportNote to import a note:

try
{
uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns");
nsfMgr.ViewNote(noteId);
}
finally
{
}
382 NSF Manager API
INSFManager :: ExportNote
INSFManager :: ExportNote
This method exports a note from the NSF database to a file, or an IStream or
ILockBytes object.
The note exported is in proprietary Enterprise Vault format, and can be passed
to the Content Management API or ImportNote method.
Syntax
HRESULT ExportNote(
[in] ULONG lNoteId,
[in] VARIANT vOutputNote);
Parameters
[in] ULONG ulNoteId The ID of the note.
[in] VARIANT vOutputNote A variant that contains the exported data.
Return value
Example
The following example shows how to use ExportNote to export a note:

try
{
nsfMgr.ExportNote(0x8f6, @"c:\EVNotes\storedNote.dvns");
}
finally
{
}
NSF Manager API 383
INSFManager :: DeleteNote
INSFManager :: DeleteNote
This method deletes the note from the NSF database.
Syntax
HRESULT DeleteNote([in] ULONG ulNoteId);
Parameters
[in] ULONG ulNoteId The ID of the note.
Return value
Example
The following example shows how to use DeleteNote to delete a note:

try
{
nsfMgr.DeleteNote(0x8a6);
}
finally
{
}
384 NSF Manager API
INSFManager :: InitializeNotes
INSFManager :: InitializeNotes
This method initializes the Notes runtime on the main application thread, or on
a worker thread.
The main thread must initialize Notes before any worker threads.
Syntax
HRESULT InitializeNotes([in] EV_NOTES_INIT_MODE initMode);
Parameters
[in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to

initialize on the main application thread or a
worker thread.
Return value
Example
The following example shows how to use InitializeNotes to initialize the Notes
runtime on the main application thread:

try
{
nsfMgr.CreateNSF(
@"c:\Program Files\Lotus\Notes\Data\mail8.ntf",
@"c:\DBs\TestDB.nsf");
}
finally
{
}
NSF Manager API 385
INSFManager :: TerminateNotes
INSFManager :: TerminateNotes
This method terminates the Notes runtime on the main application thread, or on
a worker thread.
Terminate the Notes runtime on the worker threads before the main thread.
Syntax
HRESULT TerminateNotes([in] EV_NOTES_INIT_MODE initMode);
Parameters
[in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to

terminate on the main application thread or a
worker thread.
Return value
Example
The following example shows how to use TerminateNotes to terminate the
Notes runtime:

try
{
}
finally
{
}
386 NSF Manager API
INSFManager :: SwitchToID
INSFManager :: SwitchToID
This method switches to the specified ID file, which is required when you create
an NSF database from a template, or open an NSF database from a remote
server.
Syntax
HRESULT SwitchToID(
[in] BSTR bsIdFilePath,
[in] BSTR bsPassword);
Parameters
[in] BSTR bsIdFilePath The full path and file name of the ID file.
[in] BSTR bsPassword The ID file’s password.
Return value
Example
The following example shows how to use SwitchToID to switch to a specified ID:

try
{
nsfMgr.SwitchToID(
@"c:\Program Files\Lotus\Notes\Data\IDs\user.id",
@"passw0rd");
nsfMgr.OpenNSF(@"DomSvr1/ACME!!mail\user.nsf");
}
finally
{
}
Chapter 6
Retention API
This chapter describes the Enterprise Vault Retention API and its interfaces,
methods and properties.
Retention API
The Retention API enables management of the set of Enterprise Vault retention
categories. An application using the Content Management API to archive items
or an application using the Filtering APIs can use the Retention API to select an
existing retention category, or create a new retention category.
The Retention API enables client applications to:
■ Create a new retention category.
■ Update an existing retention category.
■ Retrieve the details of an existing retention category.
■ Enumerate retention categories.
Components
The API consists of two apartment-threaded, automation-friendly COM classes:
■ RetentionCategories
RetentionCategories implements a collection object of class
RetentionCategory. It implements the IRetentionCategories and
IRetentionCategories2 interfaces. The methods and properties enable the
calling application to enumerate the current list of retention categories and
add new retention categories.
■ RetentionCategory
The RetentionCategory class maintains a collection of RetentionCategory
properties. It implements the IRetentionCategory and IRetentionCategory2
388 Retention API
Retention API
interfaces. The methods and properties enable the calling application to

view and change the various attributes of a retention category.
Security
No special privileges are required to list and read retention categories.
To create or update retention categories requires that the API is run under the
Vault Service Account, or an account that is in a suitable Enterprise Vault
roles-based administration role that includes the role task “EVT Administer
Enterprise Vault Retention Categories”.
Retention API 389
Enumerations
Enumerations
This section describes enumerations used by the Retention API.
Retention Units enumeration

The RetentionUnits value indicates the type of units used to define the retention
period.
enum _RetentionUnits {
Days = 0,
Weeks = 1,
Months = 2,
Years = 3
};
Retention Date Basis enumeration

The RetentionDateBasis value indicates the date from which to calculate the
storage expiry date of an item.
enum _RetentionDateBasis {
ExpiryBasisArchiveDate = 0,
ExpiryBasisModifiedDate = 1,
ExpiryBasisInherit = 2,
ExpiryBasisUnknown = 3
} ;
ExpiryBasisInherit takes the value set for the Enterprise Vault site.
The retention category cannot be saved or updated if the value set is
ExpiryBasisUnknown.
390 Retention API
RetentionCategories object
The RetentionCategories object implements the following interfaces:
■ IRetentionCategories
■ IRetentionCategories2 (default)
The interfaces implement a collection object for the creation and enumeration
of RetentionCategory objects.
The IRetentionCategories2 interface inherits the properties and methods of the
IRetentionCategories interface, and also provides a Get method to retrieve the
properties of a retention category.
Syntax
interface IRetentionCategories : IDispatch
interface IRetentionCategories2 : IRetentionCategories
Member summary
Table 6-1 IRetentionCategories properties
Count Read only The number of retention categories in the

collection.
_NewEnum Read only An IEnumVariant interface pointer that is

used to enumerate the collection of
retention categories.
Item Read/Write This property returns the nth retention

category object in the collection.
DirectoryDNSAlias Write only Identifies an Enterprise Vault server

running an Enterprise Vault Directory
Service.
Retention API 391
Table 6-2 IRetentionCategories methods
Method Description
Lookup Retrieve limited details of a retention category.

This method is deprecated, as it does not return all available
properties. Use the Get method to retrieve all properties of a
retention category.
Create Create a new retention category.

This method is deprecated, as it does not enable values to be
specified for all available properties. Use the Add method
Add Add a retention category to the collection. This is the preferred

method for creating a new retention category.
Update Update details of an existing retention category.
Table 6-3 IRetentionCategories2 method
Method Description
Get Retrieve details of a retention category.
Remarks
To ensure all available retention category properties can be retrieved, use the
Add method to create a new retention category, and the Get method to retrieve
details of a retention category.
The DirectoryDNSAlias property identifies an Enterprise Vault server that can
be used to access the Enterprise Vault Directory for retention category
information.
392 Retention API
Requirements
CLSID 744FC7D7-6933-4696-AC3F-9EFC1E00C96B
Prog ID EnterpriseVault.RententionCategories
Type Library RetentionAPILib
DLL EVRetentionAPI.dll

Assembly (PIA) KVS.EnterpriseVault.Interop.RetentionAPI.dll

Retention API 393
IRetentionCategories :: Count
IRetentionCategories :: Count
This property returns the number of retention categories in the collection.
Syntax
HRESULT Count([out, retval] long *plCount);
Parameters
[out, retval] long *plCount Pointer to a long that will contain the current value.
Return value
S_OK Success.
E_POINTER The plCount pointer is NULL.
Examples
The following example Visual Basic script enumerates the available retention
categories.
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg
Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")

if Err.Number <> 0 then
MsgBox(Err.Description)
else
oRCs.DirectoryDNSAlias = "EVSite"
MsgBox("There are " & oRCs.Count & " categories")
For Each oRC In oRCs
sMsg = "Category is " & oRC.Name & " ; IsVisible=" &
oRC.IsVisible & " ;
OnHold=" & oRC.OnHold & " ; Locked=" & oRC.Locked
MsgBox(sMsg)
sNames = sNames & " " & oRC.Name
Next
set oRCS = Nothing
MsgBox("The list is: " & sNames)
end if
394 Retention API
IRetentionCategories :: _NewEnum
used to enumerate the collection of retention categories. This property is hidden
in Visual Basic and Visual Basic Scripting Edition (VBScript).
Syntax
Parameters

Remarks
is automatically used internally when you use the For Each construct in .NET
managed code or VBScript.
This property returns a collection of RetentionCategory objects.
Return value
S_OK Success.
E_POINTER The pointer to the IUnknown pointer passed to the property

is invalid.
Example
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

else
oRCs.DirectoryDNSAlias = "EVSite"
Retention API 395

oRC.IsVisible & " ;
OnHold=" & oRC.OnHold & " ; Locked=" & oRC.Locked
MsgBox(sMsg)
Next
set oRCS = Nothing
end if
396 Retention API
IRetentionCategories :: Item
IRetentionCategories :: Item
This property returns the nth retention category object in the collection.
Syntax
propget] HRESULT Item([in] long index, [out, retval] VARIANT* pVal);
Parameters
[in] long Index Long containing the index value of the required
item. The index is 1-based.
retention category interface pointer requested.
Remarks
This method enables an alternative method of enumerating the retention
categories in the collection.
Return value
S_OK Success.
E_POINTER pVal is an invalid pointer.
E_INVALIDARG Index is less than or greater than the collection count.
Example
IRetentionCategories retCats = (IRetentionCategories) new
RetentionCategoriesClass();
retCats.DirectoryDNSAlias = “SERVER1”;
for (int i = 0; i < retCats.Count; i++)

{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
1);
Retention API 397
IRetentionCategories :: DirectoryDNSAlias
This property is used to identify a computer running an Enterprise Vault
Directory Service, in order to retrieve information from the Enterprise Vault
Directory.
Syntax
HRESULT DirectoryDNSAlias([in] BSTR bstrVal);
Parameters
[in] BSTR bstrVal The value can be any one of the following:
■ DNS alias of a computer hosting an Enterprise Vault
Directory Service.
■ IP address of a computer hosting an Enterprise Vault
Directory Service.
■ Id of the Enterprise Vault Site.
■ Id of any archive in the Site.
■ Id of any vault store in the Site.
Remarks
If you do not set DirectoryDNSAlias, then connection to the local computer is
assumed.
Return value
S_OK Success.
E_UNEXPECTED An unexpected error has occurred.

398 Retention API
SiteIdNotFound bstrValue does not identify an existing site.
Examples
The following example sets a value for DirectoryDNSAlias in order to list
retention categories on a remote Enterprise Vault server.
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

else
oRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"
oRC.IsVisible & " ; OnHold=" & oRC.OnHold & " ;
Locked=" & oRC.Locked
MsgBox(sMsg)
Next
set oRCS = Nothing
end if
Retention API 399
IRetentionCategories :: Lookup
This method is used to obtain details of a retention category when the Name or
Id of the retention category is known.
As this method does not return all available retention category properties, we
recommend that you use the Get method instead.
Syntax
HRESULT Lookup([in] BSTR NameOrId,
[out] VARIANT *Period,
[out] VARIANT *Units,
[out] VARIANT *IsVisible,
[out] VARIANT* Id,
[out] VARIANT* RCName,
[out, retval] VARIANT* RCFound);
Parameters
.[in] BSTR NameOrId String containing name or Id of the retention

category.
[out] VARIANT *Period Value of Period for the retention category. This
is the number of retention units an item is to be
retained.
[out] VARIANT *Units Value of Units for the retention category. This
is the type of retention units (days, weeks,
months, years).
[out] VARIANT *IsVisible Value of IsVisible for the retention category.

Describes whether the retention category is to
be displayed to end users.
[out] VARIANT* Id Identifier of the retention category.
[out] VARIANT* RCName Name of the retention category. Identifies the

retention category to the end user and the
administrator.
[out, retval] VARIANT* RCFound A boolean return value that indicates whether
or not the lookup was successful.
400 Retention API
Return value
S_OK Success.
Examples
The following example Visual Basic script looks up the values assigned to the
Public retention category.
Dim oAPI
Dim msg
Set oAPI = CreateObject("EnterpriseVault.RetentionCategories")
Dim id, name, units, period, isvisible
oAPI.Lookup "Public", period, units, isvisible, id, name

set oAPI = Nothing
msg = msg & " name = " & name

msg = msg & " period = " & period
msg = msg & " units = " & units
msg = msg & " isvisible = " & isvisible
msg = msg & " id = " & id
Msgbox(msg)
Retention API 401
IRetentionCategories :: Create
This method is used to create a new retention category.
As this method does not allow the specification of all available retention
category properties, we recommend that you use the Add method instead.
Syntax
HRESULT Create([in] BSTR Name,
[in] LONG Period,
[in] RetentionUnits Units,
[in] VARIANT_BOOL IsVisible,
[in] BSTR Description,
[out,retval] BSTR* Id);
Parameters
.[in] BSTR Name The name of the retention category.
[in] LONG Period Number of retention units items are to be

retained.
[in] RetentionUnits Units Enumeration value for type of retention units

(days, weeks, months, years).
See “Retention Units enumeration” on
page 389.
[in] VARIANT_BOOL IsVisible Determines whether or not the retention

category will be available to users for selection
in manual archive operations.
[in] BSTR Description Description of the retention category.
[out,retval] BSTR* Id Retention category Id.
Remarks
If the value of Period is 999999, and the value of Units is Years, the retention
period is “forever”.
If IsVisible is false, the retention category is still visible in the Enterprise Vault
This method does not allow you to set a specific value for the ExpiryBasis
property; the default value for the Enterprise Vault site will be used.
402 Retention API
Return value
S_OK Success.
E_INVALIDARG One of the parameters is incorrect.
RetentionCategoryAlreadyExists A retention category with the same name already exists
Example
retCats.Create(“New business”,10, RetentionUnits.Months, false,

“New business correspondence”);
Retention API 403
IRetentionCategories :: Add
This is the preferred method for creating a new retention category and adding it
to the collection object.
Syntax
HRESULT Add([in] IUnknown* RetentionCategory);
Parameters
.[in] IUnknown* RetentionCategory A reference to a RetentionCategory object.
Remarks
An error will be returned if a retention category already exists with the same
name.
period is “for ever”.
Return value
S_OK Success.
E_INVALIDARG One of the properties of the IRentionCategory pointer is

invalid.
E_NOINTERFACE There is a problem with the IRetentionCategory pointer

passed into the method.
RetentionCategoryAlreadyExists A retention category with the same name already exists
Examples
The following example Visual Basic script adds two new retention categories:
Finance and Legal.
Dim oRCS
Dim oRC
Set oRCS = CreateObject("EnterpriseVault.RetentionCategories")

404 Retention API
'Create a Retention Category
Set oRC = Nothing

Set oRC = CreateObject("EnterpriseVault.RetentionCategory")
oRC.Name = "Finance"
oRC.Description = "For finance dept items"
oRC.Units = 3
oRC.Period = 6
oRC.IsVisible = True
oRC.OnHold = False
oRC.Locked = False
oRCS.Add(oRC)
msgbox(oRC.identifier)
'Create another Retention Category
Set oRC = Nothing

Set oRC = CreateObject("EnterpriseVault.RetentionCategory")
oRC.Name = "Legal"
oRC.Description = "For legal department items"
oRC.Units = 3
oRC.Period = 7
oRC.IsVisible = False
oRC.OnHold = True
oRC.Locked = True
oRCS.Add(oRC)
msgbox(oRC.identifier)
Retention API 405
IRetentionCategories :: Update
This method is used to change an existing retention category.
Syntax
HRESULT Update([in] IUnknown* RetentionCategory);
Parameters
.[in] IUnknown* RetentionCategory Reference to the RetentionCategory object to

be updated.
Remarks
Any changes that you make to a retention category will be retrospective, and be
applied to unexpired items that have been archived with the retention category.
An error will be returned if the retention category specified does not exist.
Return value
S_OK Success.
E_INVALIDARG One of the properties of the IRetentionCategory pointer

passed as a parameter is invalid.
RetentionCategoryNotExist The retention category does not exist.
Examples
The following example updates details of retention categories on a remote
computer and sets all the retention categories on hold.
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

406 Retention API
else
oRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"
oRC.IsVisible & " ; OnHold=" & oRC.OnHold & " ;
Locked=" & oRC.Locked
MsgBox(sMsg)
oRC.OnHold = true
oRCs.Update(oRC)
Next
set oRCS = Nothing
end if
Retention API 407
IRetentionCategories2 :: Get
IRetentionCategories2 :: Get
This is the preferred method for obtaining details of a retention category. It
returns a populated instance of the RetentionCategory object.
Syntax
HRESULT Get([in] BSTR NameOrId,
[out, retval] IUnknown** RetentionCategory);
Parameters
[in] BSTR NameOrId String containing name or Id of the retention

category.
Remarks
This method supercedes the Lookup method as it enables the retrieval of all
available retention category properties, including the ExpiryBasis property.
Return value
S_OK Success.
E_INVALIDARG NameOrId is NULL or RetentionCategory is NULL.
RetentionCategoryNotExist A Retention Category with the given NameOrId value does

not exist.
Example
IRetentionCategories2 retCats2 = (IRetentionCategories2) new
IRetentionCategory retcat =
(IRetentionCategory)retCats2.Get(“Business”);
408 Retention API
RetentionCategory object
The RetentionCategory object implements the following interfaces:
■ IRetentionCategory
■ IRetentionCategory2 (default)
The interfaces maintain a set of properties for a RetentionCategory object. The
IRetentionCategory2 interface inherits the properties and methods of the
IRetentionCategory interface, and also provides the ExpiryBasis property.
Syntax
interface IRetentionCategory : IDispatch
interface IRetentionCategory2 : IRetentionCategory
Member summary
Table 6-4 IRetentionCategory properties
Period read/write This property describes the number of retention

units (days, weeks, months, years) an item is to be
retained.
Units read/write This property describes whether the period has been
expressed in days, weeks, months or years.
IsVisible read/write This property describes whether the category is to be

displayed to end users.
Identifier read/write This property uniquely identifies the retention

category.
Name read/write This property identifies the retention category to the

end user and the administrator.
Description read/write This property describes the retention category to the

administrator.
OnHold read/write This property describes whether archived items with

a particular retention category can be deleted or
expired. This protection applies during the retention
period, and also after the retention period has
expired.
This retention category hold is different from the
Legal Hold API.
Retention API 409
Table 6-4 IRetentionCategory properties
Locked read/write This property enables a lock to be put on a retention

category. This prevents an administrator from
inadvertently modifying the retention category.
Table 6-5 IRetentionCategory2 property
ExpiryBasis read/write This property indicates the date from which to

calculate the storage expiry date of an item.
Remarks
A RetentionCategory pointer can either be obtained using CoCreateInstance (or
the equivalent in .NET or Visual Basic), or by obtaining one from the collection
held in an instance of RetentionCategories.
Requirements
CLSID 333D8892-6804-4090-942B-43909C498951
Prog ID EnterpriseVault.RetentionCategory
410 Retention API
IRetentionCategory :: Period
This property describes the number of retention units (days, weeks, months,
years) an item is to be retained.
Syntax
HRESULT Period([out, retval] long* pVal);
HRESULT Period([in] long newVal);
Parameters
[out, retval] long* pVal Reference to the number of retention units (days,
weeks, months, years) an item is to be retained.
[in] long newVal The range of permitted values is from 1 to 999999

inclusive.
Remarks
Return value
S_OK Success.
E_INVALIDARG newVal is outside the bounds of the permitted range (1 -

999999)
Example
[in]
IRetentionCategories retcats = (IRetentionCategories) new

IRetentionCategory retcat = (IRetentionCategory) new

RetentionCategoryClass();
Retention API 411
retcat.Name = “Finance”;
retcat.Description = “For finance depts”;
retcat.Identifier = “xyz”;
retcat.Units = RetentionUnits.Months;
retcat.Period = 10;
retcat.IsVisible = true;
retcat.OnHold = true;
retcat.Locked = true;
retCats.Add(retCat);
[out]


{
1);
string name = retCat.Name;

string descr = retCat.Description;
string ident = retCat.Identifier;
RetentionUnits ru = retCat.Units;
long period = retCat.Period;
bool isVis = retCat.IsVisible;
bool onHold = retCat.OnHold;
bool locked = retCat. Locked;
412 Retention API
IRetentionCategory :: Units
This property describes whether the period is expressed in days, weeks, months
or years.
Syntax
HRESULT Units([out, retval] RetentionUnits* pVal);
HRESULT Units([in] RetentionUnits newVal);
Parameters
[out, retval] RetentionUnits* pVal Enumerated value for type of retention

units (days, weeks, months, years).
See “Retention Units enumeration” on
page 389.
[in] RetentionUnits newVal RetentionUnits enumerated value.
Remarks
Return value
S_OK Success.

999999)
Example
[in]

Retention API 413

retcat.Period = 10;
[out]


{
1);

414 Retention API
IRetentionCategory :: IsVisible
This property describes whether the retention category is to be displayed to end
users.
Syntax
HRESULT IsVisible([out, retval] VARIANT_BOOL* pVal);
HRESULT IsVisible([in] VARIANT_BOOL newVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Reference to current value.
[in] VARIANT_BOOL newVal New value.
Remarks
All retention categories are visible to administrators in the Administration
Console, even if this the value of this property is FALSE.
Return value
S_OK Success.

999999)
Example
[in]


Retention API 415

retcat.Period = 10;
[out]


{
1);

416 Retention API
IRetentionCategory :: Identifier
This parameter uniquely identifies the retention category.
Syntax
HRESULT Identifier([out, retval] BSTR* pVal);
HRESULT Identifier([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to a string containing the retention category
Id.
[in] BSTR newVal String containing retention category Id (up to 250

Unicode characters).
Return value
S_OK Success.
Example
[in]


retcat.Period = 10;
Retention API 417
[out]


{
1);

418 Retention API
IRetentionCategory :: Name
This parameter identifies the retention category to end users and the
administrator.
Syntax
HRESULT Name([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal The current retention category name.
[in] BSTR newVal New retention category name.

Maximum length is 32 unicode characters.
Return value
S_OK Success.
Example
[in]


retcat.Period = 10;
Retention API 419
[out]


{
1);

420 Retention API
IRetentionCategory :: Description
IRetentionCategory :: Description
This property describes the retention category to the administrator.
Syntax
HRESULT Description([in] BSTR newVal);
Parameters
[out, retval] BSTR* pVal Pointer to description of retention category.
[in] BSTR newVal New description of retention category.

Maximum length is 127 unicode characters.
Remarks
When creating a retention category, this property must be set. The value cannot
be an empty string.
Return value
S_OK Success.
E_INVALIDARG newVal is either an empty string or is greater than 127

characters in length.
Retention API 421
IRetentionCategory :: OnHold
This property describes whether archived items with a particular retention
category can be deleted or expired. This protection applies during the retention
period, and also after the retention period has expired.
While this property remains true, neither users nor Enterprise Vault storage
expiry can delete items that have been stored using this retention category.
Syntax
HRESULT OnHold([out, retval] VARIANT_BOOL* pVal);
HRESULT OnHold([in] VARIANT_BOOL newVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL containing

the current value.
Remarks
This retention category hold is different from the Legal Hold feature described
in “About Legal Hold” on page 313.
Return value
S_OK Success.
Example
[in]


422 Retention API
retcat.Period = 10;
[out]


{
1);

bool locked = retCat.Locked;
Retention API 423
IRetentionCategory :: Locked
This property enables a lock to be put on a retention category. This prevents an
administrator from inadvertently modifying the retention category.
Syntax
HRESULT Locked([out, retval] VARIANT_BOOL* pVal);
HRESULT Locked([in] VARIANT_BOOL newVal);
Parameters
[out, retval] VARIANT_BOOL* pVal Pointer to current value.
Remarks
In the Administration Console, this lock feature can be controlled using the
checkbox, Lock this Retention Category, in the retention category properties.
Return value
S_OK Success.
Example
[in]


424 Retention API
retcat.Period = 10;
[out]


{
1);

bool locked = retCat.Locked;
Retention API 425
IRetentionCategory2 :: ExpiryBasis
This property indicates the date from which storage expiry is calculated.
Syntax
HRESULT ExpiryBasis([out, retval] RetentionDateBasis* pVal);
HRESULT ExpiryBasis([in] RetentionDateBasis newVal);
Parameters
[out, retval] RetentionDateBasis* pVal Enumeration value for date used to

calculate storage expiry.
See “Retention Date Basis
[in] RetentionDateBasis newVal RetentionDateBasis enumeration

value.
Remarks
To retrieve the value of this property use the Get method; it is not returned by
the Lookup method.
Return value
S_OK Success.
E_INVALIDARG newVal is outside the bounds of the permitted range.
Example
[in]

426 Retention API
IRetentionCategory2 retcat2 = (IRetentionCategory2) new

retcat2.Name = “Finance”;
retcat2.Description = “For finance depts”;
retcat2.Identifier = “xyz”;
retcat2.Units = RetentionUnits.Months;
retcat2.Period = 10;
retcat2.IsVisible = true;
retcat2.OnHold = true;
retcat2.Locked = true;
retcat2.ExpiryBasis = RetentionDataBasis. ExpiryBasisArchiveDate;
[out]


{
IRetentionCategory2 retCat = (IRetentionCategory2)retcats.Item(i
+ 1);
string name = retCat2.Name;

string descr = retCat2.Description;
string ident = retCat2.Identifier;
RetentionUnits ru = retCat2.Units;
long period = retCat2.Period;
bool isVis = retCat2.IsVisible;
bool onHold = retCat2.OnHold;
bool locked = retCat2.Locked;
RetentionDataBasis rdb = retCat2.ExpiryBasis;
Chapter 7
Filtering APIs
This chapter describes the following APIs available for adding proprietary
external filters to Enterprise Vault archiving tasks:
■ Exchange Filtering API
■ Domino Filtering API
About the Filtering APIs

Filtering involves selecting specific items according to set criteria, and
performing certain actions on those items. Items may be selected using
attributes such as author, message recipients, subject, or a combination of
attributes. Actions could include, for example, archiving the item with a specific
retention category, or storing the item in a particular archive. Other actions
could include deleting the item, or removing attachments.
Enterprise Vault includes generic filters for Exchange Server archiving and
Domino Server archiving. To use these generic filters, you do not require access
to the Enterprise Vault API. For an overview of filtering, and instructions on
how to configure the generic Enterprise Vault filters, see the Configuring custom
filtering section in the following manuals:
Setting Up Exchange Server Archiving
Setting Up Domino Server Archiving
The Enterprise Vault Filtering APIs provide a "plug-in" interface that enables
you to develop proprietary filters that perform a wider range of tasks than is
possible using the generic filters. For example, you may want to collect statistics
on particular item types, classify items based on metadata or content, or add
proprietary information to items as they are archived.
The Exchange Filtering API, is presented as a set of COM interfaces. This API can
be used to develop proprietary filters for the following archiving tasks:
■ Exchange Mailbox task
428 Filtering APIs
About the Filtering APIs
■ Exchange Journaling task

■ Exchange Public Folder task
The Domino Filtering API, is presented as a set of .NET interfaces. This API can
be used to develop proprietary filters for the Domino Journaling task.
You can configure multiple filters for a particular type of archiving; the
associated archiving task will process these in order.
You enable filtering by configuring registry settings for the associated archiving
task.
The following points summarize the steps you need to take to configure
filtering:
■ Develop your filter class using the API interfaces described in this chapter.
In the filter you can use the Content Management DiagnosticsAPI class to
add tracing and event logging.
See “DiagnosticsAPI object” on page 364
■ Configure the appropriate filtering registry settings for the archiving tasks
that you want to perform filtering. The registry settings enable filtering for
the archiving task and define the external filters to process.
Details of the registry settings are given in the following sections:
“Exchange filtering registry settings” on page 430
“Domino filtering registry settings” on page 474
■ Restart the associated archiving tasks.
Details of the filtering APIs are given in the following sections:
■ “Exchange Filtering API” on page 429
■ “Domino Filtering API” on page 473
Filtering APIs 429
Exchange Filtering API

The Exchange Filtering API provides a mechanism for COM components to be
loaded by the appropriate Exchange archiving task, and called on a per-message
basis during the archiving process.
Figure 7-1 Overview of Exchange filtering
The figure, “Overview of Exchange filtering”, illustrates how Enterprise Vault

implements Exchange external filters:
■ If the registry settings are configured to enable filtering for the Exchange
Mailbox, Journaling or Public Folder tasks, the task calls the task filter
controller when processing a message.
■ The task filter controller invokes the first external filter, which implements
the IExternalFilter interface.
■ The external filter calls the IArchivingControl3 interface, which is
implemented by the task filter controller, to retrieve information about the
message.
430 Filtering APIs
■ The filter processes the message synchronously, using the methods and
properties of the IArchivingControl3 interface to set properties that define
how the Exchange archiving task is to process the message.
■ Provided the stopFiltering parameter is not set to TRUE, each filter is
applied in turn to the message.
■ After the message has been processed by all of the registered filters, the task
filter controller then invokes the FilteringComplete method for each filter.
This enables the filter to tidy up and release any resources used while
processing the message.
■ The Exchange archiving task then completes archiving the message, as
modified by the external filters and also taking account of any archiving
actions set by the external filters.
Developing Exchange external filters
Note: External filters for Exchange filtering must be developed in unmanaged

code. This is because the Enterprise Vault Exchange archiving tasks are written
in an unmanaged language and Microsoft has not implemented a managed
(.NET) MAPI library.
A filter should be implemented as an apartment-threaded, in-process COM

server that references the following libraries:
■ Enterprise Vault External Filtering Type Library
■ Enterprise Vault Archiving Control Type Library
To develop a filter for Exchange filtering, you need to obtain and install the
appropriate Enterprise Vault archiving license.
Exchange filtering registry settings

Filtering for Enterprise Vault Exchange Mailbox, Journaling, and Public Folder
tasks is enabled using registry settings under the following registry key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
You add a new key to specify the type of archiving task that is to perform the
filtering. The key can be one of the following:
■ Mailbox
■ Journaling
Filtering APIs 431
■ PublicFolder
For example, to add filtering for the Exchange Mailbox archiving tasks, you add
the Mailbox key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
You then add a string value to the Mailbox key for each of the required external
filters. For the name of each filter entry, use the values, 1, 2, 3 and so on. If there
are multiple filters, the filter names should form an unbroken numerical
sequence. The filters are applied in numerical order. If one number is missing,
no further filters are applied.
Note: When configuring filtering for Exchange journaling tasks, if the

Compliance Accelerator Journaling Connector filter exists, it must be last in the
sequence.
For the value of each filter entry give the ProgID (that is, the
ProjectName.ClassName of the COM class implementing IExternalFilter for
this particular filter). For example, the value for the generic Enterprise Vault
filter for Exchange Server filtering is EnterpriseVault.CustomFilter.
The following example shows three external filters that have been configured
for the Exchange Mailbox archiving tasks.
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
1 = ACompany.Filter1
In this case, filter 1 is applied and then filter 2. However, filter processing stops
after filter 2 because the filter name sequence is broken.
The following optional DWORD values can also be created to control filtering:
■ Override — This setting has the following effect:
■ Exchange Journaling tasks. If created under the Journaling key, and
given the value, 1, this setting forces the Exchange Journaling tasks to
retry messages that were marked as MARK_DO_NOT_ARCHIVE by a
previous filter.
432 Filtering APIs
If the value is 0, or the setting does not exist, the Exchange Journaling
tasks do not retry messages that are marked as
MARK_DO_NOT_ARCHIVE.
■ Exchange Mailbox and Public Folder tasks. If created under the Maibox
or PublicFolder keys, and given the value, 1, this setting turns off
custom filtering.
If the value is 0, or the setting does not exist, the archiving tasks
implement the configured custom filters.
■ MoveOnFilterFailure — This can be set for Exchange Journaling tasks or
Exchange Mailbox tasks. If this setting has the value 1, and an unhandled
error occurs in the external filter, the message involved is moved to the
folder, Failed external filter. This folder is created automatically if it does
not exist.
If the value is 0, or the setting does not exist, the archiving tasks take the
following action:
■ Exchange Journaling task. When an unhandled error occurs in the
external filter, the task moves the associated messages to the folder,
Enterprise Vault Journaling Service\Invalid Journal Report
in the journal mailbox.
■ Exchange Mailbox task. When an unhandled error occurs in the
external filter, the archiving task does not move the associated
messages. The task tries to process the messages during each archiving
run
In the following example, the Override and MoveOnFilterFailure settings
have been created under the Mailbox registry key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
Override = 0
MoveOnFilterFailure = 1
If you make changes to the custom filtering registry settings, restart the
associated archiving tasks to implement the changes.
For further details of the filtering registry settings, see the Configuring custom
filtering chapter in the the manual, Setting Up Exchange Server Archiving.
Filtering APIs 433
Enumerations (Exchange filtering)

This section lists the enumerations for the Exchange Filtering API.
EV_ACTION enumeration
The following enumeration values are defined for EV_ACTION:
enum EV_ACTION
{
NO_ACTION = 0,
ARCHIVE_ITEM = 1,
MARK_DO_NOT_ARCHIVE = 2,
MOVE_DELETED_ITEMS = 3,
HARD_DELETE = 4,
REQUEST_SHUTDOWN = 5
};
The default value is ARCHIVE_ITEM.
When the task is running in report mode the action is ignored.
EV_ATTACHMENT_ACTION enumeration
The following enumeration values are defined for EV_ATTACHMENT_ACTION:
enum EV_ATTACHMENT_ACTION
{
NO_ATTACHMENT_ACTION = 0,
DELETE_ATTACHMENT = 1,
REPLACE_ATTACHMENT = 2
};
If the attachment action is to replace attachments, users will see a file called
Deleted Attachments.txt attached to messages that have had
attachments deleted by the filter. When they open this file, it contains a list of
the names of files that have been deleted.
The contents of this file are taken from the file,
CF_Replace_Attachment.txt, in the Enterprise Vault program folder
(typically, C:\Program Files\Enterprise Vault). If required, you can
modify the text of this file. For example, you may want to localize the
descriptive text.
EV_RETRY_STATUS enumeration
The following enumeration values are defined for EV_RETRY_STATUS:
enum EV_RETRY_STATUS
{
UNKNOWN_IF_RETRY = 0,
IS_NOT_RETRY = 1,
IS_A_RETRY = 2
434 Filtering APIs
};
UNKNOWN_IF_RETRY does not indicate an error; it indicates that the task
could not determine if the status was a retry. For example, this may be returned
if the archiving task does not support detecting retries. Filters should interpret
an UNKNOWN_IF_RETRY status as IS_NOT_RETRY.
EV_REARCHIVE_STATUS enumeration
The following enumeration values are defined for EV_REARCHIVE_STATUS:
enum EV_REARCHIVE_STATUS
{
UNKNOWN_IF_REARCHIVE = 0,
IS_NOT_REARCHIVE = 1,
IS_A_REARCHIVE = 2
};
UNKNOWN_IF_REARCHIVE does not indicate an error; it indicates that the task
could not determine if the status was a re-archive. For example, this may be
returned if the archiving task does not support detecting re-archives. Filters
should interpret an UNKNOWN_IF_REARCHIVE status as IS_NOT_REARCHIVE.
Message direction enumeration

The following enumeration values are defined for MSG_DIRECTION:
public enum MSG_DIRECTION
{
DIRECTION_UNDEFINED = 0,
DIRECTION_INTERNAL = 1,
DIRECTION_EXTERNAL_IN = 2,
DIRECTION_EXTERNAL_OUT = 3
}
Filtering APIs 435
IExternalFilter interface
An external filter implements the following interface:
■ IExternalFilter
Syntax
interface IExternalFilter : IDispatch
Member summary
Method Description
Initialize This method is called during Exchange archiving task initialization.
ProcessFilter This method is called per-message during the archiving process. The
ProcessFilter method is where you process the message to your
requirements.
FilteringComplete This method is called after all filters have been processed for the
current item.
Remarks
The external filter must implement the COM interface, IExternalFilter, which is
called by the task filter controller.
All methods must be implemented, even if they return only S_OK.
If the filter makes changes to the message, and the changes are to be reflected in
the Exchange Server store or the Enterprise Vault archive or both, then call the
IArchivingControl2 :: MAPISaveChanges method at the end of the method
(ProcessFilter or FilteringComplete) that made the changes to the message.
Making a change to the message in ProcessFilter and delaying the
MAPISaveChanges call to FilteringComplete is not regarded as good practice.
436 Filtering APIs
IExternalFilter :: Initialize
This method is called during Exchange archiving task initialization.
Syntax
HRESULT Initialize([in] IDispatch *pArchivingControl);
Parameters
[in] IDispatch *pArchivingControl Reference to the IArchvingControl interface.
Remarks
Filters are instantiated at task startup and released at task shutdown.
The filter should perform any necessary initialization before message
processing begins. The interface does not define a corresponding “Uninitialize”
method, so any resources created or opened in this method should be released
on the final release of the filter implementing the interface.
Filtering APIs 437
IExternalFilter :: ProcessFilter
This method is called per-message during the archiving process. The
ProcessFilter method is where you process the message to your requirements.
Syntax
HRESULT ProcessFilter([out, retval] VARIANT_BOOL *bStopFiltering);
Parameters
[out, retval] VARIANT_BOOL *bStopFiltering Value of true stops the filter

controller from processing any
more filters on the current item.
Remarks
To get a reference to the message, use the IArchivingControl :: MAPIMessage
property.
To find or change the current action to be taken on the message, use the
IArchivingControl :: Action property.
Similarly to change the retention category or archive for the item, use the
currentRetentionCategoryId and currentVaultId properties on the
IArchivingControl interface.
The external filter must be written to handle concurrent calls. If the filter
accesses a shared resource, it must use appropriate concurrency protection.
See also
■ “IArchivingControl :: MAPIMessage” on page 450.
■ “IArchivingControl :: Action” on page 448.
■ “IArchivingControl :: currentVaultId” on page 443.
■ “IArchivingControl :: currentRetentionCategoryId” on page 444.
438 Filtering APIs
IExternalFilter :: FilteringComplete
This method is called after all filters have been processed for the current item. It
can be used to clean up item-specific resources, such as memory or object
handles.
Syntax
HRESULT FilteringComplete();
Remarks
After processing has been completed, the properties on the IArchivingControl
interface are read-only. The properties can still be examined so that the filter
can determine the final state of the item.
Filtering APIs 439
IArchivingControl interface for Exchange filtering

The task filter controller implements the following interfaces:
■ IArchivingControl
■ IArchivingControl2
■ IArchivingControl3
The IArchivingControl interface enables an external filter to retrieve and modify
properties on the current message.
The IArchivingControl2 interface extends the IArchivingControl interface and
adds methods and properties to provide the following functionality:
■ Improved handling of MAPI Message Classes.
■ Ability to open an archived item from a URL.
■ Method for persisting changes made to messages by external filters, so that
the changes are reflected in the Exchange Server store and the Enterprise
Vault archive.
The IArchivingControl3 interface extends the IArchivingControl2 interface and
adds properties to retrieve sender and recipient information as XML.
Syntax
interface IArchivingControl3 : IArchivingControl2 :
IArchivingControl : IDispatch
Member summary
Table 7-1 IArchivingControl properties
currentVaultId Read/Write The Id of the archive associated

with the current item.
currentRetentionCategoryId Read/Write The Id of the retention category

associated with the current item.
defaultRetentionCategoryId Read only The Id of the default retention

category for the Enterprise Vault
Site.
deleteOriginalItem Read/Write Whether the item is to be deleted

from the original location after it
has been archived.
440 Filtering APIs
createShortcutToItem Read/Write Whether a shortcut is created in

the original location after the
item has been archived.
Action Read/Write The action to be taken by the

archiving task when the filtering
process is complete.
MAPISession Read only Gets a MAPI session.
MAPIMessage Read only A pointer to the current MAPI

message.
IndexedPropertiesSet Read only Lists the properties that have

been added using
AddIndexedProperty.
TransactionID Read only Identifies archiving action.
AgentType Read only Identifies the type of archiving

task using the filter.
AgentAssignedRetentionCategoryId Read only Identifies the original retention

category assigned.
AgentAssignedVaultId Read only Identifies the original destination

archive.
AttachmentAction Read/Write Defines action to be taken when

processing message attachments.
RetryStatus Read only Indicates if current archiving

action is a retry.
ReArchiveStatus Read only Indicates if current archiving

action is rearchiving an item that
has been restored from the
archive.
Filtering APIs 441
Table 7-2 IArchivingControl2 properties
BrowserViewURL Read only Provides a URL that can be used to present an

HTML view of the original item.
NativeItemURL Read only Provides a URL that can be use to fetch the original
item.
MessageClass Read only Identifies the original value of the MAPI Message
Class property.
Table 7-3 IArchivingControl methods
Method Description
AddIndexedProperty Adds metadata to the item. The metadata will be indexed.
AddIndexPropertyToSet Adds custom properties to a named custom property set.
AddIndexPropertySet Adds a named custom property set.
GetFilterProperty Retrieves value of variable set using PutFilterProperty by another

filter.
PutFilterProperty Sets a variable that can be queried by other filters.
Table 7-4 IArchivingControl2 method
Method Description
MAPISaveChanges Enables changes to the current message to be saved.

442 Filtering APIs
Table 7-5 IArchivingControl3 properties
Method Description
SenderRecipientXML Retrieves an XML document containing the sender

and recipient information for the current message.
EnvelopeSenderRecipientXML Retrieves an XML document containing the sender

and recipient information taken from the envelope
message.
MessageDirection Indicates the direction in whish the message was

travelling (in relation to the domain defined as
internal).
Version information
■ IArchivingControl2 properties and method are available in Enterprise Vault
7.0 and later. MessageClass and MAPISaveChanges are also available in
■ IArchivingControl3 properties are available in Enterprise Vault 6.0 SP5,
Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
Filtering APIs 443
IArchivingControl :: currentVaultId
IArchivingControl :: currentVaultId
The Id of the archive associated with the current item.
Syntax
HRESULT currentVaultId([in] BSTR newVal);
HRESULT currentVaultId([out, retval] BSTR *pVal);
Parameters
[in] BSTR newVal Id of archive to be assigned.
[out, retval] BSTR *pVal Id of archive assigned.
Remarks
The currentVaultId property enables an external filter to control the archive (or
folder) in which the item is stored. Although a subsequent filter may actually
redefine this value. The value originally assigned can be retrieved using the
AgentAssignedVaultId property.
An example value is:
190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1
444 Filtering APIs
IArchivingControl :: currentRetentionCategoryId
IArchivingControl :: currentRetentionCategoryId
The Enterprise Vault retention category to be assigned to the current item.
Syntax
HRESULT currentRetentionCategoryId([in] BSTR newVal);
HRESULT currentRetentionCategoryId([out, retval] BSTR *pVal);
Parameters
[in] BSTR newVal New retention category Id.
[out, retval] BSTR *pVal Retention category Id.
Remarks
The currentRetentionCategoryId property enables the external filter to get and
set the retention category that is to be applied to the item when it is stored. The
value originally assigned can be retrieved using the
AgentAssignedRetentionCategoryId property.
18306BF113C2C444096279660836252821b10000EVArchiveSite1
Use the Retention API to retrieve details of retention categories, and create new
Filtering APIs 445
IArchivingControl :: defaultRetentionCategoryId
IArchivingControl :: defaultRetentionCategoryId
The default retention category for the Enterprise Vault Site.
Syntax
HRESULT defaultRetentionCategoryId([out, retval] BSTR *pVal);
Parameters
[out, retval] BSTR *pVal Id of default retention category for site.
Remarks
The defaultRetentionCategoryId property enables the external filter to get the
default retention category for the Enterprise Vault Site.
446 Filtering APIs
IArchivingControl :: deleteOriginalItem
IArchivingControl :: deleteOriginalItem
This property indicates whether the item is to be deleted from the original
location after it has been archived.
Syntax
HRESULT deleteOriginalItem([in] BOOL newVal);
HRESULT deleteOriginalItem([out, retval] BOOL *pVal);
Parameters
[in] BOOL newVal New value.
[out, retval] BOOL *pVal Pointer to current value.
Remarks
When the archiving task is running in report mode, the action is ignored.
Filtering APIs 447
IArchivingControl :: createShortcutToItem
IArchivingControl :: createShortcutToItem
This property indicates whether a shortcut is created in the original location
after the item has been archived.
Syntax
HRESULT createShortcutToItem([in] BOOL newVal);
HRESULT createShortcutToItem([out, retval] BOOL *pVal);
Parameters
[in] BOOL newVal New value.
[out, retval] BOOL *pVal Pointer to current value.
Remarks
When the task is running in report mode the action is ignored.
448 Filtering APIs
IArchivingControl :: Action
IArchivingControl :: Action
This property indicates the action to be taken by the archiving task when the
filtering process is complete.
Syntax
HRESULT Action([in] EV_ACTION newVal);
HRESULT Action([out, retval] EV_ACTION *pVal);
Parameters
[in] EV_ACTION newVal EV_ACTION enumeration value.
[out, retval] EV_ACTION *pVal Current EV_ACTION enumeration value.
Remarks
For EV_ACTION enumeration values, see “EV_ACTION enumeration” on
page 433.
The default action is to archive the item (ARCHIVE_ITEM enumeration value).
Filtering APIs 449
IArchivingControl :: MAPISession
IArchivingControl :: MAPISession
This property returns a MAPI session for the current message.
Syntax
HRESULT MAPISession([out, retval] IUnknown **pUnkVal);
Parameters
[out, retval] IUnknown **pUnkVal Pointer to MAPI session.

450 Filtering APIs
IArchivingControl :: MAPIMessage
IArchivingControl :: MAPIMessage
This property provides a pointer to the current MAPI message (P2).
Syntax
HRESULT MAPIMessage([out, retval] IUnknown **pUnkVal);
Parameters
[out, retval] IUnknown **pUnkVal Pointer to MAPI message.
Remarks
The properties of the message can be accessed and updated using standard
MAPI calls. Any changes should be persisted using MAPISaveChanges at the end
of the method (ProcessFilter or FilteringComplete) that made the changes to the
message.
As MAPISaveChanges does not save changes made to attachments of P2
messages, these will have to be saved first by the caller.
See also
■ “IArchivingControl2 :: MAPISaveChanges” on page 467.
Filtering APIs 451
IArchivingControl :: AddIndexedProperty
IArchivingControl :: AddIndexedProperty
This method enables you to add a property to the custom index metadata for the
item.
Syntax
HRESULT AddIndexedProperty([in] BSTR propname,
[in] BSTR value);
Parameters
[in] BSTR propname Property name.
[in] BSTR value Property value.
Remarks
Using this method adds the property to the default property set.
Properties added using this method are always searchable and retrievable.
To avoid property name clashes, you are recommended to use
AddIndexPropertyToSet to add the property to a named property set. This will
also enable you to control whether the property is searchable and retrievable.
452 Filtering APIs
IArchivingControl :: IndexedPropertiesSet
IArchivingControl :: IndexedPropertiesSet
This property lists the properties that have been added to the custom index
metadata of the item using AddIndexedProperty.
Syntax
HRESULT IndexedPropertiesSet([out, retval] BSTR *pVal);
Parameters
[out, retval] BSTR *pVal Pointer to the XML list of properties.
Remarks
This property enables the filter to find out the custom index metadata that has
been added to the item using AddIndexedProperty method.
The properties are returned as XML which can be loaded into an
ISimpleIndexMetadata object using the FromXML method.
See “ISimpleIndexMetadata :: FromXML” on page 290.
Filtering APIs 453
IArchivingControl :: AddIndexPropertyToSet
IArchivingControl :: AddIndexPropertyToSet
This method adds a custom index metadata property to a named property set.
Syntax
HRESULT AddIndexPropertyToSet([in] BSTR setname,
[in] BSTR propname,
[in] BSTR propvalue);
Parameters
[in] BSTR setname Name of property set.
[in] BSTR propname Name of property.
[in] BSTR propvalue Value of property.
Remarks
The searchable and retrievable settings for the property set will define how the
property is handled.
If the property set exists, the property will be added to that property set. If it
does not exist, the property set will be created first.
If a property set is created "by default", it will have the default attributes of
searchable ="true" and retrievable ="false".
If a property needs to be retrievable, the property set needs to be created using
the AddIndexPropertySet method, where the values for searchable and
retrievable can be set explicitly.
Properties can be multi-valued. When adding a property, the existence of that
property within the specified set is checked and, if present, the value is added as
an element of that property.
454 Filtering APIs
IArchivingControl :: AddIndexPropertySet
IArchivingControl :: AddIndexPropertySet
This method adds a named custom property set. Custom index metadata
properties can be added to this set using AddIndexPropertyToSet method.
Syntax
HRESULT AddIndexPropertySet([in] BSTR setname,
[in] BOOL searchable,
[in] BOOL retrievable);
Parameters
[in] BSTR setname The name of the property set. Suitable names would be your
company name or the filter application name.
[in] BOOL searchable Setting the value to “true” means that properties in the set
will be indexed.
[in] BOOL retrievable Setting the value to “true” means that property values can be
returned as part of the search results.
The default is “false”.
Remarks
Properties added can be grouped in named property sets. It is good practice to
use a named property sets in order to avoid name clashes with other filter
additions. The property set names, Vault, EnterpriseVault, KVS, Veritas, and
Symantec are reserved.
Properties defined as Searchable will be indexed and can be searched for using
the Search API. Properties defined as Retrievable can be retrieved and displayed
later with the item. Each property set can be marked as Searchable or
Retrievable or both.
See “SimpleIndexMetadata object” on page 277.
Property sets do not need to be created before properties are added to them.
Filtering APIs 455
IArchivingControl :: TransactionID
IArchivingControl :: TransactionID
This property is the unique identifier that will be assigned to the archived item.
Syntax
HRESULT TransactionID([out, retval] BSTR* pTransactionID);
Parameters
[out, retval] BSTR* pTransactionID Transaction Id.
Remarks
This property can be used as the IItem :: Id value in the Content Management
API to subsequently fetch the archived item.
See also
■ “IArchivingControl :: RetryStatus” on page 462.
■ “IArchivingControl :: ReArchiveStatus” on page 463.
456 Filtering APIs
IArchivingControl :: AgentType
IArchivingControl :: AgentType
This property identifies the type of the current archiving task.
Syntax
HRESULT AgentType([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal Current archiving task type.
Remarks
The value can be one of the following:
■ Mailbox
■ Journaling
■ PublicFolder
Filtering APIs 457
IArchivingControl :: AgentAssignedRetentionCategoryId
IArchivingControl ::
AgentAssignedRetentionCategoryId
This property identifies the original retention category assigned, in case other
filters have assigned a different retention category.
Syntax
HRESULT AgentAssignedRetentionCategoryId([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal Retention category Id.
Remarks
Use the Retention API to retrieve details of retention categories, and create new
458 Filtering APIs
IArchivingControl :: AgentAssignedVaultId
IArchivingControl :: AgentAssignedVaultId
This property identifies the original destination archive, in case other filters
have redirected the message to an alternative archive.
Syntax
HRESULT AgentAssignedVaultId([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal Archive Id.

Filtering APIs 459
IArchivingControl :: GetFilterProperty
IArchivingControl :: GetFilterProperty
This method enables communication between filters; a filter property can be set
by one filter and queried by another.
Syntax
HRESULT GetFilterProperty([in] BSTR Key);
HRESULT GetFilterProperty([out, retval] BSTR *pVal);
Parameters
[in] BSTR Key Key for property used by PutFilterProperty.
[out, retval] BSTR *pVal Pointer to a string containing the value of Setting (set
with PutFilterProperty).
Remarks
The GetFilterProperty and PutFilterProperty methods facilitate communication
between filters; a filter may set a property value which a later filter can then
query. Once a property value is set, it will be passed down to each filter.
The method uses the Key, (used by PutFilterProperty), to retrieve the Setting
value that was set with PutFilterProperty method.
The setting can be set by separate filters, so the order in which they are called is
important.
If called with a Key that has not been set, then it will return an empty string, but
will not return an error.
460 Filtering APIs
IArchivingControl :: PutFilterProperty
IArchivingControl :: PutFilterProperty
This method is used to set a filter property that is passed on to subsequent
filters.
Syntax
HRESULT PutFilterProperty ([in] BSTR Key,
[in] BSTR Setting);
Parameters
[in] BSTR Key Key for filter property.
[in] BSTR Setting Value of filter property.
Remarks
The caller supplies a unique name (Key) for each setting that can then be
retrieved using GetFilterProperty.
The property values exist until filtering is completed for the current item.
Settings can be updated by calling PutFilterProperty a second time, suppling the
same key. The keys are case insensitive.
Its not possible to delete filter settings, but they can be set to empty.
Filtering APIs 461
IArchivingControl :: AttachmentAction
IArchivingControl :: AttachmentAction
This property defines the action to be taken when processing attachments to
messages.
Syntax
HRESULT AttachmentAction([in] EV_ATTACHMENT_ACTION newVal);
HRESULT AttachmentAction([out, retval] EV_ATTACHMENT_ACTION *pVal);
Parameters
[in] EV_ATTACHMENT_ACTION newVal The new value to set.
[out, retval] EV_ATTACHMENT_ACTION *pVal Pointer to an

EV_ATTACHMENT_ACTION type
that contains the current value.
Remarks
This property is not currently supported.
With Exchange server filtering, if the message attributes satisfy a rule, any
attachments are then evaluated using attachment attributes. When an
attachment matches a rule, the action specified by ATTACHMENT_ACTION is
applied to the attachment.
For EV_ATTACHMENT_ACTION enumeration values, see
“EV_ATTACHMENT_ACTION enumeration” on page 433.
462 Filtering APIs
IArchivingControl :: RetryStatus
IArchivingControl :: RetryStatus
This property enables the caller to determine if the current attempt to archive
an item is a retry.
Syntax
HRESULT RetryStatus([out, retval] EV_RETRY_STATUS* pRetryStatus
Parameters
[out, retval] EV_RETRY_STATUS* pRetryStatus Pointer to an

EV_RETRY_STATUS type
containing the current value.
Remarks
Sometimes when an item fails to be archived, the item will be subsequently
retried by the archiving task. In this case, the item will also be refiltered.
If this is a retry, the transactionID will typically be the same as the previous
attempt.
This property can be used to avoid the following when processing retries:
■ Counting the same transaction multiple times.
■ Storing the same transaction (for example, in a database) multiple times.
For EV_RETRY_STATUS enumeration values, see “EV_RETRY_STATUS
See also
■ “IArchivingControl :: TransactionID” on page 455.
■ “IArchivingControl :: ReArchiveStatus” on page 463.
Filtering APIs 463
IArchivingControl :: ReArchiveStatus
IArchivingControl :: ReArchiveStatus
If an item has been restored and is being rearchived, this property enables the
caller to determine if the current item is being rearchived.
Syntax
HRESULT ReArchiveStatus([out, retval] EV_REARCHIVE_STATUS*
pReArchiveStatus);
Parameters
[out, retval] EV_REARCHIVE_STATUS* pReArchiveStatus Pointer to an

EV_REARCHIVE_
STATUS type
containing the current
value.
Remarks
If this is a rearchive, the transactionID will typically be the same as the previous
archive transaction.
This property can be used to avoid the following when processing rearchive
transactions:
■ Counting the same transaction multiple times.
■ Storing the same transaction (for example, in a database) multiple times.
For EV_REARCHIVE_STATUS enumeration values, see
“EV_REARCHIVE_STATUS enumeration” on page 434.
464 Filtering APIs
IArchivingControl2 :: BrowserViewURL
IArchivingControl2 :: BrowserViewURL
This property returns a string containing the URL that should be entered into a
web browser (for example) to view the item.
Syntax
HRESULT BrowserViewURL([out,retval] BSTR* pVal)
Parameters
[out,retval] BSTR* pVal Pointer to a BSTR that will contain the URL.
Remarks
This property will return an error if the archive Id and the saveset Id have not
been set previously.
for each caller.
ture.
Return value
S_OK Success.
E_FAIL An unexpected error has occurred.
E_INVALIDARG Either the archive Id or saveset Id have not been set or the
saveset Id is invalid.
Example
The following is an example value of BrowserViewURL:
http://webserver1.EXAMPLE.COM/EnterpriseVault/viewmessage.asp?Vault
ID=12B72E5122E1D714893C625CEF3A762311110000sv1.example.com&SavesetI
D=430D7CD1EA644810ADF10D71CF39063&Format=WEB
Filtering APIs 465
IArchivingControl2 :: NativeItemURL
IArchivingControl2 :: NativeItemURL
The URL downloads the item that was archived and attempts to open the item
using the default application for the type of the item.
Syntax
HRESULT NativeItemURL([out, retval] BSTR* pVal);
Parameters
[out, retval] BSTR* pVal A pointer to a BSTR that will contain the current value.
Remarks
There will be an error if either the item Id or the archive Id have not been set
before using this property.
for each caller.
ture.
Return Value
S_OK Success.
E_INVALIDARG Either the item Id or archive Id have not been set.
E_POINTER An invalid pointer has been passed as an argument and it is

not possible to return the current value of this property.
Example
The following is an example value of NativeItemURL:
http://webserver1.EXAMPLE.COM/EnterpriseVault/download.asp?VaultID=
12B72E5122E1D714893C625CEF3A762311110000sv1.example.com&SavesetID=4
30D7CD1EA644810ADF10D71CF39063&Request=NativeItem
466 Filtering APIs
IArchivingControl2 :: MessageClass
IArchivingControl2 :: MessageClass
This property returns the MAPI Message Class for the current item.
Syntax
HRESULT MessageClass([out, retval] BSTR *pVal);
Parameters
[out, retval] BSTR *pVal Pointer to a string containing the MAPI message
class.
Remarks
The value of the MAPI property, OriginalMessageClass, is returned if it
exists. Otherwise the value of PR_MESSAGE_CLASS is returned.
If the current item is an envelope journal message (P1), then the Message Class
is returned from the P2 message.
Example
An example of a MAPI Message Class is:
IPM.Note
Filtering APIs 467
IArchivingControl2 :: MAPISaveChanges
IArchivingControl2 :: MAPISaveChanges
This method persists changes to the current message.
Syntax
HRESULT MAPISaveChanges();
Remarks
If the external filter makes changes to the message or message envelope, save
the changes by calling the MAPISaveChanges method at the end of the method
(ProcessFilter or FilteringComplete) that made the changes to the message. The
changes are saved in the Exchange Store. If the item is then archived, the
changes are also saved in the archive. It is not possible to save changes in the
archive but not in the Exchange Store.
MAPISaveChanges saves changes made to the following:
■ The P2 message.
■ Any attachment to the P1 message.
■ The P1 message.
As MAPISaveChanges does not save changes made to attachments of P2
messages, these will have to be saved first by the caller.
468 Filtering APIs
IArchivingControl3 :: SenderRecipientXML
This property retrieves an XML document containing the sender and recipient
information for the current message.
Syntax
HRESULT SenderRecipientXML([out, retval] IUnknown **ppStream);
Remarks
For Exchange Journaling tasks any distribution lists are expanded, regardless of
the setting of the Expand distribution lists setting on the Advanced page of the
Exchange Journaling policy in the Enterprise Vault Administration Console.
The property value is an XML document representing the sender and recipient
information for the current message, including expanded distribution lists.
For Exchange envelope journal items this information is extracted from the P2
message and is just a representation of the sender and recipient information as
taken from the MAPI message.
The return object implements IStream and can be loaded into an
XMLDOMDocument. The only available IStream methods available are
IStream :: CopyTo, IStream :: Read, IStream :: Seek and IStream :: Stat. All other
methods return E_NOTIMPL.
Example
<?xml version="1.0" encoding="UTF-16"?>
<ARCHIVED_ITEM xmlns:o="urn:kvsplc-com:archived_item"
version="1.0">
<MSG>
<RECP>
<TO>
<RC>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</RC>
<DL>
<DN>Distribution List Display Name</DN>
<EA>Distribution List SMTP Email Address</EA>
<TIME>2007-09-03T23:36:28</TIME>
<RC>
<DN>User1</DN>
</RC>
</DL>
Filtering APIs 469
</TO>
<CC/>
<BCC/>
</RECP>
<AUTH>
<FROM>
</FROM>
</AUTH>
</MSG>
</ARCHIVED_ITEM>
470 Filtering APIs
IArchivingControl3 :: EnvelopeSenderRecipientXML
information taken from the envelope message.
Syntax
HRESULT EnvelopeSenderRecipientXML([out, retval] IUnknown
**ppStream);
Remarks
This property is only available for Exchange envelope journal items. Any
distribution lists are expanded, regardless of the setting of the Expand
distribution lists setting on the Advanced page of the Exchange Journaling
policy in the Enterprise Vault Administration Console.
information for the current message, including expanded distribution lists. The
recipient information as taken from the envelope report and does not contain
information from the P2 message.
The return object implements IStream and can be loaded into an
XMLDOMDocument. The only available IStream methods available are
IStream :: CopyTo, IStream :: Read, IStream :: Seek and IStream :: Stat. All other
methods return E_NOTIMPL.
Example
<?xml version="1.0" encoding="UTF-16"?>
<ARCHIVED_ITEM xmlns:o="urn:kvsplc-com:archived_item"
version="1.0">
<MSG>
<RECP P1="true">
<TO>
<RC>
</RC>
<DL>
<DN>Distribution List Display Name</DN>
<EA>Distribution List SMTP Email Address</EA>
<RC>
<DN>User1</DN>
</RC>
</DL>
Filtering APIs 471
</TO>
<CC/>
<BCC>
<RC>
</RC>
</BCC>
<ENV>
<RC>
</RC>
</ENV>
</RECP>
<AUTH P1=”true”>
<FROM>
</FROM>
</AUTH>
</MSG>
</ARCHIVED_ITEM>
Note: EnvelopeSenderRecipientXML for Exchange 2007 envelope items will not

contain any <DN> (Display Name) tags as the display name does not exist in the
P1 envelope report.
472 Filtering APIs
IArchivingControl3 :: MessageDirection
IArchivingControl3 :: MessageDirection
This property indicates the direction in which the message was travelling (in
relation to the domain defined as internal).
Syntax
HRESULT MessageDirection([out, retval] MSG_DIRECTION
*Msg_Direction);
Remarks
The property value is an enumerated value. For MSG_DIRECTION enumerated
values, see “Message direction enumeration” on page 434.
Filtering APIs 473
Domino Filtering API

The Domino Filtering API is presented as a set of .NET interfaces.
About the Domino Filtering API

The Domino Filtering API enables you to create external filters for Domino
Journaling tasks. The filters define how the Domino Journaling task selects and
processes messages.
■ Messages can be selected by matching one or more attributes, such as email
addresses, subject text or message direction.
■ Additional properties can be added to the Enterprise Vault index for the
message.
■ The action defined for the task can be to archive the message, mark it as "do
not archive", or delete it.
Marking messages reduces the overhead on the archiving task, as these
messages are not re-evaluated during subsequent archiving runs, unless the
Override registry setting is configured.
See “Domino filtering registry settings” on page 474
Figure 7-2 Overview of Domino filtering
The figure, “Overview of Domino filtering”, illustrates how Enterprise Vault

implements Domino journal filters:
■ If the registry settings are configured to enable filtering for the Domino
Journaling tasks, the Domino Journaling task calls the task filter controller
when processing a message in the Domino journal database.
474 Filtering APIs
■ The task filter controller invokes the first external filter, which implements
the IExternalFilter interface.
■ The filter uses the methods and properties on the ILotusArchivingControl
interface to retrieve information about the message.
■ The filter then processes the message. Methods and properties on the
ILotusArchivingControl interface enable you to define how the Domino
Journaling task is to process the message.
■ If there are several filters, each external filter is applied in turn to the
message, provided the stopFiltering parameter is not set to TRUE.
■ After all the filters have been applied, the FilteringComplete method for
each filter is called to perform any clean up tasks.
■ The Domino Journaling task then processes the message according to the
properties set by the external filters.
Developing external filters
Note: If you plan to supply data to your external filters using XML, be aware that
Microsoft does not support the use of MSXML (Microsoft’s COM-based XML
parser) in .NET applications. This is described in the knowledge base article, KB
815112.
Filters developed using the Domino Filtering API must reference the .NET
assembly:
■ KVS.EnterpriseVault.LotusDominoInterfaces.DLL
You can develop external filters in the programming language of your choice.
For clarity, definitions are given using C#.NET syntax.
For Domino filters, if you want to use the Lotus C API for Lotus Notes/Domino to
access the note, we recommend that you use managed C++. The Lotus C API for
Lotus Notes/Domino is shipped with the Lotus Notes client.
To develop an external filter for Domino journaling, you need to obtain and
install an Enterprise Vault Lotus Domino Journaling license.
Domino filtering registry settings

Filtering for Enterprise Vault Domino Journaling tasks is enabled using registry
settings under the External Filtering key:
Filtering APIs 475
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Lotus Journaling
If either External Filtering or Lotus Journaling keys do not exist, then
you can create them.
You create a new string entry for each filter under the Lotus Journaling key.
Filter names must be an unbroken numbered sequence starting at 1.
The value of the filter name is a string value that contains the name of the .NET
assembly and the relevant filter class for the new external filter:
PathToFilterAssembly!FilterClassName
For example, the value for the generic Domino filter is
KVS.EnterpriseVault.LotusDominoCustomFilter.DLL!KVS.Enterpri
seVault.LotusDomino.CustomFilter
Note that the class name is case sensitive.
If you have installed the Compliance Accelerator Journaling Connector,
KVS.EnterpriseVault.LotusDominoMsgHandler.dll!
KVS.EnterpriseVault.LotusDomino.CADominoFilter
then it must be the last in the sequence of filters. When you add other filters,
you must rename the Journaling Connector to ensure that it remains last in the
sequence.
Optionally, you can create a DWORD entry with the name Override, if it does
not exist. Set its value to 0 (zero). This entry controls whether the Domino
Journaling task reexamines any messages that are marked as
MARK_DO_NOT_ARCHIVE each time it processes the Domino journaling
location. If the value is 0, or the Override entry does not exist, then the
Domino Journaling task does not reexamine the messages.
To implement changes to the registry settings, restart the associated Domino
Journaling tasks.
476 Filtering APIs
Enumerations (Domino filtering)

This section lists the enumerations for the Domino Filtering API.
Message direction enumeration

The following enumeration values are defined for MSG_DIRECTION:
public enum MSG_DIRECTION
{
DIRECTION_UNDEFINED = 0,
DIRECTION_INTERNAL = 1,
DIRECTION_EXTERNAL_IN = 2,
DIRECTION_EXTERNAL_OUT = 3
}
Domino action enumeration

The following enumeration values are defined for DominoAction:
public enum DominoAction
{
NO_ACTION = 0,
ARCHIVE_ITEM = 1,
MARK_DO_NOT_ARCHIVE = 2,
HARD_DELETE = 4,
REQUEST_SHUTDOWN = 5
}
Table 7-6 DominoAction enumeration values
Value Action
NO_ACTION Do not archive, delete or mark the item.
ARCHIVE_ITEM (Default) Archive the item according to the

assigned policy.
MARK_DO_NOT_ARCHIVE Mark the item as processed but do not archive it.

The Domino Journaling task does not reexamine
marked messages unless the Override setting is
configured.
See “Domino filtering registry settings” on
page 474
HARD_DELETE Hard delete the item without archiving it.

Note that this option requires Enterprise Vault
8.0 SP5 or later.
REQUEST_SHUTDOWN Shut down the archiving task.

Filtering APIs 477
478 Filtering APIs
The external filter must implement the IExternalFilter interface, which is called
by the archiving task filter controller:
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL
Syntax
public interface IExternalFilter
Member summary
Method Description
Initialize Called during the archiving task initialization. The filter should
perform any necessary initialization before item processing begins.
ProcessFilter Called per-item during the archiving process. The ProcessFilter

method is where you process the item to your requirements.
FilteringComplete Called after all filters have been processed for the current item.
Shutdown Called during the archiving task shutdown. The filter should
perform any necessary clean-up tasks.
Requirements
Filtering APIs 479
This method is called during archiving task initialization.
Syntax
void Initialize();
Remarks
Filters are instantiated at task startup and released at task shutdown.
The filter should perform any necessary initialization before item processing
begins.
480 Filtering APIs
This method is called per-item during the archiving process. The ProcessFilter
method is where you process the item to your requirements.
Syntax
void ProcessFilter(IArchivingControl archivingControl,
ref bool stopFiltering);
Parameters
IArchivingControl archivingControl Reference to the LotusArchivingControl

interface.
ref bool stopFiltering True value prevents any further filters

from being processed for the current item.
Remarks
The archivingControl reference is used by the filter in the callback to obtain
information about the current item and take appropriate actions.
As the archiving task runs in multiple threads, the external filter must be
written to handle concurrent calls. If the filter accesses a shared resource, it
must use appropriate concurrency protection.
See also
■ “IArchivingControl interface” on page 483
■ “ILotusArchivingControl interface” on page 490
Filtering APIs 481
This method is called after all filters have been processed.
Syntax
void FilteringComplete();
Remarks
This method can be used to clean up resources used to filter the item.
482 Filtering APIs
IExternalFilter :: Shutdown
IExternalFilter :: Shutdown
This method is called during archiving task shutdown.
Syntax
void Shutdown();
Remarks
The filter should perform any necessary clean-up tasks.
Filtering APIs 483
IArchivingControl interface
IArchivingControl interface
This task filter controller implements the following interfaces:
■ IArchivingControl
■ ILotusArchivingControl
The methods properties of the interfaces enable an external filter to retrieve
and modify properties on the current item.
The ILotusArchivingControl interface is implemented by the Domino archiving
task filter controller, and is passed to the filter on a per-message basis during
the ProcessFilter call. It extends the IArchivingControl interface to provide
access to Domino messages from Domino filters.
See “ILotusArchivingControl interface” on page 490
Syntax
public interface ILotusArchivingControl : IArchivingControl
Member summary
OriginalVaultID Read only Original archive for the current

item.
CurrentVaultID Read/Write Target archive for the current

item.
OriginalRetentionCategoryID Read only Original retention category for

the current item.
CurrentRetentionCategoryID Read/Write Retention category assigned to

current item.
IndexData Read only Metadata added, or to be added,

to the current item.
FilterProperties Read only A collection of properties for the

current item.
484 Filtering APIs
IArchivingControl :: OriginalVaultID
IArchivingControl :: OriginalVaultID
Retrieves the original archive ID for the current item.
This property is read-only.
Syntax
string OriginalVaultID {get;}
Remarks
This property holds the archive ID originally assigned by the archiving task
before any filters where processed. If a filter changes the target archive for the
item, this property will remain unchanged.
Filtering APIs 485
IArchivingControl :: CurrentVaultID
IArchivingControl :: CurrentVaultID
This property retrieves or sets the ID of the archive in which the current item
will be stored.
Syntax
string CurrentVaultID {get; set;}
Example
An example value for this property is:
190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1
486 Filtering APIs
IArchivingControl :: OriginalRetentionCategoryID
IArchivingControl :: OriginalRetentionCategoryID
This property holds the original retention category ID for the current item.
This property is read-only.
Syntax
string OriginalRetentionCategoryID {get;}
Remarks
This property holds the Id of the retention category originally assigned by the
archiving task, before any filters where processed. If a filter changes the
retention category for the item, this property will remain unchanged.
Filtering APIs 487
IArchivingControl :: CurrentRetentionCategoryID
IArchivingControl :: CurrentRetentionCategoryID
This property defines the retention category for the current item.
Syntax
string CurrentRetentionCategoryID {get; set;}
Remarks
Use this property to set or retrieve the ID of the retention category assigned to
the current item.
18306BF113C2C444096279660836252821b10000EVArchiveSite1
488 Filtering APIs
IArchivingControl :: IndexData
IArchivingControl :: IndexData
This property is an instance of the IIndexMetadata interface, and enables access
to the custom index metadata for the current item.
Syntax
IIndexMetadata IndexData {get;}
Remarks
See also
■ “IIndexMetadata interface” on page 499.
Filtering APIs 489
IArchivingControl :: FilterProperties
IArchivingControl :: FilterProperties
This property is an instance of the IKeyedList interface, and enables
communication between multiple filters. For example, a filter property can be
set by one filter and queried by another.
Syntax
IKeyedList FilterProperties {get;}
Remarks
The properties listed are shared across all filters. These properties are not
stored in Enterprise Vault or reset by Enterprise Vault. The properties can be
maintained across multiple messages, if required.
See also
■ “IKeyedList interface” on page 513.
490 Filtering APIs
ILotusArchivingControl interface
ILotusArchivingControl interface
ILotusArchivingControl is derived from the IArchivingControl interface, and
extends the interface to enable filters to access Domino messages.
For details of the properties on the IArchivingControl interface, see
“IArchivingControl interface” on page 483
Member summary
Table 7-8 ILotusArchivingControl properties
Action Read/Write Defines filtering action for current message.
NoteHandle Read only Handle to current message.
DatabaseHandle Read only Handle to current journal database.
DatabaseName Read only Path to current journal database.
SenderRecipientXML Read only XML representation of message distribution list.
StoreIdentifier Read only Unique Id of Domino message.
Direction Read only Direction of message (internal or external).

Filtering APIs 491
ILotusArchivingControl :: Action
ILotusArchivingControl :: Action
This property defines the filtering action for the current message.
Syntax
DominoAction Action {get; set;}
Remarks
The filtering action is defined by the DominoAction enumeration. For
DominoAction enumerated values, see
“Domino action enumeration” on page 476.
The default action is to archive the item (ARCHIVE_ITEM enumeration value).
492 Filtering APIs
ILotusArchivingControl :: NoteHandle
ILotusArchivingControl :: NoteHandle
This property retrieves the Lotus C API for Lotus Notes/Domino handle to the
current message.
Syntax
IntPtr NoteHandle {get;}
Remarks
This handle must not be closed by the filter.
Filtering APIs 493
ILotusArchivingControl :: DatabaseHandle
ILotusArchivingControl :: DatabaseHandle
This property retrieves the Lotus C API for Lotus Notes/Domino handle to the
current database.
Syntax
IntPtr DatabaseHandle {get;}
Remarks
This handle must not be closed by the filter.
494 Filtering APIs
ILotusArchivingControl :: DatabaseName
ILotusArchivingControl :: DatabaseName
This property retrieves the current Domino journal database path.
Syntax
string DatabaseName {get;}
Remarks
This path is relative to the Data folder.
Filtering APIs 495
ILotusArchivingControl :: SenderRecipientXML
information for the current message.
Syntax
XmlDocument SenderRecipientXML {get;}
Remarks
Any distribution lists are expanded, regardless of the setting of the Expand
distribution lists setting on the Advanced page of the Domino Journaling policy
in the Enterprise Vault Administration Console.
information for the current message, including expanded distribution lists.
This document is described by the following DTD:
<!ELEMENT MSG (RECP, AUTH)>
<!ELEMENT RECP (TO, CC, BCC)>
<!ELEMENT TO (RC*, DL*)>
<!ELEMENT CC (RC*, DL*)>
<!ELEMENT BCC (RC*, DL*)>
<!ELEMENT RC (DN, EA+)>
<!ELEMENT DN (#PCDATA)>
<!ELEMENT EA (#PCDATA)>
<!ELEMENT DL (DN, EA, RC*)>
<!ELEMENT AUTH (FROM, PP)>
<!ELEMENT FROM (DN, EA)>
<!ELEMENT PP (DN?, EA?)>
<!ATTLIST EA TYPE CDATA #REQUIRED>
Example
The following is an example of the SenderRecipientXML document:

<MSG>
<RECP>
<TO>
<RC>
<EA TYPE="SMTP">SMTP_address</EA>
<EA TYPE="NOTES">LotusNotes_address</EA>
</RC>
496 Filtering APIs
<DL>
<DN>Display Name of DL</DN>
<EA TYPE="NOTES">lotusnotes_address_of_dl</EA>
<RC>
<DN>Display Name of DL Member</DN>
<EA TYPE="NOTES">lotusnotes_address_of_dl_member</EA>
</RC>
</DL>
</TO>
<CC/>
<BCC/>
</RECP>

<AUTH>
<FROM>
<EA TYPE="NOTES">LotusNotes_address</EA>
</FROM>
<PP/>
</AUTH>
</MSG>
Filtering APIs 497
ILotusArchivingControl :: StoreIdentifier
ILotusArchivingControl :: StoreIdentifier
This property uniquely identifies the message.
Syntax
string StoreIdentifier {get;}
Remarks
The property is derived from the Universal Note ID (UNID) and Originator ID
(OID) that are assigned by the Domino server.
The UNID and OID are defined as follows:
UNID (Universal Note ID) Identifies all the copies of a note, regardless of
location or time. Every copy of a note has the same
UNID, and the UNID does not change when a note is
modified.
OID (Originator ID) Identifies a particular revision of a note, regardless of

location. Every copy of a note has the same OID, but
the OID changes when the note is modified.
498 Filtering APIs
ILotusArchivingControl :: Direction
ILotusArchivingControl :: Direction
This property indicates the direction in which the message was travelling (in
relation to the domain defined as internal).
Syntax
MSG_DIRECTION Direction {get;}
Remarks
The property value is an enumerated value. For MSG_DIRECTION enumerated
values, see “Message direction enumeration” on page 476.
Filtering APIs 499
IIndexMetadata interface
IIndexMetadata interface
This interface enables the external filter to add properties to the custom index
metadata for the current item, and retrieve additional properties that have been
previously added to the index using Add ().
Syntax
public interface IIndexMetadata : IEnumerable
Member summary
Table 7-9 IIndexMetadata properties
DateTimeUTC Read/Write Whether date and time properties are UTC or local
system time.
Table 7-10 IIndexMetadata methods
Method Description
Count Returns the current count of properties.
Add Add a custom index metadata property to the current item.
Clear Remove all custom index metadata properties from the current item.
ToXML Persists the custom index metadata to XML.
FromXML Loads the custom index metadata from XML.
Remarks
The IIndexMetadata interface inherits from the IEnumerable interface and
hence supports standard enumeration support for the collection of properties.
When enumerating, each property is returned as an instance of the
IIndexProperty interface.
See “IIndexProperty interface” on page 507.
500 Filtering APIs
IIndexMetadata :: ToXML
IIndexMetadata :: ToXML
This method returns the custom index metadata as an XML document.
Syntax
string ToXML(bool formattedLayout);
Parameters
bool formattedLayout If true, the XML returned will be formatted in lines and
indented appropriately.
Remarks
The XML can be loaded into an ISimpleIndexMetadata object, as defined in the
Content Management API.
Filtering APIs 501
IIndexMetadata :: FromXML
IIndexMetadata :: FromXML
This method loads the custom index metadata from an XML document.
Syntax
void FromXML(string xmlIndexMetadata);
Parameters
[in] BSTR xmlIndexMetadata The XML stream to input.
Remarks
Use the Add method to add item specific values.
The XML schema is not published, as the Add method should always be used to
add metadata properties.
Do not change the structure of the XML.
502 Filtering APIs
IIndexMetadata :: Add
This method adds a property to the custom index metadata for the current item.
The custom index metadata will be added to the archive's item once the item has
been archived.
Syntax
void Add(string propertySet, string propertyName,
string propertyValue, bool propertySearchable,
bool propertyRetrievable);

DateTime propertyValue, bool propertySearchable,

long propertyValue, bool propertySearchable,

ulong propertyValue, bool propertySearchable,
Parameters
string propertySet Name of the property set.
string propertyName Name of the property.
string propertyValue Property value.

DateTime propertyValue
long propertyValue
ulong propertyValue
bool propertySearchable Whether property can be searched for using Search API.
bool propertyRetrievable Whether property can be retrieved and displayed in

search results.
Remarks
The Add method can be called repeatedly to add multiple properties to the
index.
The overloads of the Add method allow the addition of strings, integers or
DateTime values.
Filtering APIs 503
Properties can be multi-valued. When adding a property, the existence of that

property within the specified property set is checked and, if present, the value is
added as an element of that property.
If the Searchable property is true, the property will be indexed.
If the Retrievable property is true, the property is stored with the item in the
archive. The property information can then be retrieved and displayed later
with the item in search results. The default value is false.
It is good practice to use a named property set in order to avoid name clashes
with other external filter additions. Suitable names would be your company
name or the filter application name. The following property set names are
reserved:
■ Vault
■ EnterpriseVault
■ KVS
■ Veritas
■ Symantec
Property sets do not need to be created before properties are added to them.
When you use Add() to add a property to the index, the property will be added to
the property set specified by propertySet, if the property set exists. If the set
does not exist, it will be created first.
504 Filtering APIs
IIndexMetadata :: Clear
IIndexMetadata :: Clear
This method clears all properties from the IIndexMetadata object for the current
item.
Syntax
void Clear();
Filtering APIs 505
IIndexMetadata :: Count
IIndexMetadata :: Count
This method retrieves the number of properties in the IndexMetadata object for
the current item.
Syntax
int Count();
506 Filtering APIs
IIndexMetadata :: DateTimesUTC
IIndexMetadata :: DateTimesUTC
This property sets or retrieves whether the date and time properties are input
and output in UTC or local system time.
Syntax
bool DateTimeUTC {get; set;}
Remarks
This property sets or retrieves whether the date and time properties are input
and output in UTC or local system time.
Filtering APIs 507
IIndexProperty interface
IIndexProperty interface
The IIndexProperty interface details a a custom index metadata property within
an IIndexMetadata collection.
Syntax
public interface IIndexProperty
Member summary
Table 7-11 IIndexProperty properties
Set Read only The name of the property set.
Name Read only The name of the property.
Value Read only The value assigned to the property.
Searchable Read only Defines whether the property is to be added to the

item index.
Retrievable Read only Defines whether the property is to be stored in the

saveset.
Remarks
An instance of this interface is returned when enumerating an IIndexMetadata
collection.
Example
C#
IIndexMetadata custProps = archivingControl.IndexMetadata;
foreach(IIndexProperty prop in custProps)

{
if (prop.Searchable)
{
searchableProps.Add(prop.Set, prop.Name, prop.Value);
}
}
508 Filtering APIs
IIndexProperty :: Set
IIndexProperty :: Set
This property holds the name of the property set.
Syntax
string Set {get;}
Filtering APIs 509
IIndexProperty :: Name
IIndexProperty :: Name
This property holds the name of the custom index property.
Syntax
string Name {get;}
510 Filtering APIs
IIndexProperty :: Value
IIndexProperty :: Value
This property holds the value of the index property.
Syntax
System.Object Value {get;}
Remarks
The object will be a string, integer, or date/time value.
Example
C#
IIndexMetadata custProps = archivingControl.IndexMetadata;
foreach(IIndexProperty prop in custProps)

{
if (prop.Searchable && (prop.Value.GetType() ==
typeof(DateTime)))
{
searchableDateProps.Add(prop.Set, prop.Name,
(DateTime)prop.Value);
}
}
Filtering APIs 511
IIndexProperty :: Searchable
IIndexProperty :: Searchable
This property indicates whether the property can be returned in search results
when using the Search API.
Syntax
bool Searchable {get;}
512 Filtering APIs
IIndexProperty :: Retrievable
IIndexProperty :: Retrievable
This property indicates whether the index property can be retrieved and
displayed with search results when using the Search API.
Syntax
bool Retrievable {get;}
Filtering APIs 513
IKeyedList interface
IKeyedList interface
This interface enables multiple filters to access a list of filter properties. The
collection allows both random access by index and keyed access using a key
value.
Syntax
public interface IKeyedList : ICollection, IDictionary, IEnumerable
Member summary
Table 7-12 IKeyedList methods
Method Description
Insert Inserts a filter property into the list at the specified position.
RemoveAt Removes a filter property from the specified position in the list.
See also
■ “IArchivingControl :: FilterProperties” on page 489.
514 Filtering APIs
IKeyedList :: Insert
IKeyedList :: Insert
Inserts a filter property into the list at the specified position.
Syntax
void Insert(System.Int32 index, System.Object key,
System.Object value);
Parameters
System.Int32 index The position to insert into the list.
System.Object key The key for the filter property.
System.Object value The value of the filter property.
Remarks
The elements that follow the insertion point are moved down to accommodate
the new element.
If index equals the number of items in the list, then the value is appended at the
end of the list.
An exception is reported if the specified index is out of range.
Filtering APIs 515
IKeyedList :: RemoveAt
Removes a filter property from the list at the specified position.
Syntax
void RemoveAt(Int32 index);
Parameter
Int32 index The position in the list.
Remarks
The elements that follow the removed element move up to occupy the vacated
spot.
An exception is reported if the index is out of range.
516 Filtering APIs
Chapter 8
Search API
This chapter describes the Search API which enables third-party applications to
search the indexes of Enterprise Vault archives.
Introduction to storing and indexing

The Enterprise Vault Storage service accepts items for archiving from the
archiving tasks. If possible, it generates a text or HTML version of each item,
which the Indexing service uses to compile indexing data for the item. The
Storage service compresses and stores the items (and the text or HTML
versions) as savesets in the appropriate archives. Information about each item
that is archived is stored in the vault store database. The Storage service also
responds to requests from the retrieval tasks to restore items.
The Indexing service manages the indexes of archived data to enable users to
search for archived items that they want to retrieve. The role of the Indexing
service can be summarized as follows:
■ On instruction from the Storage service, the Indexing service indexes items
as they are archived. There can be one to many indexes (index volumes) per
archive.
The locations of index files are specified in the Indexing service properties
in the Enterprise Vault Administration Console.
■ In response to search requests from the Enterprise Vault Web access
components, or third-party search applications using the Search API, the
Indexing service searches these indexes and returns information about the
archived items that match the search criteria.
■ The Indexing service ensures that indexes are complete and up to date. If an
index is out of date, the Indexing service automatically updates the index.
In Enterprise Vault you can set the required level of indexing. If required,
different levels can be set for different groups of users. There are three levels of
518 Search API
Introduction to storing and indexing
indexing: brief, medium and full. Each level extends the searches that users can
perform:
■ Brief indexing. This enables users to search on attributes of an archived
item such as Author, Subject, Recipients, Created Date, File Extension,
Retention Category and so on. With brief indexing, the content of the item
is not indexed.
■ Medium indexing. This enables users to search attributes, as for brief
indexing, as well as searching content. It does not provide phrase searching
in content.
■ Full indexing. This enables users to search as for medium indexing, and also
provides searching for phrases in content.
Obviously, the more information that is indexed, the more disk space is required
for the index.
For example, for brief indexing, the index size is approximately 3% of the size of
the data that is indexed. For medium indexing, the figure is approximately 8%
and for full it is approximately 12% (depending on the type of documents).
The level of indexing, and when an item is indexed for a particular archive can
be controlled using the Content Management API.
See “IArchive :: IndexLevel” on page 136.
See “IArchive :: IndexUrgency” on page 134.
The content and attachments are indexed if there is a content converter
available for the file type, and the converted content does not exceed the
configured size limits (by default, 30 MB after conversion to HTML or text).
If the content cannot be indexed, a 'content missing' reason is indexed using the
"comr" property.
See “System properties” on page 664.
See “ETruncationReason enumeration” on page 536.
Enterprise Vault indexes

Each archive index comprises one or more sequential index volume sets. An
index volume set contains an index volume. (Currently, an index volume set can
contain only one index volume). Each index volume contains index entries for
the items stored in the archive. Each Enterprise Vault archive can have one or
more associated index volumes.
When an index volume is full, the Enterprise Vault Indexing service
automatically creates a new index volume (in a new index volume set). The
Enterprise Vault administrator uses the Enterprise Vault Administration
Console to configure the physical locations to be used by the Indexing service
when creating new indexes and index volumes.
Search API 519
Using the Search API
Figure 8-1 An archive index
Typically, user mailbox indexes require only a single volume. Indexes for larger
archives, such as file system archives and journal archives, are quite likely to
have multiple volumes.
When a user or application performs a search on an archive, the search is
performed on index volumes associated with the archive, not the archive itself.
For more information on Enterprise Vault indexes, see “About index volume sets
and volumes” on page 659.

For programming notes on using Enterprise Vault APIs with .NET managed
code, and information about code samples in this manual, see “Programming
notes” on page 46.
All the components required for using the Search API are contained in
IndexClient.dll.
■ SearchQuery object is used to construct search queries.
520 Search API
■ IndexVolumeSets object enables access to a collection of IndexVolumeSet

objects.
■ IndexVolumeSet object provides properties that expose information about
the index volume set.
■ IndexSearch2 object is used to select an index to search, and submit a
search query to return some search results.
■ SearchResults object is used to enumerate through a set of search results.
■ SearchResult object is used to enumerate through the index property values
returned for each search hit (search result).
The process of using the Search API is, brief, as follows:
■ Get an instance of the Search Query object. You can do this in the usual
manner using CoCreateInstance directly (C++), or indirectly using the new
operator (.NET managed code).
■ Build the query. You do this by adding various terms and operations to the
query object using the ISearchQuery2 interface properties and methods.
See “Constructing a search query” on page 520
■ Get an instance of the IndexSearch2 object and submit the search by calling
the Search method of IndexSearch2 interface.
See “Performing a search” on page 524
■ This returns a SearchResults object, which in turn is used get SearchResult
object instances for each of the search hits returned in the SearchResults
object. (You do not have to obtain or create the SearchResults or
SearchResult objects).
See “Processing the search results” on page 527
Constructing a search query

Take for example the following query expressed in words:
The email Author is John Doe or Alan Smith, and its Subject contains the
phrase “Financial Reports”, and its Document Date is earlier than 17 May
2001.
This query can be broken down into its constituent parts.
There are three properties (in a SQL query, these would be the fields or columns
in a table):
■ Author
■ Subject
■ Document Date
Search API 521
In order to find the correct emails, we need to attach search conditions to each
of these properties:
■ Author - is either John Doe or Alan Smith
■ Subject - this must contain the phrase "Financial Reports"
■ Document Date - this must be earlier than 17th May 2001
The words in italics are the operators within the query.
The Search API does not have a "less than" or "greater than" operator so it will
be necessary to use a Range for the Document Date:
■ Document Date - this must be between 1st January 1900 and 16th May 2001
The query can now be rewritten as follows:
Find All emails where Author = ("Fred Bloggs" or "John Smith") and (Subject
contains the phrase "Financial Reports") and (Document Date is between
"1st January 1900 and 17th May 2001")
The property name, for example, Author, would normally be one of the
Enterprise Vault system index property names.
“System properties” on page 664.
In addition to system property names, custom properties defined by the user can
also be used.
Any number of terms can be added to a SearchQuery object. By default, they are
all combined using the AND operator. Different operators can be specified using
the Combine, AddOp, or AddQuery methods:
■ Combine takes two SearchQuery objects, each containing one or more terms
and an operator. The method creates a new search query containing all the
terms in both objects, combined with the specified operator. This new query
can be used in a further Combine operation to create searches of arbitrary
complexity.
■ AddQuery is similar to Combine, but instead of taking two SearchQuery
objects and combining them to create a third, it incorporates the second
object into the first.
■ AddOp combines one or more of the terms previously added to the
SearchQuery object with the specified operator.
All three methods can be used interchangeably, and at different stages in the
construction of a single search query. Which approach you use depends solely
on your preference.
To start to construct the earlier example query, you use the AddTerm method of
the ISearchQuery interface. AddTerm has the parameters: property, value,
search query flag. If SetTerm is used, it clears out any previous query.
522 Search API
The search query flag determines how to process individual terms added to a
search query.
See “ESearchQueryFlags enumeration” on page 533.
The first term could be added to the query as follows:
AddTerm(IndexPropAUTH, "John Doe", ESQPhrase);
Then the second term could be added to the query as follows:
AddTerm(IndexPropAUTH, "Alan Smith", ESQPhrase);
Now the above terms need to be combined using the OR operator. This is done
using the AddOp method:
AddOp(ESQor, ESQBinary)
The query is built up using a reverse polish system; the operator is applied to the
previous x 'objects' to create a new one, where x is determined by the value of the
second parameter to AppOp, the search object scope.
See “ISearchQuery :: AddOp” on page 554.
The operator itself can be obtained from the ESearchQueryOperators
enumeration.
See “ESearchQueryOperators enumeration” on page 534.
In the example query, two more terms can now be added; the Subject term and
the date range term:
AddTerm(IndexPropSubj, "Financial Results", ESQPhrase)
AddRange(IndexPropDate, 1st January 1900, 16th May 2001, ESQany)
(In reality, you would use the appropriate DateTime object for the programming
language being used).
The three parts of the query need to be combined using the AND operator. (The
first part is the result of the first call to AddOp. The second and third parts are
the terms being added in this operation):
AppOp(ESQand, ESQQternary)
The resulting query now represents the original query that was expressed in
words. The constructed query can be used by the Search method of the
IndexSearch2 interface to search the index of an archive.
The search query operator, ESQfilter, is a special operator for performing
complex searches, such as those required by the Enterprise Vault Compliance
and Discovery Accelerator products.
See “ESQfilter searches” on page 522.
ESQfilter searches
ESQfilter is similar to ESQ but more powerful. The following summarizes how
this operator works:
Search API 523
■ A search is performed using the first query. This searches top-level items
only. (For example, this term could specify a date range to be searched).
■ A separate search is performed using subsequent queries. This searches
both top-level items and attachments. (For example, words in message
subject or content).
■ The results are compared and any result from the second search which has
an associated top-level item that matches a result from the first query
search is added to the results.
Only top-level items are returned in results; if a search query is satisfied in an
attachment, the associated top-level item is returned in results.
Note that the Options setting of the Search method is ignored if the search uses
the operator ESQfilter.
This type of search is particularly efficient for compliance or discovery type
searches. For optimum performance, it should be used together with the
ItemGranularityOnly index schema.
See “About index schemas” on page 660.
Special characters in search queries

In addition to the search query flags, the string value being searched for can
contain special characters to modify the search behavior. Individual words are
normally separated with spaces.
■ If words are separated by punctuation (the period is preferred, but most
punctuation has the same effect), they are treated as a sub-phrase. For
example, if "white blue.green" is specified with ESQany, then the search will
look for items containing the single word "white" or the phrase "blue
green".
■ If a word or sub-phrase is preceded by + (a single plus character), that word
must be found. For example, "white blue +green" means find items
containing the word "green", plus at least one of "white or blue".
■ If a word or sub-phrase is preceded by - (a single minus character), that
word must not be found.
For example, "domain1.com -domain2.com". This finds items sent to
"domain1.com" that were not also sent to "domain2.com".
■ If the entire string is being treated as a single phrase anyway (for example,
ESQphrase), none of the above values has any effect.
■ To search using wildcards, use an asterisk (*) to find zero or more
characters, and a question mark (?) to find any single character. For
example, 'min*' matches the words 'minutes', 'minimum', and so on.
524 Search API
There must be at least three other characters before a wildcard.

Finally, words like "and" and "or" have no special meaning in query values (and
cannot be given any special meaning). They will be searched for like any other
word. So, for example, to search for documents containing both "financial" and
"hint", search for the string "financial hint" using ESQall.
Performing a search
The index is searched using the methods and properties of the IIndexSearch2
interface.
Before initiating the search, set requirements for the search and search results
using methods and properties of the IIndexSearch2 interface:
■ SelectArchive method. Use this to specify the index to search. The index is
identified using the Id of the associated archive.
You can use the vault store and archive enumeration functionality in the
Content Management API to find the target archive.
The Id of an archive can also be discovered using the Enterprise Vault
Administration Console:
■ In the Enterprise Vault Administration Console, double-click the
archive to display the properties dialog and click the Advanced tab. The
archive Id is displayed on the advanced properties page.
■ SelectIndexVolumeSet method. If you do not want Enterprise Vault to
perform a federated search across multiple index volumes, use this method
to set the Id of the archive's index volume set to search.
See “Searching indexes with multiple volume sets” on page 525
■ Options property. Use this to set the required granularity of the search:
■ roItemGranularity. Only top-level items are searched, not attachments.
■ roAttachmentGranularity. Both top-level items and attachments are
searched.
Note that the Options setting is ignored if the search uses the operator
ESQfilter.
See “ESQfilter searches” on page 522
■ AdditionalResultsProperties property. Use this to set the required
properties to be returned in results. (Use AdditionalResultsProperties in
preference to the ResultsPropertySet property).
■ SortBy property. Use this to specify the required sort order of the results.
After setting the required properties, you initiate the search using the Search
method.
Search API 525
The query is passed to this method as a query string. In most cases this query
string is created using the methods of ISearchQuery2 interface. The Query
property returns the string that has been constructed and can be passed to the
Search method.
Use the Search method parameters, startResult and maximumResults to specify
the number of results to return at one time. This enables you to "page" through
the results.
The output from a search is a pointer to a SearchResults object, which provides a
structured way to access the results. The object provides standard collection
support enabling iterative operations on the results in the collection, such as
"for each" in Visual Basic, and .NET managed code.
Concurrent searches
To optimize performance, applications using multiple search threads should
search different archives or index volume sets.
Searching indexes that are changing during the search

It is quite possible that items are being added to, or removed from, the index
while a search is being performed. If this is the case, we recommend that you use
the index sequence number (IndexPropertySNUM) of an item to specify the start
of the batch of search results returned. The size of each batch is defined by the
maximumResults parameter of the Search method.
When using the index sequence number to define the batch of search results to
return, do the following:
■ Always order results by increasing sequence number
(IndexPropertySNUM), and ensure that the sequence number property is
returned in the search results.
■ When processing a batch of search results, the highest sequence number in
the results should be recorded; this should be the last one in the batch.
■ To get the next batch of results, amend the search query to return results
with a sequence number (IndexPropertySNUM) greater than that recorded
at the end of the previous batch of results.
Repeat this until no more results are found.
Searching indexes with multiple volume sets

Enterprise Vault automatically performs a federated search across multiple
index volumes if the following criteria are met:
■ An index volume set is not selected using SelectIndexVolumeSet.
526 Search API
■ An archive has multiple index volumes, and the number of index volumes is
less than, or equal to MaxSearchIndexVolumeSets (default 5).
If an archive has more than five index volumes, then you can either increase the
number to be searched by setting the value of MaxSearchIndexVolumeSets, or
use SelectIndexVolumeSet to select the index volume set to search.
Use MaxSearchResultsPerVolumeSet to set the maximum number of results per
volume set that can be processed and merged during a federated search (default
is 1000).
Be aware that increasing these default settings could result in a time out.
If it is necessary to select a specific volume set then after calling SelectArchive,
a call to IndexVolumeSets returns a collection of IIndexVolumeSet pointers
from which the ID can be obtained.
See “IndexSearch object” on page 564.
Creating multiple index volume sets for testing

In a test environment, an archive typically only has one index volume set
because the number of archived items is relatively low. However, there are
several properties and methods that are only tested when multiple index volume
sets exist. In particular, when developing non-federated search applications, the
scope for testing is very limited if there is only one index volume set available.
You can use the registry setting, AVSMaxLoc, to create multiple index volume
sets for testing purposes. This setting lets you configure the number of index
locations used before a new index volume set is created.
Setting Setting Content Description

name location
AVSMaxLoc HKEY_LOCAL_MACHINE DWORD. Maximum location value

\SOFTWARE Default value is allowed in an index.
\KVS
1,000,000,000 Typically used to prevent
\Enterprise Vault
indexes from exceeding their
\Indexing maximum size.
In test scenarios, can be used to
create multiple index volume
sets.
Can be specified per index by
creating the values below a key
with value equal to the Index
entry-id.
Search API 527
To create multiple volume index sets for testing

1 Ensure that the archive's indexing level is set to Full.
2 Open regedit, and navigate to the Indexing registry key at the location
shown above. If either the Indexing key or AVSMaxLoc do not exist, then
create them.
3 Set the value of AVSMaxLoc to something like 2,500,000. It must have a
value greater than 2,000,000.
4 Archive items with large content or attachments that contain a large
number of words.
Continue to archive large items until six or more index volumes have been
created. (If AVSMaxLoc is set to 2,500,000, this would mean that
approximately 6 * 2,500,000 words have been indexed).
This ensures that the number of index volumes is greater than the default
federation search threshold (5), and should ensure that there are more
items per index volume than the default maximum results per index volume
for federation searches (1000).
Alternatively, if you already have a large test index, you can change the
value of AVSMaxLoc and then rebuild the index using the Enterprise Vault
Administration Console. The option for rebuilding indexes is on the Index
Volumes tab of Archive properties in the Enterprise Vault Administration
Console.
Processing the search results

The SearchResults object is a collection of results returned by IndexSearch. (The
implementation of ISearchResults2 contains a collection of ISearchResult2
interface pointers). The first result in the collection, and the maximum number
of results returned in the collection are defined by the startResult and
maximumResults parameters to the Search method.
The SearchResults object has several properties, including the following:
■ Count. This is the number of results in the object; that is, the size of the
current collection.
■ Total. This is the total number of results for the search.
You can access the data for each result returned using the methods of
ISearchResult2.
Only top-level items are returned in results if any of the following are
configured:
■ Searching is limited to top-level items using roItemGranularity option in
the Search method.
528 Search API
■ The search query includes the ESQfilter operator. Attachments are

searched but the associated top-level item is returned in results.
■ The ItemGranularityOnly index schema is enabled. Attachments are
searched but the associated top-level item is returned in results.
Remember, a search result is not the archived item; it is a set of properties
containing information about the item. To retrieve the archived item, use the
Get method of the IItem interface in the ContentManagementAPI.
To access the properties of each result, use the Prop method of the SearchResult
class, specifying the required property as the parameter.
Enterprise Vault index properties

Enterprise Vault index properties are listed in “System properties” on page 664.
When using the Search API, Enterprise Vault property names are defined as
constants in the form IndexPropXXXX. See “Index Property constants” on
page 533.
There are Enterprise Vault system properties and custom properties. Custom
properties are typically defined and added as items are archived by third-party
components using the APIs and plug in points provided by Enterprise Vault.
Properties are defined as searchable, or retrievable or both:
■ Searchable means that the property can be used in search queries to find
items in the archive index.
■ Retrievable means that the property can be returned in search results.
Custom properties can be referenced using propertySet.propertyName,
with propertySet empty for the global property set. In many cases there are
custom property specific versions of methods that allow the propertySet and
propertyName string separately.
Search API Example

Shown here are two methods that demonstrate a search.
The first method, 'SearchArchive’, takes an archive Id and the maximum
number of search results as parameters. 'SearchArchive' compares the number
of Index Volume Sets in the archive against the value of the property
IIndexSearch2::MaxSearchIndexVolumeSets to determine whether a federated
or non-federated search is required.
The second method 'DoSearch' is then called. 'DoSearch' takes two parameters,
the IndexSearch2 object created in 'SearchArchive', and the maximum number
Search API 529
of search results. If the search is not a federated search, then this second
parameter is zero.
void SearchArchive(string archId, int maxSearchResults)

{
IIndexSearch2 search = (IIndexSearch2) new IndexSearch2();
//First select the archive

search.SelectArchive(archId);
//although the prefered approach is to do a non-federated search this sample

//code will demonstrate both non-federated and federated
//first get the IndexVolumeSets for the archive
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;
long count = volSets.Count;
//use this count value to see which approach to take

if (count > search.MaxSearchIndexVolumeSets)
{
//do non-federated search
foreach (IIndexVolumeSet volSet in volSets)
{
search.SelectIndexVolumeSet(volSet.Identity);
DoSearch(search, 0);
}
}
else
{
DoSearch(search, maxSearchResults);
}
Marshal.FinalReleaseCOMObject(search);
}
The DoSearch method, called from 'SearchArchive' performs the actual search
on the entire archive, or the specifed Index Volume Set, depending on whether
or not the search is a federated search.
The search will filter on a range of archived dates, a phrase in the subject,
greater than zero attachments and the author.
The retrieved properties are created date, content (first 150 characters only),
saveset Id, number of attachments, subject, TO:recipient, CC:recipient,
BCC:recipient.
Typically the property values in the query would be supplied using a GUI or a
command line. However, for the purposes of this example, they are supplied in
the code.
530 Search API
void DoSearch(IIndexSearch2 search, int maxSearchResults)

{
ISearchQuery2 query = (ISearchQuery2) new SearchQuery2();
DateTime dtFrom = new DateTime(2007, 1, 1);

DateTime dtTo = new DateTime(2007, 12, 31);
query.SetRange("adat", dtFrom, dtTo, (int)ESearchQueryFlags.ESQany);

query.AddRange("natc", 0, 10000, (int)ESearchQueryFlags.ESQany);
query.AddTerm("subj", "a phrase in the subject",
(int)ESearchQueryFlags.ESQphrase);
query.AddTerm("auth", "joe.user", (int)ESearchQueryFlags.ESQexact);
query.AddOp((int)ESearchQueryOperators.ESQand, 4);
search.SortBy = "snum";
//if this is a federated search then set the maximum number of search
//results per index volume set
//if this is not a federated search then 'maxSearchResults' will be 0 and
'MaxSearchResultsPerVolumeSet' will not be used.
if (maxSearchResults > 0)
search.MaxSearchResultsPerVolumeSet = maxSearchResults;
//we are going to search top level items only

search.Options = (int)EOptionsFlags.roItemGranularity;
//As the preferred method is to explicitly state which properties to

//retrieve, first set IIndexSearch2::ResultsPropertySet to Empty.
search.ResultsPropertySet = (int)EPropertySet.psEmpty;
search.AdditionalResultsProperties = "date ssid natc subj cont
reto recc rbcc";
int start = 1; //this is the index number into the results from which to
start returning the result set
int count = 0;
ISearchResults2 results = null;
do
{
results = (ISearchResults2)search.Search(query.Query, start, 500, "");
if (results.InSync == true)
{
if (results.TruncationReason == ETruncationReason.trNone)
{
//make sure that date time properties are returned as local
//system time not UTC
results.DateTimesUTC = false;
Search API 531
foreach (ISearchResult2 result in results)

{
DateTime createdDate = (DateTime)result.Prop("date");
string ssid = (string)result.Prop("ssid");
int numAttach = (int)result.Prop("natc");
string subj = (string)result.Prop("subj");
string reto = (string)result.Prop("reto");
string rbcc = (string)result.Prop("rbcc");
//do something with the results

}
}
else
{
ETruncationReason tr = (ETruncationReason)results.TruncationReason;
switch (tr)
{
case ETruncationReason.trAdminResultLimitExceeded:
//do something
break;
case ETruncationReason.trAdminTimeoutExpired:
//do something
break;
case ETruncationReason.trItemsOrContentMissing:
//do something
break;
case ETruncationReason.trNotSearchedOrFailedVolumes:
//do something
break;
case ETruncationReason.trResultLimitExceeded:
//do something
break;
case ETruncationReason.trTimeoutExpired:
//do something
break;
case ETruncationReason.trWidthNormalizationRequired:
//do something
break;
}
}
}
else
{
MessageBox.Show("It is possible that the index was being updated as the
search was being carried out",
"Index not synchronised?", MessageBoxButtons.OK,
MessageBoxIcon.Warning);
}
count = results.Count;
Marshal.FinalReleaseCOMObject(results);
results = null;
532 Search API
start += 500;
}
while (count != 0);
Marshal.FinalReleaseCOMObject(query);
}
Search API 533
Constants and enumerations

This section describes the constants and enumerations used by the Search API.
Index Property constants

When using the Search API, Enterprise Vault property names are defined as
constants, where IndexPropXXXX is the constant for the property name, xxxx, in
Table B-1 on page 664. For example, IndexPropSUBJ is the constant for the
Enterprise Vault defined property, "subj", and IndexPropRCAT is the constant
for the Enterprise Vault system property, "rcat".
ESearchQueryFlags enumeration
ESearchQueryFlags specify how to process individual terms added to a search
query (for example, using AddTerm).
Note: From Enterprise Vault 10, the Search API will not support the following
search operators for newly indexed items:
ESQBeginany begins with any of
ESQBegins begins with phrase
ESQExactany is exactly any of
ESQEndsany ends with any of
ESQEnds ends with phrase
ESQAutowild automatically add wildcard to end of all words
Using these search operators against items that were indexed using Enterprise
Vault 9 or earlier will continue to be supported.
enum ESearchQueryFlags
{
// Exactly one of these must be present (default is ESQany)
ESQany = 0, // Contains any of the words
ESQall = 1, // Contains all the words
ESQallnear = 2, // Contains all the words, near each other
(within 10 words)
ESQphrase = 3, // Contains all the words, in order (a phrase)
ESQbeginany = 4, // Begins with any of the words
ESQbegins = 5, // Begins with all the words in order (a phrase)
ESQexactany = 6, // Field exactly matches any of the words
ESQexact = 7, // Field exactly matches all the words, in order
534 Search API
ESQendsany = 8, // Ends with any of the words

ESQends = 9, // Ends with all the words in order (a phrase)
ESQmatchmask = 15, // Mask to isolate above values from
flags below
// Zero or more of the following may be present
ESQrank = 64, // Use words for results ranking
ESQusermask = 1048575 // User must not set bits outside this mask
};
By default indexes are built so that they do not support case sensitive searching.
This is to minimize the index storage footprint.
The specified operator applies to the terms or ranges already present in the
object, using a Reverse Polish scheme. Conceptually, the specified number of
terms is removed from the query, and replaced with the result of combining all
the terms with the specified operator. This result can then be combined with
other terms or intermediate results by a subsequent AddOp method.
ESearchQueryOperators enumeration
ESearchQueryOperators specify the operator to use. These operators can be
used with the AddOp, Combine and AddQuery methods.
enum ESearchQueryOperators
{
ESQand = 0,
ESQor = 1,
ESQandnot = 2,
ESQfilter = 3
};
Using ESQfilter will only return hits on top-level documents. The search finds
items that match the first query and which also match, or have a cover note or
attachment that matches, all the other queries.
ESearchOperatorScope enumeration
ESearchOperatorScope defines the number of operands on which an operation
is to be performed.
enum ESearchOperatorScope
{
ESQdefault = 0,
ESQscopeall = 1,
ESQbinary = 2,
ESQternary = 3
};
If no value is given, the default is for the operator to be binary (two operands).
The ESearchOperatorScope is a useful extension to the "Reverse Polish" scheme
used by the AddOp method, enabling a single operator to have more than two
Search API 535
operands. For more than three operands, there are no symbolic constants, so the
required number should be specified.
Note the value of the scope is the number of operands, not the number of
operations (which, when thinking of conventional binary operators, would be
one less than the number of operands).
EOptionsFlags enumeration
EOptionsFlags defines the granularity of searches.
enum EOptionsFlags
{
roItemGranularity = 0x00000000,// default
roAttachmentGranularity = 0x00000001,
};
This setting is ignored if the search uses the operator ESQfilter.
Using roItemGranularity, only top-level items are searched (not attachments).
Using roAttachmentGranularity, both top-level items and attachments are
searched.
EPropertySets enumeration
EPropertySets are the predefined property sets that can be requested in search
results.
As the predefined property sets may change at future releases, we recommend
that you set this property to 0 (psEmpty) and use “IIndexSearch2 ::
AddAdditionalResultsProperty” and “IIndexSearch2 ::
AddAdditionalResultsCustomProperty” to set the required properties to be
returned in the results set.
enum EPropertySets
{
psEmpty = 0,
psWABrief = 1,// default
psWAMedium = 2,
psWAFull = 3,
psAEMailbox = 4,
psAEFSA = 5,
psAESPS = 6,
psAEMultiFolders = 7,
psCompliance = 8,
psItemIds = 9,// Min set of ids needed to retrieve the item.
psAEShared = 10,
psAEJournal = 11,
psAEPublicFolder = 12,
psAESharePoint = 13
};
536 Search API
ETruncationReason enumeration
ETruncationReason explains why not all search results have been returned.
enum ETruncationReason
{
trNone = 0,
trResultLimitExceeded = 1,
trTimeoutExpired = 2,
trAdminResultLimitExceeded = 4,
trAdminTimeoutExpired = 8,
trNotSearchedOrFailedVolumes = 16,
trItemsOrContentMissing = 32,
trWidthNormalizationRequired = 64
};
trNotSearchedOrFailedVolumes applies to federated searches only. The
index contents for the whole archive cannot be listed. This can occur when one
or more of the index volume sets are in a failed state; they could be, for example,
offline or corrupt.
trItemsOrContentMissing indicates that index entries are missing for items
or content in archive.
trWidthNormalizationRequired is set for old indexes where character
width normalization was not applied to East Asian languages.
See http://entsupport.symantec.com/docs/289566
EXMLResultsFormatOptions enumeration
EXMLResultsFormatOptions enumerates the XML format option values.
Currently there is only one value:
enum EXMLResultsFormatOptions
{
xoNone = 0x00000000// default
};
Search API 537
SearchQuery object
SearchQuery object
The SearchQuery object implements the following interfaces:
■ ISearchQuery
■ ISearchQuery2 (default)
These interfaces are used to build up a search query. Some additional methods
have been introduced in ISearchQuery2, which inherits from ISearchQuery.
You need to get a pointer to an instance of ISearchQuery2, as this is marked as
the default.
Syntax
interface ISearchQuery2 : ISearchQuery : IDispatch
Member summary
ISearchQuery :: Query Read/Write The search query string.
Method Description
ISearchQuery :: Clear Discards the query currently being constructed in

the object (if any), and resets the object so that it is
ready for a new query.
ISearchQuery :: SetTerm Implements Clear, followed by AddTerm.
ISearchQuery :: AddTerm Adds a search term to the query.
ISearchQuery :: SetRange Implements Clear followed by AddRange.
ISearchQuery :: AddRange Adds a date or integer range to the query.
ISearchQuery :: SetProperty Implements Clear followed by AddProperty.
ISearchQuery :: AddProperty Adds a property to the query.
ISearchQuery :: AddOp Adds an operation to the query.
ISearchQuery :: Combine Combines two search queries with an operator.
ISearchQuery :: AddQuery Similar to combine, but combines a query with the

query already in the object.
538 Search API
SearchQuery object
Method Description
ISearchQuery2 :: SetPropertyRange Equivalent of SetRange method. Enables use of

date and integer ranges for custom properties in
queries.
ISearchQuery2 :: AddPropertyRange Custom property equivalent of AddRange method.

Enables use of date and integer ranges for custom
properties in queries.
Remarks
As these interfaces are ultimately derived from IDispatch, they can be used by
scripting languages.
Use the methods to create a query that can be used to search the index of an
archive, and return the values of specified properties as results.
A query consists of a number of terms, combined with different operators.
The Query property enables the query to be returned as a string (so that it can
then be used by the Search method), or to be set using a text string.
Requirements
CLSID B94D399B-B815-11D1-90D2-0000F87A3B5E
Prog ID EnterpriseVault.IndexSearch
Type Library EVIndexClient
DLL IndexClient.dll

Assembly (PIA) KVS.EnterpriseVault.Interop.Indexclient.dll
Example
The object 'query' constructed here will be used in the most of the following
examples. It is shown here as a private class data member.
Search API 539
SearchQuery object
C#
public class SampleSearchClass
{
private ISearchQuery2 query = (ISearchQuery2)
new SearchQuery();
//rest of the class
540 Search API
ISearchQuery :: Query
ISearchQuery :: Query
The Query property is the default property. It returns a string containing the
query previously constructed.
Syntax
HRESULT Query([out, retval] BSTR* pbsQuery);
HRESULT Query([in] BSTR bsQuery);
Parameters
[out, retval] BSTR* pbsQuery Pointer to a string (BSTR) that will contain the
query held in this object.
[in, string] BSTR bsQuery String (BSTR) containing the query with which
to initialize the object.
Remarks
This property returns the query string that has been constructed using the
other ISearchQuery2 methods.
Return value
rvS_OK Success.
Example
This method is often used in conjunction with IIndexSearch2::Search where it
provides the value for the first parameter, the search query.
C#
ISearchResults2 results2 = (ISearchResults2)search.Search(query.Query, 1, 100, "");
Search API 541
ISearchQuery :: Clear
ISearchQuery :: Clear
This method discards the query currently being constructed in the object (if
any), and resets the object so that it is ready to build a new query.
Syntax
HRESULT Clear([out, retval] BSTR* pbsQuery);
Parameters
[out, retval] BSTR* pbsQuery A pointer to a string (BSTR) that contains the
contents of the query string before it was cleared
out.
Remarks
Clears out the string containing the query that has been constructed so far.
Return value
rvS_OK Success.
Example
In this example the previous query is stored in the string 'oldQuery'.
C#
//save the query that is being cleared out
string oldQuery = query.Clear();
542 Search API
ISearchQuery :: SetTerm
This method is used to clear the current query object, reset it and add a new
term (property) to the query. This is equivalent to calling the Clear method and
then calling the AddTerm method.
Syntax
HRESULT SetTerm([in, string] const BSTR bsProp,
[in] VARIANT vVal,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);
Parameters
[in, string] const BSTR bsProp The name of the property to be

searched for.
[in] VARIANT vVal VARIANT containing value for which

for which to search. This can be a string,
date or integer.
[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the terms added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.
[out, retval] BSTR* pbsQuery Pointer to a string (BSTR) that contains

the current value of the query string
after this method has returned.
Remarks
If the bsProp parameter is left empty, then all indexed properties are searched
for the value. This is really only useful for string values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. This would be specified using the format:
propertySet.propertyName
If the custom index property is a member of the global property set, then the
property set name is omitted.
The parameter lFlags must contain one value from “ESearchQueryFlags
enumeration” on page 533. This value may be bitwise OR'd (C++ operator ‘|’)
with one or more values from the extended values.
Search API 543
Return value
rvS_OK Success.
Example
In this example a query is constructed that will find all items where the subject
contains the phrase 'some subject', and the number of attachments is 1. In this
example the return value is not used.
C#
//search for an item where the subject contains the phrase "some subject"
query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);
//search for an item with 1 attachment
query.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);
//now we AND the 2 terms so that both terms must be satisfied before returning a result
query.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);
See also
■ “ISearchQuery :: AddTerm” on page 544
544 Search API
ISearchQuery :: AddTerm
This method is used to add a new term (property) to the query.
Syntax
HRESULT AddTerm([in, string] const BSTR bsProp,
[in] VARIANT vVal,
Parameters
Table 8-1 AddTerm method parameters
Parameter Description
[in, string] const BSTR bsProp The name of the property in which to
search for the value.
[in] VARIANT vVal VARIANT containing value for which to

search. This can be a string, date or
integer.
process the terms added to the search
query.
on page 533.
[out, retval] BSTR* pbsQuery Pointer to a string that contains the

current value of the query string after
this method has returned.
Remarks
If the bsProp parameter is left empty, than all indexed properties are searched
for the value. This is really only useful for string values.
property_set_name.property_name
Search API 545
The parameter lFlags must contain one value from table “ESearchQueryFlags
enumeration” on page 533, this value may be bitwise or'd (C++ operator ‘|’) with
one or more values from the extended values.
Return value
rvS_OK Success.
Example
In this example a query is constructed that will find all items where the subject
contains the phrase 'some subject' and the number of attachments is 1. In this
C#
//now we AND the two terms so that both terms must be satisfied before returning a
result
See also
■ “ISearchQuery :: SetTerm” on page 542
■ “ISearchQuery :: AddProperty” on page 552
546 Search API
ISearchQuery :: SetRange
This method is used to delete all queries in the query object, reset the object and
add a date or numeric (integer) range to the query being built in the object. This
is equivalent to calling Clear then AddRange.
Syntax
HRESULT SetRange([in, string] const BSTR bsProp,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
Parameters
[in] VARIANT vVal1 The first value in the range. This can be
date or integer.
[in] VARIANT vVal2 The last value in the range. This can be
date or integer.
process the range added to the search
query.
on page 533.

Remarks
This method can only be used with date or integer values. Currently date values
are always treated as local system date/time values.
propertySet.propertyName
Search API 547
vVal1 and vVal2 must be the same type.

enumeration” on page 533. Currently, however, none of the Search Query Flags
has any effect on range searches.
Return value
rvS_OK Success.
Example
This example builds a query that will find items archived between 01/01/2008
and 21/10/2008 inclusive, or that have less than five attachments.
C#
//search for all items archived between 01/01/2008 and 31/10/2008 inclusive
DateTime from = new DateTime(2008, 1, 1);
DateTime to = new DateTime(2008, 10, 31);
query.SetRange("adat", from, to, (int)ESearchQueryFlags.ESQany);
//search for items with less than 5 attachments
//OR the 2 terms together so the result set will contain items that fall into one or
the other (or both) ranges
query. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);
See also
■ “ISearchQuery :: AddRange” on page 548.
548 Search API
ISearchQuery :: AddRange
This method is used to add a date or numeric integer range to the query being
built in the object.
Syntax
HRESULT AddRange([in, string] const BSTR bsProp,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
Parameters
[in] VARIANT vVal1 The upper or lower boundary of the

range. This can be date or integer.
[in] VARIANT vVal2 The upper or lower boundary of the

range. This can be date or integer.
query.
on page 533.

Remarks
This method can only be used with date/time or integer values.
Currently, date values are always treated as local system date/time values.
property_set_name.property_name
Search API 549

Return value
rvS_OK Success.
Example
This example builds a query that will find items archived between 01/01/2008
and 21/10/2008 inclusive, or that have less than five attachments.
C#
//search for all items archived between 01/01/2008 and 31/10/2008 inclusive
DateTime from = new DateTime(2008, 1, 1);
DateTime to = new DateTime(2008, 10, 31);
query.SetRange("adat", from, to, (int)ESearchQueryFlags.ESQany);
//search for items with less than 5 attachments
//OR the 2 terms together so the result set will contain items that fall into one or
the other (or both) ranges
query. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);
See also
■ “ISearchQuery :: SetRange” on page 546.
550 Search API
ISearchQuery :: SetProperty
This method clears all queries from the query object, resets the object, and adds
a custom property that can be used for searching.
This is equivalent to calling Clear then AddProperty.
Syntax
HRESULT SetProperty([in, string] const BSTR bsPropSet,
[in, string] const BSTR bsProp,
[in] VARIANT vVal,
Parameters
[in, string] const BSTR bsPropSet Name of the property set.
[in, string] const BSTR bsProp The name of the custom property to
search for.
[in] VARIANT vVal VARIANT containing value to search for.

This can be a string, date or integer.
query.
on page 533.
[out, retval] BSTR* pbsQuery Pointer to a string containing the query

as it stands after this method returns.
Remarks
Note that SetTerm can also be used to set a term for a custom property using the
propertySet.propertyName format.
SetProperty method is very similar to SetTerm, but as it requires both a
property set and property name, it can only be used to add custom properties.
Return value
rvS_OK Success.
Search API 551
Example
It is assumed that a custom property "Type", belonging to the property set
"Instrument", has been added to archived items.
Two queries are constructed in this sample; the first searches for all queries
with the custom property Instrument.Type = 'Guitar. The second searches for
all items where the retention category = 'Business'.
The two queries are combined to form one query that searches for all items
where Instrument.Type is 'Guitar' and retention category is not 'Business'.
C#
//search for items with custom property value `Guitar'

string qry1 = query.SetProperty("Instrument", "Type", "Guitar", (int)
ESearchQueryFlags.ESQexact);
//search for items with a retention category of "Business"
string qry2 = query.SetTerm("rcat", "Business", (int)(ESearchQueryFlags.ESQexact);
//combine the 2 queries so that the result set contains items that contain `Guitar' in
the custom property Instrument.Type and that have a retention category that is not
`Business'
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);
See also
■ “ISearchQuery :: SetTerm” on page 542.
■ “ISearchQuery :: AddProperty” on page 552.
552 Search API
ISearchQuery :: AddProperty
This method adds a custom property to the query being built in the object and
which can be used for searching.
Syntax
HRESULT AddProperty([in, string] const BSTR bsPropSet,
[in] VARIANT vVal,
Parameters
[in, string] const BSTR bsPropSet Name of the property set.
[in, string] const BSTR bsProp The name of the custom property to
search for.
[in] VARIANT vVal VARIANT containing value for which for

which to search. This can be a string, date
or integer.
query.
on page 533.
[out, retval] BSTR* pbsQuery Pointer to a string containing the query

as it stands after this method returns.
Remarks
This method is very similar to AddTerm, but with both a property set and
property name being included as parameters. This means that it can only be
used to add custom properties.
Return value
rvS_OK Success.
Search API 553
Example
In this example we use the return value which holds the current query. It is also
assumed that a custom property "Type", belonging to the property set
"Instrument", has been added to archived items as well as a custom property
"Colour", belonging to the same property set.
The example builds two queries; the first searches for all items where
Instrument.Colour is 'Red'. The second searches for items where
Instrument.Type is 'Guitar'. The two queries are combined to form one, in order
to search for all items where Instrument.Type is 'Guitar' and 'Instrument.Colur
is 'Red'.
C#
//search for items where custom property Instrument.Colour = "Red"
string qry1 = query.SetProperty("Instrument", "Colour", "red",
(int)ESearchQueryFlags.ESQexact);
//search for items with custom property Instrument.Type = `Guitar'
string qry2 = query.AddProperty("Instrument", "Type", "Guitar", (int)(
the custom property Instrument.Type and "red" in Instrument.Colour"
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQand);
See also
■ “ISearchQuery :: AddTerm” on page 544.
■ “ISearchQuery :: SetProperty” on page 550.
554 Search API
ISearchQuery :: AddOp
This method is used to add an operator to the query in order to combine
previously defined terms.
Syntax
HRESULT AddOp([in] const long lOp,
[in, defaultvalue(0)] const long lScope,
Parameters
[in] const long lOp The operator to use.

See “ESearchQueryOperators
[in, defaultvalue(0)] const long lScope How the operator is to be applied.

See “ESearchOperatorScope
[out, retval] BSTR* pbsQuery Pointer to string that will contain the
value of the query after this operator
has been added.
Remarks
This method combines the previous x properties by using the operator defined
in the first parameter, where x is the value given in the second parameter.
An example of an operator is 'AND' or 'OR'.
This method does not check the validity of the value passed to the first
parameter, so an error will only be reported when Search is called.
This method can be called successively in order to build up the query.
Return value
rvS_OK Success.
Search API 555
Example
In this example a query is constructed that will search for all items with a
subject that contains the phrase 'some subject', and one attachment. In this
C#
//now we AND the 2 terms so that both terms must be satisfied before returning a result
556 Search API
ISearchQuery :: Combine
This method clears the current query in the object and then adds queries from
two other query objects. These are combined using the specified operator.
Syntax
HRESULT Combine([in, string] const BSTR bsQuery1,
[in, string] const BSTR bsQuery2,
[in] const long lOp,
Parameters
[in, string] const BSTR bsQuery1 First query to add.
[in, string] const BSTR bsQuery2 Second query to add.

See “ESearchQueryOperators enumeration”
on page 534.
[out, retval] BSTR* pbsQuery Pointer to a string that contains the query that
results from this method.
Remarks
This method combines two search queries. Each of the search queries is the
Query property of another SearchQuery object.
No check is made to ensure that the two strings are correctly-formed query
strings. Similarly, the lOp parameter is not checked to make sure that it is a
valid operator.
If any of these parameters are incorrect, an error is not reported until the query
string is parsed.
Return value
rvS_OK Success.
Search API 557
Example
In this example we create two queries; the first searches for all items where the
custom property Instrument.Type is 'Guitar', and the second searches for all
items with a retention category of 'Business'. The return values hold the
resultant queries. These are then combined to produce one query to search for
all items where Instrument.Type is 'Guitar' and retention category is not
'Business'.
C#
//search for items with custom property value `Guitar'

string qry1 = query.SetProperty("Instrument", "Type", "Guitar", (int)(
//search for items with a retention category of "Business"
string qry2 = query.SetTerm("rcat", "Business", (int)(ESearchQueryFlags.ESQexact);
the custom property Instrument.Type and that have a retention category that is not
`Business'
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);
558 Search API
ISearchQuery :: AddQuery
This method is used to combine a query from another query object with the
query in the current object, using the specified operator.
Syntax
HRESULT AddQuery([in, string] const BSTR bsQuery1,
[in] const long lOp,
Parameters
[in, string] const BSTR bsQuery1 String containing the query to combine with the
one in the current object.

See “ESearchQueryOperators enumeration” on
page 534.
[out, retval] BSTR* pbsQuery Pointer to a string that will contain the resulting
query string.
Remarks
Combines a search query, which is assumed to be the Query property of another
SearchQuery object, with the query string of this object.
No check is made to ensure that the new string is correctly formed. Similarly,
the lOp parameter is not checked to ensure that it is a valid operator.
If any of these parameters are incorrect, an error is not reported until the query
string is parsed.
Return value
rvS_OK Success.
Example
In this example it is assumed there is already a populated ISearchQuery object,
query2.
This example adds a new query string to this existing query.
Search API 559
C#
string qry = query.SetTerm("cont", "-white blue.red",
(int)ESearchQueryFlags.ESQany);
query2.AddQuery(qry, (int)ESearchQueryOperators.ESQand);
560 Search API
ISearchQuery2 :: SetPropertyRange
This method is used to add a date or integer range to a query that specifies a
custom index property. The method deletes any queries in the current object,
resets it, and adds the specified information as part of a new query.
Custom index properties can be added to index entries using the
SimpleIndexMetadata API.
“SimpleIndexMetadata object” on page 277.
Syntax
HRESULT SetPropertyRange([in, string] const BSTR bsPropSet,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
Parameters
[in, string] const BSTR bsPropSet String containing the name of the
property set.
[in, string] const BSTR bsProp String that contains the property name.
[in] VARIANT vVal1 VARIANT specifying the first value in the

range.
[in] VARIANT vVal2 VARIANT specifying the second value in

the range.
query.
on page 533.
[out, retval] BSTR* pbsQuery Pointer to a string that will contain the
query string formed by this method.
Remarks
This method can only be used with date or integer values.
SimpleIndexMetadata API. bsPropSet specifies the property set.
Search API 561

Note that SetRange can also be used with custom properties, using the
Return value
rvS_OK Success.
Example
In this example it is assumed there is a custom property set, `CustomTags',
containing a property ‘Relevance', which is on a scale 0 - 9.
C#
//return all items that have the custom property CustomTags.Relevance between 0 and 5
query.SetPropertyRange("CustomTags", "Relevance", 0, 5,
See also
■ “Adding custom index metadata” on page 55
■ “ISearchQuery :: SetRange” on page 546
■ “ISearchQuery :: AddRange” on page 548
■ “ISearchQuery2 :: AddPropertyRange” on page 562
562 Search API
ISearchQuery2 :: AddPropertyRange
This method is used to add a date or integer range to a query that specifies a
custom index property.
Custom index properties can be added to index entries using the
SimpleIndexMetadata API.
“SimpleIndexMetadata object” on page 277.
Syntax
HRESULT AddPropertyRange([in, string] const BSTR bsPropSet,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
Parameters
[in, string] const BSTR bsPropSet String containing the name of the
property set.
[in, string] const BSTR bsProp String containing the property name.
[in] VARIANT vVal1 VARIANT specifying the first value in

the range.
[in] VARIANT vVal2 VARIANT specifying the second value

in the range.
query.
on page 533.
[out, retval] BSTR* pbsQuery Pointer to a string that will contain the
query string formed by this method.
Remarks
This method can only be used with date or integer values.
SimpleIndexMetadata API. bsPropSet specifies the property set.
Search API 563

Note that AddRange can also be used with custom properties, using the
Return value
rvS_OK Success.
Example
In this example it is assumed there is a custom property set, ‘CustomTags',
containing a property ‘Relevance', which is on a scale 0 -9.
C#
//return all items that have the custom property CustomTags.Relevance between 0 and 5
query.AddPropertyRange("CustomTags", "Relevance", 0, 5,
See also
■ “Adding custom index metadata” on page 55
■ “ISearchQuery :: SetRange” on page 546
■ “ISearchQuery :: AddRange” on page 548
■ “ISearchQuery2 :: SetPropertyRange” on page 560
564 Search API
IndexSearch object
IndexSearch object
IndexSearch object implements the following interface:
■ IIndexSearch2
IIndexSearch2 provides properties and methods that can be used to enable the
user to search an archive using a query that has been built using the methods of
ISearchQuery2.
The output from a search is a pointer to an ISearchResults2 interface, the
implementation of which contains a collection of ISearchResult2 pointers.
Syntax
interface IIndexSearch2 : IDispatch
Member summary
IndexVolumeSets Read only Returns a collection of Index

Volume Sets used by the currently
selected archive.
Options Read/Write Sets or retrieves the current

search options.
SortBy Read/Write Gets or sets the current

properties used to order the
returned search results. (None or
one index property).
ResultsPropertySet Read/Write Gets or sets a predefined list of

properties whose values are to be
returned as part of the result set.
See “EPropertySets enumeration”
on page 535.
See “Remarks” on page 566.
AdditionalResultsProperties Read/Write A space separated list of

properties returned in the search
results in addition to those in the
selected results property set.
Search API 565
IndexSearch object
Timeout Read/Write Gets or sets the timeout period, in

seconds, applied to federated
search requests (that is, searches
across multiple index volume
sets).
ArchiveEntryId Read only Gets the Id of the currently

selected archive.
ArchiveName Read only Gets the name of the currently

selected archive.
HasFolders Read only Returns true if the currently

selected archive contains folders.
IndexVolumeSetIdentity Read only Gets the identity of the currently

selected index volume set.
IndexVolumeIdentity Read only The identity of the currently

selected index volume.
IndexVolumeSetCount Read only Gets the number of index volume

sets for the currently selected
archive.
MaxSearchIndexVolumeSets Read/Write For federated searches, gets or

sets the current maximum
number of volume sets to search.
The default value is 5. If number
of volumes is above this, the
search application must select the
specific VolumeSet to search (see
SelectIndexVolumeSet).
MaxSearchResultsPerVolumeSet Read/Write For federated searches only, gets

or sets the current value of the
maximum number of results to be
returned per volume set. Default
is 1000.
Method Description
SelectArchive Sets the Id of the archive to be searched.

566 Search API
IndexSearch object
Method Description
ListIndexVolumeSets Returns as an XML document the index volume

set collection for the selected archive.
SelectIndexVolumeSet Set the Id of the archive's index volume set to

search. If an index volume set is not selected, and
the number of index volume sets is less than, or
equal to, MaxSearchIndexVolumeSets, then a
federated search is automatically performed
across the index volume sets. If the number of
index volume sets is greater than
MaxSearchIndexVolumeSets, then the index
volume set to search must be selected.
SelectIndexVolume This property should not be used.

As Enterprise Vault only supports one volume per
volume set, use SelectIndexVolumeSet to select a
specific index volume to search.
Search Search the selected archive index or selected

IndexVolumeSet.
SearchToXML Search the selected archive index or selected

IndexVolumeSet, and return the results as XML.
AddAdditionalResultsProperty Adds a single property to the

AdditionalResultsProperties list.
This should be used in preference to
ResultsPropertySet.
AddAdditionalResultsCustomProperty Adds a single custom property to the

Reset Reset the object properties to their default values.
Remarks
As they are ultimately derived from IDispatch, these interfaces can be used by
scripting languages. IIndexSearch2 supersedes IIndexSearch interface, which
does not support multiple volume sets.
Although the property ResultsPropertySet can still be used, it is recommended
that only the actual properties required are added through the use of the
property AdditionalResultsProperties.
Search API 567
IndexSearch object
IIndexSearch2 provides a method that returns a collection of index volume sets.

This collection is accessed by methods and properties of the returned
IIndexVolumeSet pointer.
If the number index volume sets is greater than the number set by
MaxSearchIndexVolumeSets (5 is the default), then it is necessary to specify the
archive Id and also the index volume sets to search, otherwise an error is
returned, rvINDEXING_E_TOO_MANY_VOLUMES.
Currently, the index volume set is limited to one index volume. However, in a
future release, index volume sets may contain more than one index volume. To
prevent any confusion, all new applications should use methods and properties
that specify index volume sets, as errors could occur if those that refer to index
volumes (such as, IIndexSearch2 :: IndexVolumeIdentity) are used.
Example
The object, 'search', constructed in this example will be used in the most of the
subsequent examples. It is shown here as a private class data member.
C#
public class SampleSearchClass
{
private IIndexSearch2 search = (IIndexSearch2)
new IndexSearch2();
//rest of the class
See also
■ “IndexVolumeSets object” on page 605
■ “IndexVolumeSet object” on page 615
568 Search API
IIndexSearch2 :: IndexVolumeSets
This property returns a pointer to an IndexVolumeSets collection object. The
collection can be accessed using the properties and methods of the returned
interface pointer. The property is read only.
Syntax
HRESULT IndexVolumeSets([out,retval] IUnknown**
volumeSetsCollection);
Parameters
[out,retval] IUnknown** volumeSetsCollection Pointer to an IUnknown pointer

that can be QI'd (or cast) to
obtain an IIndexVolumeSets
pointer.
Remarks
This property must not be used before SelectArchive has been called.
The returned data should not be persisted, as the collection of index volume sets
associated with an archive may change over time. Also when indexes are rebuilt
the set of index volumes will change.
See “IndexVolumeSets object” on page 605 for details of index volume sets.
Return value
rvS_OK Success.
rvE_POINTER An invalid pointer has been received.
rvINDEXING_W_ARCHIVE_NOT_SET The archive to search has not been set.
Example
C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
{
Search API 569
DoSearch(search);
}
570 Search API
IIndexSearch2 :: Options
This property sets or returns search option flags that define the granularity of
search results.
Syntax
HRESULT Options([in] long options,
[out,retval] long* options);
Parameters
[in] long options EOptionsFlags value defining required granularity of

search results.
“EOptionsFlags enumeration” on page 535.
[out,retval] long* options Pointer to a long integer that will contain the current
value.
Remarks
Both messages and their attachments are searched, but the granularity of
search results (Option) defines whether attachments are returned in search
results or only the top-level items.
See “EOptionsFlags enumeration” on page 535.
Return value
rvS_OK Success.
rvE_POINTER An invalid pointer has been received.
Example
C#
[in]
search.Options = (int)EOptionsFlags.roItemGranularity;
[out]
EOptionsFlags eof = (EOptionsFlags )search.Options;
Search API 571
if (eof == EOptionsFlags.roAttachmentGranularity)
{
//do something
}
else //do something else
572 Search API
IIndexSearch2 :: SortBy
IIndexSearch2 :: SortBy
This property is used to order the returned search results.
Syntax
HRESULT SortBy([in] BSTR sortProperties,
[out,retval] BSTR* sortProperties);
Parameters
[in] BSTR sortProperties String containing the properties by which

to sort search results.
[out,retval] BSTR* sortProperties Pointer to a string that will contain the

current properties used for sorting.
Remarks
sortProperties can be none or one index property.
The sort order is normally ascending, but you can reverse the order by preceding
the property with a minus sign (-), for example:
search.SortBy = "-" + "adat";
Return value
rvS_OK Success.
rvE_POINTER The pointer passed in to receive the current value is invalid.
Example
This example shows how to sort by archived date, in descending order.
C#
[in]
//sort by archived date descending
search.SortBy = "-" + "adat";
[out]
string sortBy = search.SortBy;
Search API 573
IIndexSearch2 :: ResultsPropertySet
This property can be used to specify a predefined set of properties returned in
search results.
See “Remarks” for important comments on using this property.
Syntax
HRESULT ResultsPropertySet([in] long propertySet,
[out,retval] long* propertySet);
Parameters
[in] long propertySet Long integer containing the EPropertySets

value to be set.
See “EPropertySets enumeration” on page 535.
[out,retval] long* propertySet Pointer to a long integer that will receive the
current value.
Remarks
“EPropertySets enumeration” on page 535 lists the values for the predefined
property sets.
As the predefined property sets may change in future releases, we strongly
recommend that you set this property to psEmpty, and use the
AdditionalResultsProperties property and/or AddAdditionalResultsProperty
and AddAdditionalResultsCustomProperty to set the required properties to be
found in the result set.
Return value
rvS_OK Success.
rvE_POINTER The long pointer passed in to receive the current value is

invalid.
rvE_INVALIDARG The value being set is less than 0.

574 Search API
Example
As this property is no longer the recommended way of setting the returned
properties, it is set to ‘empty'.
C#
[in]
search.ResultPropertySet = (int)EPropertySets.psEmpty;
[out]
if (search.ResultPropertySet != 0)
{
search.ResultPropertySet = 0; // (psEmpty)
}
See also
■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575
■ “IIndexSearch2 :: AddAdditionalResultsProperty” on page 601
■ “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 602.
Search API 575
IIndexSearch2 :: AdditionalResultsProperties
This property is the recommended way to define the properties returned in
search results.
Syntax
HRESULT AdditionalResultsProperties([in] BSTR propertiesList);
HRESULT AdditionalResultsProperties([out,retval] BSTR*
propertiesList);
Parameters
[in] BSTR propertiesList String containing a space separated list of

properties to be returned in the search
results.
[out,retval] BSTR* propertiesList Pointer to a string that will receive a list of

the current properties.
Remarks
The properties added must be in the format of a space delimited list.
Properties you define using this property should be in addition to those found in
the predefined property sets. It is recommended that the empty
ResultPropertySet is selected.
Return value
rvS_OK Success.
rvE_POINTER The string pointer passed in to receive the current value is

invalid.
Example
Note that as IIndexSearch2::ResultPropertySet is no longer a preferred method,
it is set 'empty' as a precaution.
576 Search API
C#
[in]
search.ResultPropertySet = (int)EPropertySets.psEmpty; //set empty
search.AdditionalResultsProperties = "ssid adat natc";
[out]
string props = search.AdditionalResultsProperties;
if (props.Contains("ssid"))
{
//do something
See also
■ “IIndexSearch2 :: AddAdditionalResultsProperty” on page 601
■ “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 602
■ “IIndexSearch2 :: ResultsPropertySet” on page 573
Search API 577
IIndexSearch2 :: Timeout
IIndexSearch2 :: Timeout
This property defines the timeout period applied to federated search requests.
Syntax
HRESULT Timeout([in] long seconds,
[out,retval] long* seconds);
Parameters
[in] long seconds Long integer containing number of seconds to wait before
the search times out. The default value is 60 seconds.
[out,retval] long* seconds Pointer to a long integer that will receive the current
value.
Remarks
Defines the period in seconds before a search request times out - the default
value is 60 seconds.
This property applies to federated searches only.
Return value
rvS_OK Success.
rvE_POINTER The new value being set is equal to or less than zero.
rvE_INVALIDARG The long integer pointer passed in to receive the current

value is incorrect.
Example
C#
[in][out]
if (search.Timeout < 60)
{
search.Timeout = 60;
}
578 Search API
IIndexSearch2 :: ArchiveEntryId
IIndexSearch2 :: ArchiveEntryId
This property returns the ID of the archive that is currently selected for
searching.
Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value)
Parameters
[out,retval] BSTR* value Pointer to a string that will receive the current value.
Remarks
This method will only return a valid Id after SelectArchive has been called.
Return value
rvS_OK Success.
rvE_POINTER The BSTR pointer passed in to receive the current value is

invalid.
rvS_FALSE The archive has not been selected yet.
Example
C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
//do something
string aeid = search.ArchiveEntryId;
Search API 579
IIndexSearch2 :: ArchiveName
IIndexSearch2 :: ArchiveName
This property returns the name of the archive that is currently selected for
searching.
Syntax
HRESULT ArchiveName([out,retval] BSTR* value);
Parameters
[out,retval] BSTR* value Pointer to a string that will contain the current
value.
Remarks
This method will only return a valid archive name after SelectArchive has been
called.
If the archive has not been selected, then the return value will be S_FALSE.
If tested in one of the C++ SUCCEEDED or FAILED macros, this will register as
true. It is therefore advisable to test that the value acquired is as expected.
Return value
rvS_OK Success.
rvE_POINTER The BSTR pointer passed in to receive the current value is

invalid.
rvS_FALSE The archive has not been selected.
Example
C#
e1");
//display the archive name in a textbox.
textBoxArchId.Text = search.ArchiveName;
580 Search API
IIndexSearch2 :: HasFolders
IIndexSearch2 :: HasFolders
This property indicates whether the currently selected archive contains a folder
structure.
Syntax
HRESULT HasFolders([out,retval] VARIANT_BOOL* value);
Parameters
[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive

the current value.
Remarks
This method will only return a valid result after SelectArchive has been called.
Return value
rvS_OK Success.
rvE_POINTER Value is an invalid pointer.
rvS_FALSE The archive has not been selected.
Example
C#
e1");
//do something
if (search.HasFolders == true)
{
//do something
Search API 581
IIndexSearch2 :: IndexVolumeSetIdentity
IIndexSearch2 :: IndexVolumeSetIdentity
This property identifies the volume set of the index volume to search.
Syntax
HRESULT IndexVolumeSetIdentity([out,retval] long* value);
Parameters
[out,retval] long* value Pointer to a long that will receive the current value.
Remarks
This property will return a valid Id after SelectArchive has been called.
It returns -1 and S_FALSE if SelectArchive has not been called, or the selected
archive has multiple index volume sets and SelectIndexVolumeSet has not been
called.
Return value
rvS_OK Success.
rvE_POINTER The long integer pointer passed in to receive the current

value is invalid.
rvS_FALSE Either SelectArchive has not been called, or there is an

invalid value for the Index Volume.
Example
C#
e1");
//do something
long id = search.IndexVolumeSetIdentity;
if (id == -1)
MessageBox.Show("This archive has multiple Index Volume Sets -
please select one", "Multiple Index Volume Sets", MB_OK);
582 Search API
IIndexSearch2 :: IndexVolumeIdentity
IIndexSearch2 :: IndexVolumeIdentity
This property should not be used: it is currently available for Enterprise Vault
internal purposes only.
Syntax
HRESULT IndexVolumeIdentity([out,retval] long* value);
Parameters
[out,retval] long* value Pointer to a long integer that will hold the current value.
Remarks
This property should not be used.
This property returns the IndexVolumeIdentity as selected by the search
application.
Return value
rvS_OK Success. The IndexVolumeIdentity is valid (that is, not 0 or

-1) and a valid archive has been selected.
rvS_FALSE The archive Id has not been selected, or the internal index
volume identity has not been populated (for example, in a
federated search).

Search API 583
IIndexSearch2 :: IndexVolumeSetCount
IIndexSearch2 :: IndexVolumeSetCount
This property returns the number of index volume sets in the archive’s index.
Syntax
HRESULT IndexVolumeSetCount([out,retval] long* value);
Parameters
[out,retval] long* value Pointer to a long integer that will receive the current value.
Remarks
This property should not be used before SelectArchive has been called.
Return value
rvS_OK Success.
rvS_FALSE SelectArchive has not been called.
rvE_POINTER The long integer pointer passed in to receive the current

value is invalid.
Example
C#
long count = search.IndexVolumeSetCount;
//want to do a federated search depending on number of Index Volume sets
if (count <= 10)
{
//do federated search
search.MaxSearchIndexVolumeSets = count;
//carry on with search
}
else
{
}
584 Search API
IIndexSearch2 :: MaxSearchIndexVolumeSets
This property specifies the maximum number of index volume sets that can be
searched by a federated search (that is, a search across multiple index volume
sets).
Syntax
HRESULT MaxSearchIndexVolumeSets([out, retval] LONG* pVal,
[in] LONG newVal);
Parameters
[out, retval] LONG* pVal Pointer to a long integer that will receive the
maximum number of index volume sets that
can be searched. The default is 5.
[in] LONG newVal Long integer containing the new value to set.
Remarks
Default value is 5. A search that spans multiple index volume sets is called a
federated search.
The default value has been selected to provide a reasonable performance and
response times for federated searches. Increasing this value will extend
response times and also consume additional memory and CPU resource in the
client application when correlating the search results from the additional index
volume sets’ searches.
Return value
rvS_OK
rvE_INVALIDARG The new value being set is less than 1.

invalid.
Search API 585
Example
C#
if (count <= 10)
{
}
else
{
586 Search API
IIndexSearch2 :: MaxSearchResultsPerVolumeSet
This property indicates the maximum number of search results that can be
returned per volume set by a federated search (that is, a search across multiple
index volume sets).
Syntax
HRESULT MaxSearchResultsPerVolumeSet([out, retval] LONG* pVal,
[in] LONG newVal);
Parameters
[out, retval] LONG* pVal Pointer to a long integer that will receive the current
value.
[in] LONG newVal Long integer that sets the new value required.
Remarks
In a federated search, results returned from each volume set are processed and
merged. This property indicates the maximum number of search results per
volume set that can be processed and merged. The default is 1000 search results
per volume set.
The default value has been selected to provide a reasonable performance and
response times for federated searches. Increasing this value will extend
response times and will also consume additional memory and CPU resource in
the client application in order to correlate the increased number of search
results.
Return value
rvS_OK
rvE_INVALIDARG The new value being set is less than 1.

invalid.
Search API 587
Example
C#
if (count <= 10)
{
search.MaxsearchResultsPerVolumeSet = 500;
}
else
{
588 Search API
IIndexSearch2 :: SelectArchive
This method is used to select an archive to search.
Syntax
HRESULT SelectArchive([in]BSTR archiveEID);
Parameters
[in]BSTR archiveEID String containing the Id of the archive to search.
Remarks
The SelectArchive method specifies the archive to search in subsequent calls to
Search or SearchToXML. The archive must be selected before attempting to list
index volume sets associated with the index, or search the index.
See “Performing a search” on page 524 for ways of finding out the ID of an
archive.
Return value
rvS_OK Success.
rvE_INVALIDARG Either a zero length string has been passed or

the archive entry specified could not be found.
rvINDEXING_W_CANT_ACCESS_DIRECTORY
rvINDEXING_E_ARCHIVE_NOT_FOUND
rvINDEXING_W_INDEXDISABLED Indexing has been disabled for this archive;

the archive status is
INDEX_ITEMS_DEFERRED_INDEFINITELY.
Example
C#
Assume there is a populated IArchives object, 'archives'.
{
search.SelectArchive(archive.Id);
Search API 589
}
See also
■ “IIndexSearch2 :: Search” on page 595
■ “IIndexSearch2 :: SearchToXML” on page 598
590 Search API
IIndexSearch2 :: ListIndexVolumeSets
This method is used to list the index volume set collection for the selected
archive as an XML document.
Syntax
HRESULT ListIndexVolumeSets([in] BSTR processingInstruction,
[out,retval] BSTR* volumeSetsList);
Parameters
[in] BSTR processingInstruction String containing an optional parameter that

enables the caller to specify an XML processing
instruction. This is added to the XML following
the XML declaration. For example, an XSL style
sheet reference can be specified with the
following string:
xml-stylesheet
href="indexvolumesets.xsl"
type="text/xsl"
(XML processing instruction delimiters are
added by the method).
[out,retval] BSTR* volumeSetsList Pointer to a string that will receive the XML
document.
Remarks
An archive must have been selected using SelectArchive.
This method is an alternative to using the IndexVolumeSets property.
IndexVolumeSets returns a pointer to an enumerated collection of
IIndexVolumeSet interface pointers, which can be accessed using the properties
and methods of the returned interface pointer.
Return value
rvS_OK Success.
rvE_POINTER The parameter volumeSetList is a NULL pointer.
rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.

Search API 591
Example
C#
e1");
string volSetsXML = search.ListIndexVolumeSets("xml-stylesheet
href='indexvolumesets.xsl' type='text/xsl'");
//do something with the XML
The following gives an example of the XML returned by the
ListIndexVolumeSets method.
For the last index volume set, all elements except FirstItemSequenceNumber are
optional, since it may represent a new index volume that has not yet been
committed to disk.
<?xml version="1.0" encoding="utf-16" ?>
<IndexVolumeSets xmlns="urn:kvsinc-com:EnterpriseVault"
ArchiveEntryId="12234E1CE26421C45A096DD3CA06527071110000evsvr"
ArchiveName="John Smith"
HasFolders="True">
<IndexVolumeSet Identity="20">
<FirstItemSequenceNumber>1</FirstItemSequenceNumber>
<OldestArchivedDate>2002-03-13T12:50:38Z</OldestArchivedDate>
<YoungestArchivedDate>2004-04-18T06:49:44Z</YoungestArchivedDate>
<OldestItemDate>1998-03-26T05:34:02Z</OldestItemDate>
<YoungestItemDate>2004-03-02T22:22:23Z</YoungestItemDate>
</IndexVolumeSet>
<IndexVolumeSet Identity="29">
<FirstItemSequenceNumber>16666344</FirstItemSequenceNumber>
<OldestArchivedDate>2004-04-18T06:49:50Z</OldestArchivedDate>
<YoungestArchivedDate>2004-04-25T07:02:44Z</YoungestArchivedDate>
<OldestItemDate>2004-03-12T20:12:03Z</OldestItemDate>
<YoungestItemDate>2004-03-13T22:06:16Z</YoungestItemDate>
</IndexVolumeSet>
</IndexVolumeSets>
See also
■ “IIndexSearch2 :: IndexVolumeSets” on page 568
592 Search API
IIndexSearch2 :: SelectIndexVolumeSet
This method selects an index volume set when searching an index with multiple
index volume sets.
Syntax
HRESULT SelectIndexVolumeSet([in] long volumeSetIdentity);
Parameters
[in] long volumeSetIdentity Long integer containing the Id of the index volume set.
Remarks
An archive must have been selected using SelectArchive.
For an index with a single index volume set, that index volume set is selected by
default.
Unless this property is set to specify an index volume set to search, then a feder-
ated search will be carried out across all index volume sets in the archive. How-
ever, if the number of index volume sets exceeds the number set by
MaxSearchIndexVolumeSets (default is 5), this property must be set to deter-
mine which index volume set to search, otherwise the Search API will return an
error, rvINDEXING_E_TOO_MANY_VOLUMES.
Index volume set Ids can be obtained using the ListIndexVolumeSets method.
Return value
rvS_OK Success.
rvE_INVALIDARG
rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.
rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET The volume set specified does not

exist.
rvINDEXING_W_UNABLE_FAILED_VOLUME A volume in the set is known to have

failed - no reason specified.
Search API 593
rvINDEXING_E_UNABLE_OFFLINE_VOLUME A volume in the set is known to be

offline.
Example
C#
//set up the search
ISearchResults2 results = null;
if (search.IndexVolumeSetCount > search.MaxSearchIndexVolumeSets)
{
{
//do the search etc.
results = (ISearchResults2)search.Search(query.Query, 1, 100, "");
}
}
else results = (ISearchResults2)search.Search(query.Query, 1, 100, "");
594 Search API
IIndexSearch2 :: SelectIndexVolume
IIndexSearch2 :: SelectIndexVolume
This method is used to select a specific index volume of the archive to search.
Syntax
HRESULT SelectIndexVolume([in] long volumeIdentity);
Parameters
[in] long volumeIdentity
Remarks
This method should not be used. An Index Volume Set is considered the smallest
element of an archive's index. The ability to select individual index volumes may
be removed in a future release.
Return value
rvS_OK Success.
rvE_INVALIDARG An unexpected error has occurred.
rvINDEXING_W_UNKNOWN_INDEX_VOLUME
rvINDEXING_W_ARCHIVE_NOT_SET
rvINDEXING_W_UNABLE_FAILED_VOLUME
rvINDEXING_E_UNABLE_OFFLINE_VOLUME
Search API 595
IIndexSearch2 :: Search
This method submits the search request and returns a search results object.
See “SearchResults object” on page 627.
Syntax
HRESULT Search([in] BSTR bsQuery,
[in] long startResult,
[in] long maximumResults,
[in] BSTR reserved,
[out, retval] IUnknown** resultsSet);
Parameters
[in] BSTR bsQuery String containing the query. This is

normally the Query property of a
SearchQuery object.
[in] long startResult Long integer containing the number of the

first result. This can be 1 up to the total
number of possible results.
[in] long maximumResults Long integer containing the maximum

number of results to return.
[in] BSTR reserved This parameter must be "".
[out, retval] IUnknown** resultsSet Pointer to an IUnknown pointer. On return,

the resulting IUnknown pointer can be QI'd
(or cast) to obtain the required
ISearchResults2 pointer.
Remarks
An empty query causes a full wildcard search, which matches all entries in the
index. As maximum results will probably be exceeded, it is unlikely to return all
the items in the index.
To ensure a well formed query is passed to this method, obtain an
ISearchQuery2 interface pointer and construct a query using the properties and
methods of this interface.
See “SearchQuery object” on page 537.
Each search starts a new search in the Indexing server.
The startResult and maximumResults arguments enable paging through search
results.
596 Search API
Results are numbered, in order, after sorting. Search results are ordered as
follows:
■ Using the index property specified with the SortBy property, if any.
■ Otherwise, for those terms where the ESQRank flag was specified in the
search term, by relevance to the words used in the search query.
■ Otherwise, in order of addition to the index.
See “Performing a search” on page 524 for more information and
recommendations for performing searches.
Return value
rvS_OK Success.
rvE_POINTER The pointer to the IUnknown pointer

passed is the fourth parameter is
invalid.
rvE_ACCESSDENIED
rvE_NOINTERFACE
rvE_SERVER_UNAVAILABLE
rvINDEXING_SERVER_STOPPING
rvINDEXING_E_SERVICE_STOPPING
rvINDEXING_E_ARCHIVE_NOT_SET
INDEXING_W_CANT_ACCESS_DIRECTORY
rvINDEXING_W_ARCHIVE_BEING_DELETED
rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET
rvINDEXING_W_UNKNOWN_INDEX_VOLUME The selected index volume is not

known.
rvINDEXING_W_SEARCH_WOULD_BLOCK
rvINDEXING_W_SEARCH_TIMEDOUT
Search API 597
rvINDEXING_E_TOO_MANY_RESULTS
rvINDEXING_E_TOO_MANY_VOLUMES
rvINDEXING_E_INVALID_QUERY
rvINDEXING_E_ILLEGAL_WILDCARD_QUERY
rvINDEXING_E_FAILED_SEARCH_REQUEST
rvINDEXING_E_INDEX_SEARCH_FAILED
Example
In this example it is assumed that an ISearchQuery2 object, ‘query', has been
created and populated.
C#
//select the archive and set up the search query etc
//return a results set that starts from the first item found up to a
total of 100 items.
ISearchResults2 results = (ISearchResults2)search(query.Query, 1,
100, "");
Note the fourth parameter must be "".
See also
■ “SearchQuery object” on page 537
■ “ESearchQueryFlags enumeration” on page 533
598 Search API
IIndexSearch2 :: SearchToXML
This method is used to search the selected index volume set or index volume and
return the results as XML. This method is similar to Search, but it returns XML
not an interface pointer.
Syntax
HRESULT SearchToXML([in] BSTR bsQuery,
[in] long startResult,
[in] long maximumResults,
[in] BSTR reserved,
[in] BSTR processingInstruction,
[in] long xmlFormatOptions,
[out,retval] VARIANT* xmlResults);
Parameters
[in] BSTR bsQuery String containing the query, this is normally the
Query property of a SearchQuery object.
[in] long startResult Long integer containing the number of the first
result. This can be 1 up to the total number of
possible results.
[in] long maximumResults Long integer containing the maximum number of

results to return.
[in] BSTR reserved This parameter must be "".
[in] BSTR processingInstruction String containing an XML processing instruction

which will be inserted into the returned XML. For
example, xml-stylesheet type="test/xsl"
href="results.xsl"
[in] long xmlFormatOptions Long integer containing a flag from the

EXMLResultsFormatOptions. Currently the only
available value is 0.
[out,retval] VARIANT* xmlResults Pointer to a VARIANT containing the search

results.
Remarks
EXMLResultsFormatOptions enumerates the XML format option values.
Currently there is only the following default value:
xoNone = 0x00000000
Search API 599
An empty query causes a full wildcard search, which matches all entries in the
index. As maximum results will probably be exceeded, it is unlikely to return all
the items in the index.
To ensure a well formed query is passed to this method, obtain an
ISearchQuery2 interface pointer and construct a query using the properties and
methods of this interface.
See “SearchQuery object” on page 537.
Each search starts a new search in the Indexing server.
The startResults and maximumResults arguments enable paging through
search results.
Results are numbered, in order, after sorting. Search results are ordered as
follows:
■ Using the index property specified with the SortBy property, if any.
■ Otherwise, for those terms where the ESQRank flag was specified in the
search term, by relevance to the words used in the search query.
■ Otherwise, in order of addition to the index.
See “Performing a search” on page 524 for more information and
recommendations for performing searches.
Return value
rvS_OK Success.
rvE_POINTER The pointer to the IUnknown pointer passed is the fifth

parameter is invalid.
rvE_ACCESSDENIED
rvE_NOINTERFACE
rvE_SERVER_UNAVAILABLE
rvINDEXING_SERVER_STOPPING
rvINDEXING_E_SERVICE_STOPPING
rvINDEXING_E_ARCHIVE_NOT_SET
INDEXING_W_CANT_ACCESS_DIRECTORY
rvINDEXING_W_ARCHIVE_BEING_DELETED
600 Search API
rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET
rvINDEXING_W_UNKNOWN_INDEX_VOLUME
rvINDEXING_W_SEARCH_WOULD_BLOCK
rvINDEXING_W_SEARCH_TIMEDOUT
rvINDEXING_E_TOO_MANY_RESULTS
rvINDEXING_E_TOO_MANY_VOLUMES
rvINDEXING_E_INVALID_QUERY
rvINDEXING_E_ILLEGAL_WILDCARD_QUERY
rvINDEXING_E_FAILED_SEARCH_REQUEST
rvINDEXING_E_INDEX_SEARCH_FAILED
Example
In this example it is assumed that an ISearchQuery2 object, ’query', has been
created and populated.
C#
//select the archive and set up the search query etc
byte[] res = (byte[])search.SearchToXML(query.Query, 1, 100, "",
"", 0);
Search API 601
IIndexSearch2 :: AddAdditionalResultsProperty
IIndexSearch2 :: AddAdditionalResultsProperty
This method is used to add a single property to the AdditionalResultsProperties
list. Using the AdditionalResultsProperty list is now the preferred way of
specifying properties required in the results set.
Syntax
HRESULT AddAdditionalResultsProperty([in] BSTR propertyName);
Parameters
[in] BSTR propertyName String containing the property to add to the list of
properties returned in results.
Remarks
In conjunction with AdditionalResultsProperties, this is now the preferred way
to set up a list of properties to be returned. A custom property can be specified
using the propertySet.propertyName format.
Return value
rvS_OK Success.
rvE_POINTER
rvE_INVALIDARG A property name has not been specified
Example
C#
search.AddAdditionalResultsProperty ("natc");
See also
602 Search API
IIndexSearch2 :: AddAdditionalResultsCustomProperty
IIndexSearch2 ::
AddAdditionalResultsCustomProperty
This method is used to add a single custom property to the
Syntax
HRESULT AddAdditionalResultsCustomProperty([in] BSTR propertySet,
[in] BSTR propertyName);
Parameters
[in] BSTR propertySet String containing the name of the property set.
[in] BSTR propertyName String containing the name of the property.
Remarks
If the property is in the global property set, then the propertySet parameter
should be set to NULL.
Custom properties can be added at the time of storage using the
ISimpleIndexMetaData interface.
Return value
rvS_OK Success.
rvE_POINTER A property name has not been specified.
rvE_INVALIDARG A property name has not been specified.
Example
C#
search.AddAdditionalResultsCustomProperty("custpropset",
"custpropname");
Search API 603
IIndexSearch2 :: AddAdditionalResultsCustomProperty
See also
■ “SimpleIndexMetadata object” on page 277
604 Search API
IIndexSearch2 :: Reset
IIndexSearch2 :: Reset
This method is used to reset the object properties to their default values.
Syntax
HRESULT Reset();
Remarks
This method is used to reset the object properties to their default values.
Return value
rvS_OK Success.
Example
C#
private void resetButton_Click(object sender, EventArgs e)
{
//reset button pressed so reset all object properties to default
search.Reset();
}
Search API 605
IndexVolumeSets object
■ IIndexVolumeSets
This interface provides a set of properties than can used to manage a collection
of index volume sets.
Syntax
interface IIndexVolumeSets : IDispatch
Member summary
ArchiveEntryId The archive Id of the archive to which the index volume set
collection belongs.
ArchiveName The name of the archive.
HasFolders Whether the archive contains a folder structure.
Count The number of index volume sets in the collection.
_NewEnum Returns an enumerator object for the collection of Index Volume

Set objects or an Index Volume Set collection.
Item Returns an Index Volume Set object using a 1-based index of the
collection.
Remarks
An index volume set comprises a sequence of index volumes; the order of index
volumes is defined by the value of FirstItemSequenceNumber. Thus each index
volume set contains all items archived between a start and end date defined by
OldestArchivedDate and YoungestArchivedDate properties of the first and last
index volume respectively.
The volume sets can be enumerated either using the Item property of
IIndexVolumeSets, or using the enumerator returned by _NewEnum.
This interface pointer is returned by a call to the ListIndexVolumeSets method
of IIndexSearch2.
606 Search API
Example
Note that IIndexSearch2::SelectArchive must be called before using
IIndexSearch2::IndexVolumeSets.
C#
See also
■ “IIndexSearch2 :: IndexVolumeSets” on page 568
■ “IIndexSearch2 :: ListIndexVolumeSets” on page 590
■ “IIndexVolumeSet :: FirstItemIndexSequenceNumber” on page 620
■ “IIndexVolumeSet :: OldestArchivedDate” on page 621
■ “IIndexVolumeSet :: YoungestArchivedDate” on page 622
■ “IIndexVolumeSets :: Item” on page 613
■ “IIndexVolumeSets :: _NewEnum” on page 611
Search API 607
IIndexVolumeSets :: ArchiveEntryId
IIndexVolumeSets :: ArchiveEntryId
This property returns the archive Id of the archive to which the index volume
set belongs.
Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value);
Parameters
[out,retval] BSTR* value Pointer to a string that will hold the currently selected
archive Id.
Remarks
Gets the ArchiveEntryId associated with the current index volume sets.
SelectArchive must be called prior to using this property.
Return value
rvS_OK Success.
rvE_POINTER The pointer passed in to receive the current value is invalid.
Example
C#
e1");
IIndexVolumeSets volSets =
(IIndexVolumeSets)search.IndexVolumeSets;
string aeid = volSets.ArchiveEntryId;
608 Search API
IIndexVolumeSets :: ArchiveName
IIndexVolumeSets :: ArchiveName
This property returns the name of the archive to which the index volume set
belongs.
Syntax
Parameters
[out,retval] BSTR* value Pointer to a string that will contain current name.
Remarks
Return value
rvS_OK Success.
rvE_POINTER The pointer to a string passed to the property is invalid.
Example
C#
string archName = volSets.ArchiveName;
Search API 609
IIndexVolumeSets :: HasFolders
IIndexVolumeSets :: HasFolders
This property indicates whether the archive contains a folder structure.
Syntax
HRESULT HasFolders([out,retval] VARIANT_BOOL* value);
Parameters

a true value if the archive contains a folder
structure.
Remarks
Return value
rvS_OK Success.
rvE_POINTER The pointer to a string passed in to receive the current value is invalid.
Example
C#
if (volSets.HasFolders == true)
{
//do something
610 Search API
IIndexVolumeSets :: Count
IIndexVolumeSets :: Count
This property returns the number of index volume sets associated with the
currently selected archive.
Syntax
HRESULT Count([out,retval] long* value);
Parameters
[out,retval] long* value Long pointer to receive the current number of index
volume sets for the current archive.
Remarks
Return value
rvS_OK Success.
rvE_POINTER The long integer pointer passed to the parameter to receive

the current value is not valid.
Example
C#
for (int i = 1; i <= volSets.Count; i++)
{
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i);
//do something
Search API 611
IIndexVolumeSets :: _NewEnum
used to enumerate the collection. This property is hidden in VBScript.
Syntax
Parameters
[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface

of the object.
Remarks
is automatically used internally when you use the For Each construct in C#,
VBScript.
Return value
rvS_OK Success.
rvE_POINTER The pointer to the IUnknown pointer passed to the property

is invalid.
Examples
The following examples show how to enumerate the Index Volume Sets in an
Index Search object.
C#
e1");
{
//do something
612 Search API
See also
“IIndexVolumeSets :: Item” on page 613
Search API 613
IIndexVolumeSets :: Item
This property returns an index volume set instance from the collection, based
on the index value passed to it.
Syntax
HRESULT Item([in] long index,
[out,retval] IUnknown** indexVolumeSet);
Parameters
[in] long index The 1-based index of index volume sets

in the collection.
[out,retval] IUnknown** indexVolumeSet Returns an IUnknown interface to the

index volume set object.
Remarks
This property provides an alternative method to _NewEnum for accessing the
IIndexVolumeSet pointers contained in the collection.
IIndexSearch2::SelectArchive must be called prior to using this property.
Return value
rvS_OK Success.

is invalid.
rvE_INVALIDARG
Example
C#
e1");
614 Search API
for (int i = 1; i <= volSets.Count; i++)

{
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i);
//do something
C++
#import "IndexClient.dll"
using namespace EVIndexClient;
long volSetCount = 0;
IIndexVolumeSetsPtr volSets;
IIndexVolumeSetPtr volumeSet;
indexSearch.SelectArchive(archiveId);
volSets = indexSearch.IndexVolumeSets();
volSetCount = volSets.Count();
for(long i = 1; i <= volSetCount; ++i)

{
volumeSet = volSets.Item(i);
// Display the volume set details, ensure date time values

are returned and displayed in local system time
volumeSet.PutDateTimesUTC(VARIANT_FALSE);
DisplayVolumeSet(volumeSet);
}
See also
■ “IIndexVolumeSets :: _NewEnum” on page 611
Search API 615
IndexVolumeSet object
The IndexVolumeSet object implements the following interface:
■ IIndexVolumeSet
IIndexVolumeSet interface provides a set of properties that can be used to query
a particular index volume set for the current archive.
IndexVolumeSet pointers can be obtained using the IIndexVolumeSets interface
that enables users to iterate through the index volume sets for an archive.
Syntax
interface IIndexVolumeSet : IDispatch
Member summary
Identity Read only The Id of the current index volume set.
ArchiveEntryID Read only The archive Id of the archive to which

the index volume set collection
belongs.
ArchiveName Read only The name of the archive to which the

index volume set belongs.
FirstItemIndexSequenceNumber Read only Each indexed item in an archive has a

unique Index Sequence Number (ISN).
The order of index volumes is defined
by the ISN of the first item in the index
volume.
OldestArchivedDate Read only Archived date of oldest item

referenced in this index volume set.
YoungestArchivedDate Read only Archived date of youngest item

referenced in this index volume set.
OldestItemDate Read only The oldest date property of the items

indexed in the index volume set.
YoungestItemDate Read only The youngest date property of the

items indexed in the index volume set.
616 Search API
DateTimesUTC Read/Write Indicates whether property values of

type VT_DATE are returned as UTC or
local system time. By default, items are
always archived using UTC time.
Remarks
IIndexVolumeSet interface pointers can be obtained using the properties of the
IIndexVolumeSets interface that allows you to iterate through the index volume
sets for an archive.
Example
C#
The following examples show two ways of obtaining an object of type
IIndexVolumeSet. Both ways assume that an object of type IIndexVolumeSets,
'volSets', has been obtained.
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(index);
//index is a '1' based index into the collection of IIndexVolumeSets
or
//Use the 'foreach' method with IIndexVolumeSets::_NewEnum:
{
//do something
See also
Search API 617
IIndexVolumeSet :: Identity
IIndexVolumeSet :: Identity
This property returns the Id of the current index volume set.
Syntax
HRESULT Identity([out,retval] LONG* value);
Parameters
[out,retval] LONG* value Pointer to a long integer which will receive the current
value.
Return value
rvS_OK Success.
rvE_POINTER The long integer pointer passed into the property is invalid.
Example
C#
IIndexVolumeSets volSets = (IIndexVolumeSets)
search.IndexVolumeSets;
{
}
618 Search API
IIndexVolumeSet :: ArchiveEntryID
IIndexVolumeSet :: ArchiveEntryID
This property returns the archive Id of the archive to which the index volume
set collection belongs.
Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value);
Parameters
[out,retval] BSTR* value Pointer to a string that will contain the current Id.
Return value
rvS_OK Success.
rvE_POINTER The string pointer passed into the property is invalid.
Example
C#
string archId = volSet.ArchiveEntryId;
Search API 619
IIndexVolumeSet :: ArchiveName
IIndexVolumeSet :: ArchiveName
This property returns the name of the archive to which the index volume set
collection belongs.
Syntax
Parameters
[out,retval] BSTR* value Pointer to a string that will contain the current Id.
Return value
rvS_OK Success.
rvE_POINTER Pointer to a string that will contain the current Id.
Example
C#
string archId = volSet.ArchiveName;
620 Search API
IIndexVolumeSet :: FirstItemIndexSequenceNumber
IIndexVolumeSet :: FirstItemIndexSequenceNumber
This property returns the Index Sequence Number (ISN) of the first item in the
index volume set.
Syntax
HRESULT FirstItemIndexSequenceNumber([out,retval] VARIANT* value);
Parameters
[out,retval] VARIANT* value Pointer to a VARIANT that will receive the index
number.
Remarks
The value of this property determines the order of volume sets in the collection.
The number is returned as a VARIANT and could be either a variant type VT_I4
or VT_I8. In Windows 2000, VT_I8 is not supported, so variant type will be
VT_DECIMAL.
Return value
rvS_OK Success.
rvE_POINTER The VARIANT pointer passed to the property is not valid.
Example
C#
object obj = volSet.FirstIndexSequenceNumber;
Search API 621
IIndexVolumeSet :: OldestArchivedDate
IIndexVolumeSet :: OldestArchivedDate
This property returns the oldest archived date of the items indexed in the index
volume set.
Syntax
HRESULT OldestArchivedDate([out,retval] VARIANT* value);
Parameters
[out,retval] VARIANT* value Pointer to a VARIANT containing the oldest archived

date in the index volume set.
Remarks
This date value is returned as VARIANT. The variant type will be VT_DATE.
Return value
rvS_OK Success.
rvE_POINTER The VARIANT pointer passed to the property is invalid.
Example
C#
object obj = volSet.OldestArchivedDate;
DateTime dateTime = (DateTime)obj;
622 Search API
IIndexVolumeSet :: YoungestArchivedDate
IIndexVolumeSet :: YoungestArchivedDate
This property returns the youngest archived date of the items indexed in the
index volume set.
Syntax
HRESULT YoungestArchivedDate([out,retval] VARIANT* value);
Parameters
[out,retval] VARIANT* value Pointer to a VARIANT that will receive the youngest
archived date in the index volume set.
Remarks
Return value
rvS_OK Success.
rvE_POINTER The VARIANT pointer passed in to the property is invalid.
Example
C#
object obj = volSet.YoungestArchivedDate;
Search API 623
IIndexVolumeSet :: OldestItemDate
IIndexVolumeSet :: OldestItemDate
This property returns the oldest item in the index.
Syntax
HRESULT OldestItemDate([out,retval] VARIANT* value);
Parameters
[out,retval] VARIANT* value Pointer to a VARIANT that will receive the oldest
date of items in the index volume set.
Remarks
Return value
rvS_OK Success.
Example
C#
object obj = volSet.OldestItemDate;
624 Search API
IIndexVolumeSet :: YoungestItemDate
IIndexVolumeSet :: YoungestItemDate
This property returns the youngest item in the index.
Syntax
HRESULT YoungestItemDate([out,retval] VARIANT* value);
Parameters
[out,retval] VARIANT* value Youngest date of items in the index volume set.
Remarks
Return value
rvS_OK Success.
Example
C#
object obj = volSet.YoungestItemDate;
Search API 625
IIndexVolumeSet :: DateTimesUTC
This property indicates whether property values of type VT_DATE are returned
as UTC or local system time.
Syntax
HRESULT DateTimesUTC([in] VARIANT_BOOL value);
HRESULT DateTimesUTC([out,retval] VARIANT_BOOL* value);
Parameters
[in] VARIANT_BOOL value VARIANT_BOOL containing the new value to

set.
[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will

receive the current value.
Return value
rvS_OK Success.
rvE_POINTER The VARIANT_BOOL pointer passed to the property is

invalid.
Example
C#
[in]
{
//make sure we return the datetime in local system time
volSet.DateTimeUTC = false;
object obj = volSet.YoungestItemDate;
DateTime dt = new DateTime(2006, 12, 31);
if (dateTime > dt)
{
//do something
626 Search API
}
}
[out]
{
bool utc = volSet.DateTimeUTC;
Search API 627
SearchResults object
The SearchResults object implements the following interfaces:
■ ISearchResults
■ ISearchResults2
These interfaces provide a set of methods and properties that can be used to
query and manage results returned from a search operation. Each result is
represented by an SearchResult object.
Syntax
interface ISearchResults2 :ISearchResults : IDispatch
Member summary
ISearchResults::Results Read/Write Pointer to the SearchResults object,

which contains the results (as XML)
returned from a search.
ISearchResults::Count Read only The number of results in this

SearchResults object.
ISearchResults::Total Read only Total number of results that matched the

search query.
ISearchResults::Start Read only Position in the set of results of the first

result in this SearchResults object.
ISearchResults::Options Read only Value of the Options property of the

IndexSearch2 object used to generate this
set of results. This defines the
granularity of the search results.
ISearchResults::SortBy Read only Name of the properties used to order the

search results.
ISearchResults::_NewEnum Read only Enumeration for iterating through the

results.
628 Search API
Method Read/Write Description
ISearchResults::Item Read only Set of results object returned by

enumeration.
ISearchResults2::InSync Read only Indicates whether or not the index is

synchronized with the current
contents of the archive.
ISearchResults2::TruncationReason Read only Reasons for truncated search results.
ISearchResults2::DateTimesUTC Read/Write Whether property values of type

VT_DATE are returned as UTC or local
system time.
ISearchResults2::LoadResults Write only Loads search results XML from

IStream or SAFEARRAY of bytes or a
string (BSTR).
Example
An object of type ISearchResults2 is obtained from a call to
IIndexSearch2::Search, or by creating it directly and initializing it with a set of
pre-existing results.
C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
or
ISearchResults2 results = (ISearchResults2) new SearchResults();
//assume we have a set of results in xml, held in the string
xmlResults
results.Results = xmlResults;
Search API 629
ISearchResults :: Results
This property gets or sets an XML text string which represents the results
string.
Syntax
HRESULT Results([out, retval] BSTR *pbsResults,
[in, string] BSTR bsResults);
Parameters
[out, retval] BSTR *pbsResults Pointer to a string that will receive the XML
results string.
[in, string] BSTR bsResults String that contains an XML results string to
initialize the object.
Remarks
Search results are stored in XML and can be retrieved or set using this property.
If a new string is stored then any previous results will be lost.
Return value
rvS_OK Success.
rvE_POINTER The BSTR pointer passed in to the property is invalid.
rvS_FALSE
vE_INVALIDARG
rvE_NOINTERFACE
Example
C#
[out]
630 Search API
//get the results in XML

string xmlResults = results.Results;
[in]
//assume that a previous results set has been stored in the string
’xmlResults’
ISearchResults2 src = (ISearchResults2) new SearchResults();
//initialise the new object with some existing results
src.Results = xmlResults;
Search API 631
ISearchResults :: Count
ISearchResults :: Count
This property returns the number of results found by the Search operation.
Syntax
HRESULT Count([out, retval] long *plCount);
Parameters
[out, retval] long *plCount Long integer pointer that will receive the number
found.
Remarks
The number of results returned in this SearchResults object may differ from the
number of results requested.
Return value
rvS_OK Success.
Example
C#
The following example gives an alternative approach to using 'foreach' to
enumerate the results returned.
int num = results.Count;
for (int i = 1; i <= num; i++)
{
ISearchResult2 res = (ISearchResult2)results.Item(i);
632 Search API
ISearchResults :: Total
ISearchResults :: Total
This property returns the total number of results that matched the search
query.
Syntax
HRESULT Total([out, retval] long *plTotal);
Parameters
[out, retval] long *plTotal Pointer to a long integer that will receive the total.
Remarks
Total refers to the total number of hits for the query. This number should be
greater than, or equal to, the number of results (Count).
Return value
rvS_OK Success.
Example
C#
long num = results.Count;
long total = results.Total;
if (total < num)
{
//an error has ooccured as the total should be at least equal to
the number results returned
Search API 633
ISearchResults :: Start
ISearchResults :: Start
This property returns the start position in the entire set of results of the first
result in this SearchResults object.
Syntax
HRESULT Start([out, retval] long *plStart);
Parameters
[out, retval] long *plStart Pointer to a long integer that will receive the start
position of the first result in this SearchResults
object. Value can be from 1 to Total.
Remarks
This value can be from 1 to Total.
A search application will not know what the value of Total is on the first call to
Search.
Note that Total can also change between calls to consecutive searches, as result
of newly archived, indexed and deleted items.
Return value
rvS_OK Success.
rvE_POINTER The long integer pointer that was passed to the property is
invalid.
Example
C#
long start = results.Start;
634 Search API
ISearchResults :: Options
ISearchResults :: Options
This property returns the value of the Options property of the IndexSearch2
object used to generate this set of results. The property contains search option
flags that define the granularity of search results.
Syntax
HRESULT Options([out, retval] long *plOptions);
Parameters
[out, retval] long *plOptions Pointer to a long integer that will receive the value.
Remarks
This property retrieves the value that indicates the granularity used to generate
the set of results.
See “IIndexSearch2 :: Options” on page 570.
Return value
rvS_OK Success.
Example
C#
EOptionsFlags eof = (EOptionsFlags )results.Options;
if (eof == EOptionsFlags.roAttachmentGranularity)
{
//do something
}
Search API 635
ISearchResults :: SortBy
ISearchResults :: SortBy
This property returns the value of the SortBy property of the IndexSearch2
object used to generate this set of results. The property is used to order the
returned search results.
Syntax
HRESULT SortBy([out, retval] BSTR *pbsSortBy);
Parameters
[out, retval] BSTR *pbsSortBy Pointer to a string that will receive the current
value
Remarks
See “IIndexSearch2 :: SortBy” on page 572.
Return value
rvS_OK Success.
rvE_POINTER The string pointer passed into the property is invalid.
Example
C#
string sortBy = results.SortBy;
636 Search API
ISearchResults :: _NewEnum
used to enumerate the SearchResults collection. This property is hidden in
VBScript.
Syntax
Parameters

Remarks
is automatically used internally when you use the foreach construct in C# or
VBScript.
This property provides an alternative to Item for iterating through the
collection.
Return value
rvS_OK Success.

is invalid.
Example
This property is not normally called explicitly; it allows the use of ’foreach', as
shown in the following example.
C#
foreach (ISearchResult2 res in results)
{
Search API 637
//do something
638 Search API
ISearchResults :: Item
This method is used to return the specified item in the SearchResult collection
object. The value returned is an ISearchResult interface pointer which provides
properties and methods to allow the user to extract the results data.
Syntax
HRESULT Item([in] long lIndex,
[out, retval] LPVARIANT pvResult);
Parameters
[in] long lIndex The index number of the result required in the
SearchResult collection.
[out, retval] LPVARIANT pvResult Pointer to a VARIANT that will receive the
ISearchResult pointer.
Remarks
This property can be used in place of the _NewEnum property to iterate through
the collection.
Return value
rvS_OK Success.
rvE_POINTER The LPVARIANT passed into the method is invalid.
rvE_INVALIDARG The value of the first parameter, lIndex, is either less than 1
or greater than the number of results returned.
Example
C#
int num = results.Count;
for (int i = 1; i <= num; i++)
{
ISearchResult2 res = (ISearchResult2)results.Item(i);
Search API 639
See also
■ “SearchResult object” on page 646
640 Search API
ISearchResults2 :: InSync
ISearchResults2 :: InSync
This property indicates whether or not the index is synchronized with the
current contents of the archive.
Syntax
HRESULT InSync([out,retval] VARIANT_BOOL* value);
Parameters

the current value.
Remarks
Typically a false value indicates that the index is currently being updated.
Return value
rvS_OK Success.
rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current

value is invalid.
Example
C#
bool inSync = results.InSync;
if (inSync == false)
{
MessageBox.Show("It is possible that the index was being updated
as the search was being carried out", "Index not synchronised",
MessageBoxButtons.OK, MessageBoxIcon.Warning);
}
else //carry on as normal
Search API 641
ISearchResults2 :: TruncationReason
This property indicates the reason, if any, for incomplete search results.
Syntax
HRESULT TruncationReason([out,retval] ETruncationReason* value);
Parameters
[out,retval] ETruncationReason* value Pointer to an ETruncationReason value

which contains the reason for
truncation.
Remarks
For the values that ETruncationReason can have, see “ETruncationReason
Return value
rvS_OK Success.
rvE_POINTER The ETruncationReason pointer passed into the property is

invalid
Example
C#
ETruncationReason tr = (ETruncationReason)results.TruncationReason;
if (tr == ETruncationReason.trNone)
{
//carry on processing
}
else
{
switch (tr)
{
case ETruncationReason.trAdminResultLimitExceeded:
642 Search API
//handle the problem

break;
case ETruncationReason.trAdminTimeoutExpired:
//handle the problem
break;
//and so on for the other reasons
Search API 643
ISearchResults2 :: DateTimesUTC
This property indicates whether date/time property values are returned as UTC
or local system time.
Syntax
HRESULT DateTimesUTC([in] VARIANT_BOOL value);
HRESULT DateTimesUTC([out,retval] VARIANT_BOOL* value);
Parameters
[in] VARIANT_BOOL value VARIANT_BOOL that will set a new value.
[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will

receive the current value.
Remarks
By default, items are returned as UTC time.
Return value
rvS_OK Success.
rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current

value is invalid.
Example
C#
[in]
//make sure date/time values are returned in local system time
results.DateTimesUTC = false;
[out]
if (results.DateTimesUTC == true)
{
644 Search API
//do something
Search API 645
ISearchResults2 :: LoadResults
ISearchResults2 :: LoadResults
This method can be used to load an instance of ISearchResults2 with the XML
results returned by the IIndexSearch2.SearchToXML method.
Syntax
HRESULT LoadResults([in] VARIANT rResultsXML);
Parameters
[in] VARIANT rResultsXML VARIANT containing the XML to load.
Remarks
For information on the XML schema used to return the search results, consult
Symantec support.
If possible, use the SearchResults object rather than processing the XML
directly.
The VARIANT may contain an IStream, byte array (SAFEARRAY) or a string
(BSTR) containing the XML.
Return value
rvS_OK Success.
rvE_INVALIDARG The VT TYPE of the VARIANT is incorrect.
rvS_FALSE The XML is empty or the VT TYPE is VT_EMPTY.
Example
C#
In this example, it is assumed that there is a string holding a set of XML results
from a previous search, called xmlResults.
ISearchResults2 results = (ISearchResults2) new SearchResults();
results.LoadResults(xmlResults);
646 Search API
SearchResult object
SearchResult object
The SearchResult object implements the following interfaces:
■ ISearchResult
■ ISearchResult2
These interfaces provide methods and properties that allow the user to examine
the individual results returned after a call to Search.
Syntax
interface ISearchResult2 : ISearchResult : IDispatch
Member summary
ISearchResult::Result Read/Write Gets or sets an XML string containing

the search result.
ISearchResult::Number Read only Returns a unique Id for this result.
ISearchResult2::Count Read Returns the number of properties in

this search result.
ISearchResult2::DateTimesUTC Read/Write Gets or sets the value of the

DateTimesUTC setting.
Method Description
ISearchResult::Prop Obtains the value of a specific property from the result.
ISearchResult::Prop2 Obtains the value of a specific custom property from the result.
ISearchResult2::Item Gets the property at the 1-based position in the collection.
Remarks
ISearchResult interface pointers are obtained by using either
ISearchResults::_NewEnum and iterating through the collection, or by using
ISearchResults::Item to obtain a specific pointer from the collection.
Search API 647
SearchResult object
Example
C#
The following examples show two different ways of iterating through results in
a SearchResults collection object. It is assumed there is an ISearchResults2
object, 'results', obtained from a search.
ISearchResult2 res = (ISearchResult2)results.Item(index);
//index is a '1' based index into the collection of ISearchResult's.
or
{
648 Search API
ISearchResult :: Result
ISearchResult :: Result
This property is used to get an XML string for this result or to set a new XML
string.
Syntax
HRESULT Result([out, retval] BSTR *pbsResult,
[in, string] BSTR bsResult);
Parameters
[out, retval] BSTR *pbsResult Pointer to a string that will contain the current
string.
[in, string] BSTR bsResult String that contains a new XML string to set.
Remarks
This property is simply the XML string for the search result stored in this result
object, or an empty string if the object is not initialized. It can also be used to
store an XML result. Any previous result will be overwritten.
Return value
rvS_OK Success.
rvE_POINTER The string pointer passed in to receive the current value is

invalid.
rvS_FALSE The XML string passed in is zero length.
Example
C#
{
string xmlResult = res.Result;
//do something
Search API 649
ISearchResult :: Number
ISearchResult :: Number
This property returns the unique identifier for this result.
Syntax
HRESULT Number([out, retval] long *plNumber);
Parameters
[out, retval] long *plNumber Pointer to a long integer that will contain the number.
Remarks
Returns the unique identifier for this result within the collection. The Id is
stored in the NUMBER attribute of each XML result tag.
Return value
rvS_OK Success.
rvE_POINTER The long integer pointer passed in to retrieve the value is

invalid.
Example
C#
{
long number = res.Number;
650 Search API
ISearchResult :: Prop
This method returns the specified property for the current result.
Syntax
HRESULT Prop([in, string] BSTR bsName,
[out, retval] LPVARIANT pvVal);
Parameters
[in, string] BSTR bsName String containing the name of the property.
[out, retval] LPVARIANT pvVal Pointer to a VARIANT that will contain the
property value.
Remarks
The value returned can be either a date, string or integer. If the value is
multi-valued, the returned VARIANT is an array of VARIANTS, each of which
contains a date, string or integer value.
The following VARIANT types may be returned: VT_I4, VT_UI4, VT_I8,
VT_DECIMAL, VT_DATE, VT_BSTR or VT_EMPTY.
The name can be that of a custom property, in the
Return value
rvS_OK Success.
rvE_POINTER The VARIANT point passed in to receive the property value is

invalid.
rvS_FALSE Property not found.
Example
C#
Search API 651
{
object obj = res.Prop("ssid");
string ssid = (string)obj;

RetrieveItem(ssid);
652 Search API
ISearchResult :: Prop2
This method is used to get the value of a specific custom property.
Syntax
HRESULT Prop2([in] BSTR bsName,
[in] BSTR bsPropertySet,
[in] BSTR bsPropertyName,
[out, retval] LPVARIANT pvVal);
Parameters
[in] BSTR bsName This parameter is not currently used.
[in] BSTR bsPropertySet String containing the name of the property set to
which the property belongs.
[in] BSTR bsPropertyName String containing the name of the property.
[out, retval] LPVARIANT pvVal Pointer to a VARIANT that will receive the value of
the property.
Remarks
This method returns the value of a custom property. If the requested property
does not exist, an initialized but empty VARIANT will be returned.
Return value
rvS_OK Success.
rvE_POINTER The VARIANT pointer passed in to receive the value is

invalid.
rvS_FALSE The custom property could not be found.

Search API 653
Example
C#
This example assumes there is a custom property set, "CustomTags", which has
an integer property, "Importance".
{
int tag = 0;
//the prop we want should be an int but make sure
object obj = res.Prop2("CustomTags", "Importance");
Type type = obj.GetType();
if (type.Name == "Int32")
{
tag = (int)obj;
654 Search API
ISearchResult2 :: Count
ISearchResult2 :: Count
This property returns the number of properties in the current search result.
Syntax
HRESULT Count([out, retval] long* count);
Parameters
[out, retval] long* count Long pointer that will receive the number of properties
in search result.
Return value
rvS_OK Success.
rvE_POINTER The long integer pointer passed into receive the count
number is invalid.
Example
C#
{
int count = res.Count;
for (int i = 1; i < = count; i++)
{
object objProp = null;
object objVal = null;
res.Item(i, out objProp, out objVal);
if ((string)objProp == "ssid")
{
string ssid = (string)objVal;
//do something
Search API 655
ISearchResult2 :: Item
This method returns the property name and value of the property at the position
in the index specified by the first parameter.
Syntax
HRESULT Item([in] long index,
[out] LPVARIANT propertyName,
[out] LPVARIANT propertyValue);
Parameters
[in] long index The index position of the required property.
[out] LPVARIANT propertyName Pointer to a VARIANT that contains the name of

the property.
[out] LPVARIANT propertyValue Pointer to a VARIANT that will contain the value
assigned to the property.
Remarks
Use this method to obtain the name and value of a property at a specific position
in the collection. Note that the collection is 1-based not 0-based.
The name can be that of a custom property, in the
Return value
rvS_OK Success.
rvE_POINTER One of the VARIANT pointers passed to the method is invalid.
rvE_INVALIDARG The index was outside the range 1 to the number of

properties.
656 Search API
Example
C#
{
int count = res.Count;
for (int i = 1; i < = count; i++)
{
object objProp = null;
object objVal = null;
res.Item(i, out objProp, out objVal);
if ((string)objProp == "ssid")
{
string ssid = (string)objVal;
//do something
Search API 657
ISearchResult2 :: DateTimesUTC
This property indicates whether property values of type VT_DATE are returned
as UTC or local system time.
Syntax
HRESULT DateTimesUTC([in] VARIANT_BOOL value,
[out,retval] VARIANT_BOOL* value);
Parameters
[in] VARIANT_BOOL value VARIANT_BOOL containing the new value to set.
[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will receive

the current value.
Remarks
By default, items are always archived using UTC time.
Return value
rvS_OK Success.
Example
C#
[in]
{
//make sure date/times are returned in local system time
res.DateTimesUTC = false;
//do something
[out]
658 Search API

{
bool isUTC = res.DateTimesUTC;
//do something
Appendix A
About Enterprise Vault
indexes
This section provides more detailed information about Enterprise Vault indexes.
About index volume sets and volumes

Each archive index comprises one or more sequential index volume sets. An
index volume set contains an index volume. (Currently, an index volume set can
contain only one index volume). Each index volume contains index entries for
the items stored in the archive.
See Figure 8-1 on page 519.
An index volume can contain approximately three to five million index
documents. The maximum number of index entries for a volume will depend on
the level of indexing set and the number of properties indexed for each item.
When an index volume is full, the Enterprise Vault Indexing service
automatically creates a new index volume set (containing a new index volume).
The Enterprise Vault administrator uses the Enterprise Vault Administration
Console to configure the physical locations to be used by the Indexing service
when creating new indexes for archives.
Typically, user mailbox indexes will require only a single volume. Indexes for
larger archives, such as file system archives and journal archives, are quite
likely to have multiple volumes.
About index properties

Enterprise Vault indexes a set of system properties for each item. The system
properties indexed depend on the level of indexing configured when the item is
archived.
660 About Enterprise Vault indexes
About index schemas
In addition to the system index properties, you can add custom index metadata
properties to the index document for an item. These properties may be required
to enable users or third-party applications to search for particular items.
Custom index metadata can be added in the following ways:
■ Using the SimpleIndexMetadata interface of the Content Management API.
An application that submits items to Enterprise Vault for archiving using
the Content Management API can call the SimpleIndexMetadata methods
and properties to add custom index metadata to the item before it is
archived.
■ Using the External Filtering API.
The IArchivingControl interface can be used to add custom index metadata
properties as required by the external filter as an item is archived.
Note that custom index metadata properties cannot be added for attachments.
About index schemas

The contents of index entries differs depending on the index schema in use. This
affects the way indexes are searched and the results returned.
There are two index schemas available with Enterprise Vault:
■ Default schema
■ Item Granularity Only schema
If you are using the Item Granularity Only schema, then the registry setting,
SchemaType, will have a value of "1". This setting, if configured, is in the
following location:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\Indexing
Which schema an installation uses will depend on the type of applications that
will search the indexes. In general, any application that performs complex
searches, such as those performed by Enterprise Vault Compliance and
Discovery Accelerator products, should use the Item Granularity Only schema.
The Item Granularity Only schema enables such searches to be performed
considerably faster than the default schema.
If you have an existing Enterprise Vault environment, you need to consider the
following if you decide to enable the Item Granularity Only schema:
■ After you enable the schema (using the SchemaType registry setting), only
new indexes will be affected. Existing indexes need to be rebuilt in order to
About Enterprise Vault indexes 661
About index schemas
use the new schema. If you have a very large number of archives, this could
take a considerable time.
■ Users will see a difference in the number of results returned when
searching with Enterprise Vault browser search or the Enterprise Vault
search integrated with Outlook. By default, these search applications return
both top-level items and individual attachments, and with the Item
Granularity Only schema, they will not see individual attachments.
Default index schema

With the default index schema, an index document is created for the top-level
item (such as a message), and separate index documents are created for each
attachment; each nested message and attachment is stored in a separate index
document.
When a search is performed, each index document is searched, and all items
that contain a match are returned as individual results; so results may contain
both top-level items and attachments.
For example, a search for “John Doe” AND “Widgets Corp” will return any items
or attachments that contain both “John Doe” and “Widgets Corp” in the same
index document.
With this schema, performing a very complex search could result in a very large
number of active queries in memory, potentially resulting in “out of memory”
errors. For this reason, search query “chunking” settings may be required to
limit the number of active queries in memory.
Item Granularity Only schema

With the Item Granularity Only schema, there is a single index document for the
top-level message and any attachments; this means that the top-level item and
attachments are searched as a single item.
When a search is performed, the single index entity (containing both top-level
items and attachments) is searched, and only top-level items are returned in the
results. Even if the search criteria is only matched in one or more attachments,
only the associated top-level item is returned in the results. Attachments can be
accessed from the top-level items.
As index data for an item and any attachments are stored in the same index
document, searches for terms that are combined using AND may return more
results than are returned with the default schema. For example, a search for
“John Doe” AND “Widgets Corp” may return an item which has “John Doe” in
attachment 1 and “Widgets Corp” in attachment 3.
By combining the information from attachments into the top-level item in the
index, the need to configure query “chunking” for very complex searching is
662 About Enterprise Vault indexes
About index schemas
removed. Complex searches, such as those performed by Enterprise Vault

Compliance and Discovery Accelerator products, are considerably faster if this
index schema is used.
Appendix B
Enterprise Vault
Properties
This section lists the properties that are defined by Enterprise Vault:
■ System properties
■ Defined custom properties
■ Defined custom FSA properties
■ Defined custom SharePoint properties
■ Defined custom properties for Compliance Accelerator.
When processing an item, Enterprise Vault populates properties with
information in the item. This data is then stored with the archived item. Indexed
properties are added to the archive index and can be used in archive searches.
Not all properties are present on every item, and the type library defines many
more properties than are currently used. The data available in search results for
each item is a subset of these properties; any properties that are to be returned
in search results must be defined as retrievable.
Note: If you are using the Search API from a language that cannot access the
string constants that are defined in the type library, any string literals used
instead must match exactly the values from the type library. For example, for
IndexPropSSID use "ssid".
In the following tables:

■ Searchable properties are those that can be used in search queries.
■ Retrievable properties are those that can be returned in search results.
■ Multi-valued properties can have multiple values for a single index entry.
664 Enterprise Vault Properties
System properties
■ Sortable properties are those that can be used to order search results.
Properties marked with are optimized in the index for sorting and
provide the quickest results.
System properties
This section lists the system properties defined in Enterprise Vault.
All properties in this table have defined constants, IndexPropXXXX, where
XXXX is the uppercase form of the property name. For example, IndexPropSUBJ
is the constant for the defined property, “subj”, and IndexPropRCAT is the
constant for the system property, “rcat”.
Table B-1 System properties
Description Name Type Search- Retriev- Multi- Fast Notes

able able Valued Sort-
able
Subject/Title subj String
Message Priority prio String Although indexed as a string,

usually a numeric value.
Technically no limit,
practically limited to 32-bit
integer maximum.
Message Importance impo String Although indexed as a string,

integer maximum.
Message Sensitivity sens String Although indexed as a string,

integer maximum.
Message Security secu String Currently not populated with

any value.
Message Originator orgn String
Original identifier for iden String

the item.
(e.g. SubmissionId for
a sent message)
Last Modified date of mdat Date Range 1 Jan 1970 to 31 Dec

the item 2148
Enterprise Vault Properties 665
System properties

able
Original identifier for coid String

this component of
the item
Data type of the item dtyp String E.g. DOC, XLS, MSG
De-duplication fpdd String Can be used to find an exact

fingerprint of item match of a message or a
document.
Content fingerprint fpcn String Can be used to find a match

of item on an attachment or
document content.
Archived Date adat Date Range 1 Jan 1970 to 31 Dec

2148
Original location of locn String A sequence of folders.

the item
Current location of clcn String A sequence of folders.

the item
The last or leaf folder lolf String

of original location
The last or leaf folder cllf String

of current location
Original location lofn String

folder names
(ordered)
Current location clfn String

folder names
(ordered)
The item's Saveset ssid String See “Note 1” on page 676.

identifier Max 72 chars. However, if
you include any attachment
num, as per Note 1, then the
max number of chars is
76 + 1 + 10 => 87 chars.
Shortcut location shct String Not supported from

Enterprise Vault 10.
System properties

able
User who archived user String Currently not populated.

the item.
Original retention rcat String Max 112 chars.

category Id
Current retention crct String Max 112 chars.

category Id
Original retention rcnm String Max 32 chars

category name
Current retention crcn String Max 32 chars

category name
Index Sequence snum Integer 64-bit integer

Number
VaultEntryId of index vlid String Max 112 chars.

containing the item
Created, date Date Range 1 Jan 1970 to 31 Dec

sent/received or 2148
archivedDate See “Note 2” on page 676
Content cont String Search API: Only the first

120 significant characters
can be retrieved.
Content Management API:
HTML representation to a
max of 5 MB.
See “Note 3” on page 676
Languages lang String Currently not populated.
Categories/Keywords keys String
The size of the item size Integer 32-bit integer

in KB
The number of natc Integer 32-bit integer

attachments
Permission VaultIds pvid String Max 112 chars.

for the item. (Known
as Archive Folder
VaultIds)
System properties

able
Attachment Number anum Integer 32-bit integer

Zero for top-level item.
In ItemGranularity schema,
this property cannot be used
in a query to limit hits on
attachments or top level
documents. This is because
each index document
contains the parent item and
all the attachments.
Expiry date for the edat Date Range 1 Jan 1970 to 31 Dec
item (based on crct) 2148
Number of days to ndte Integer 32-bit integer

expiry for the item
(based on crct)
Rank value of the rank Integer 32-bit integer

item when sorted by
relevance (0 to
10,000)
The item's original msgc String

MAPI Message Class
(e.g. IPM.Note)
Message Flag Status flag Integer 32-bit integer
Reason for missing comr String See “Note 4” on page 677

content Technically no limit,
integer max.
Attachments only. taut String Not applicable to items

The author of the indexed using
ItemGranularity schema.
top-level item
Attachments only. tsub String Not applicable to items

The subject/title of indexed using
the top-level item
Attachments only. tsiz Integer 32-bit integer

The size of the Not applicable to items
top-level item in KB indexed using
System properties

able
Conversation cnid String For MAPI items, a 32

tracking ID hexadecimal character
representing a 128-bit GUID.
Currently not populated for
other items.
Conversation cnhv String For MAPI items, 12

tracking index hexadecimal characters
representing a datetime,
followed by 32 hexadecimal
characters representing a
128-bit GUID, followed by 10
hexadecimal characters for
each reply/forward.
Currently not populated for
other items.
Conversation cntp String Currently only populated for

tracking topic MAPI items.
Index Volume. ivid Integer 32-bit integer

Identity of the
volume containing
the item
Index Volume Set. vsid Integer 32-bit integer

Identity of the
volume set
containing the item
Message Envelope menv String Only present for Exchange

recipient and sender journal messages.
information See “Note 5” on page 677
Retrievable using the
(see “IArchiveMetaData ::
IndexData” on page 253)
Message Envelope jrcp String Only present for Exchange

Recipient. journal messages. The
property values include both
Union of jrto, jrcc,
email addresses and display
jrbc & jren names (where present).
Message Envelope jrto String Only present for Exchange

TO: Recipient journal messages.
See Notes for jrcp.
System properties

able
Message Envelope jrcc String Only present for Exchange

CC: Recipient journal messages.
See Notes for jrcp.
Message Envelope jrbc String Only present for Exchange

BCC: Recipient journal messages.
See Notes for jrcp.
Message Envelope jren String Only present for Exchange

Other Recipient journal messages.
See Notes for jrcp.
Used when the recipient
details are not explicitly
identified as a TO, CC, or BCC
recipient.
Message Envelope jrau String Only present for Exchange

Author journal messages.
Union of jrfm, jrpp & See Notes for jrcp.
jaen
Message Envelope jrfm String Only present for Exchange

FROM: Recipient journal messages.
See Notes for jrcp.
Message Envelope jrpp String Only present for Exchange

PP: Recipient journal messages.
Per Procurationem See Notes for jrcp.
(by delegation to):
person on whose
behalf document has
been written or
message has been
sent
Message Envelope jaen String Only present for Exchange

Other Author journal messages.
See Notes for jrcp.
Used when the author details
are not explicitly identified
as FROM or PP.
System properties

able
Message Sender and sere String See “Note 6” on page 678

Recipient Retrievable using the
(see “IArchiveMetaData ::
IndexData” on page 253)
Message Recipient. recp String

Union of redn, reea,
resm, reot & jrcp
Message Recipient. redn String

Display/friendly
name. Union of rtdn,
rcdn, rbdn & rndn
Message Recipient. reea String

Email address. Union
of rtea, rcea, rbea &
rnea
Message Recipient. resm String

SMTP email address.
Union of rtsm, rcsm,
rbsm & rnsm
Message Recipient. reot String

Other email address.
Union of rtot, rcot,
rbot & rnot
TO: Recipient reto String Max 256 chars.

The retrievable value is the
first few RTDN (or RTSM)
values, up to a maximum of
256 characters.
TO: Recipient. rtdn String

Display/friendly
name
TO: Recipient. rtea String

of RTSM & RTOT
TO: Recipient. rtsm String

SMTP email address
System properties

able
TO: Recipient. rtot String

Other email address
CC: Recipient recc String Max 256 chars.

256 characters.
CC: Recipient. rcdn String

Display/friendly
name
CC: Recipient. rcea String

of rcsm & rcot
CC: Recipient. rcsm String

SMTP email address
CC: Recipient. rcot String

Other email address
BCC: Recipient rbcc String Max 256 chars.

256 characters.
BCC: Recipient. rbdn String

Display/friendly
name
BCC: Recipient. rbea String

of rbsm & rbot
BCC: Recipient. rbsm String

SMTP email address
BCC: Recipient. rbot String

Other email address
System properties

able
Other Envelope renv String Max 256 chars.

Recipient The retrievable value is the
256 characters.
Other Envelope rndn String

Recipient.
Display/friendly
name
Other Envelope rnea String

Recipient.
of rnsm & rnot
Other Envelope rnsm String

Recipient.
SMTP email address
Other Envelope rnot String

Recipient.
Other email address
Number of Recipients nrcp Integer 32-bit integer
Number of TO: nrto Integer 32-bit integer

Recipients
Number of CC: nrcc Integer 32-bit integer

Recipients
Number of BCC: nrbc Integer 32-bit integer

Recipients
Number of Other nren Integer 32-bit integer

Envelope Recipients
Author. Union of auth String

audn, auea, ausm,
auot, writ, from, ppgn
& jrau
System properties

able
Author. audn String

Display/friendly
name. Union of wrdn,
frdn, ppdn
Author. auea String

of ausm, auot and
wrea
Author. ausm String

SMTP email address.
Union of wrsm, frsm
ppsm
Author. auot String

Union of wrot, frot,
ppot
Writer. writ String

Union of wrdn, wrea,
wrsm, wrot
Writer. wrdn String

Display/friendly
name
Writer. wrea String

of wrsm & wrot
Writer. wrsm String

SMTP email address
Writer. wrot String

Other email address
FROM: from String

Union of frdn, frea,
frsm, frot
FROM: frdn String

Display/friendly
name
System properties

able
FROM: frea String

of frsm & frot
FROM: SMTP e-mail frsm String

address
FROM: frot String

Other email address
PP ppgn String
Union of ppdn, ppea,
ppsm & ppot. Per
Procurationem (by
delegation to) person
on whose behalf
document has been
written or message
has been sent
PP ppdn String
Display/friendly
name
PP ppea String
Exchange email
address. Union of
ppsm, ppot
PP ppsm String
SMTP email address
PP ppot String
Other email address
Name name String

Union of recp, auth
Name nadn String

Display/friendly
name. Union of redn
& audn
System properties

able
Name naea String

Exchange email
address. Union of
reea & auea
Name nasm String

SMTP email address.
Union of resm &
ausm
Name naot String

Union of reot & auot
Text text String

Union of cont & subj
Event start date csrt Date Range 1 Jan 1970 to 31 Dec

E.g. Calendar meeting 2148
start date
Event end date cend Date Range 1 Jan 1970 to 31 Dec

E.g. Calendar meeting 2148
end date
Event location clon String

E.g. Calendar meeting
location
Task due date tddt Date Range 1 Jan 1970 to 31 Dec

2148
Task completed date tcdt Date Range 1 Jan 1970 to 31 Dec

2148
Task status tsts Integer Property value can be one of

the following:
0 = Not started
1 = In progress
2 = Completed
3 = Paused
4 = Deferred
System properties
Note 1
The ssid value returned for attachments is a concatenation of the SavesetId and
the attachment number (see anum), separated by a full stop.
For example, for the first attachment:
849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B
0.1
To use the Content Management API to retrieve the item, the SavesetId must be
extracted by removing the trailing full stop and attachment number:
849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B
0
Note 2
For a message, this is selected from the first of the following properties that is
present on the message:
Message Delivery Time (PR_MESSAGE_DELIVERY_TIME)
Original Message Delivery Time (PR_ORIGINAL_DELIVERY_TIME)
Submission Time (PR_CLIENT_SUBMIT_TIME)
Original Message Submission Time (PR_ORIGINAL_SUBMIT_TIME)
Message Transport Provider Submission Time (PR_PROVIDER_SUBMIT_TIME)
Last Modification Time (PR_LAST_MODIFICATION_TIME)
Creation Time (PR_CREATION_TIME)
Deferred Delivery Time (PR_DEFERRED_DELIVERY_TIME)
For an attachment to a message or a document, this is the created date of the
object (PR_CREATION_TIME).
In the extreme case that none of the above properties are available, then the
current time (archival time) is used.
Note 3
In the Search API, the value is the first 120 characters of the textual
representation of the content.
In the Content Management API, the value is the HTML representation of the
content to a maximum of 5 MB.
If the size is larger than 5 MB, no value is returned, but a content missing reason
property (comr) with value vmrVALUENOTOBTAINED is returned instead.
The 5 MB limit can be changed using the registry value,
HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\MaxIndexDataHTMLContentKB
System properties
Note 4
Predefined values for comr property:
enum EValueMissingReason
{
vmrNOREASON =0 No reason available
vmrVALUENOTFOUND =1 Content does not exist
vmrVALUENOTOBTAINED =2 Content could not be obtained
vmrVALUECORRUPT =3 Content is (or appears to be) corrupt
vmrNOCONVERTER =4 Not possible to convert content to
suitable format (i.e. no converter for this specific conversion)
vmrCONVERSIONFAILED =5 Conversion of content failed (i.e.
converter error)
vmrCONVERSIONTIMEDOUT =6 Conversion of content timed out
vmrFORMATEXCLUDED =7 Content requires conversion but its data
format is excluded from conversion
vmrCONVERSIONBYPASS =8 Content requires conversion but
conversion bypass has been set
vmrVALUEENCRYPTED =9 Content is encrypted
vmrCONVERTERUNINIT =10 Content requires conversion but
converters are not available, or have not been initialized
vmrADDITEMTOINDEX =11 Unable to add content to index
vmrFORMATNOTRECOGNISED =12 Converters did not recognize the file
type
vmrLARGEFILE =13 Conversion excluded for large files
vmrUNKNOWNCODEPAGE =14 Conversion excluded for codepages we
cannot detect (e.g. GB18030)
Note 5
The menv property contains the Message Envelope recipient and sender
information for journal messages, in XML format. The following is an example
of what it can contain:
<?xml version="1.0" encoding="utf-16?">

<MSGENV>
<RECP P1="true">
<TO>
<RC>
<DN>Joe User</DN>
<EA>Joe.User@email.com</EA>
</RC>
<DL>
<DN>Internal Users</DN>
<EA>Internal.Users@ourcompany.com</EA>
<RC>
<DN>Administrator</DN>
<EA>admin@ourcompany.com</EA>
</RC>
<RC>
<DN>CEO</DN>
System properties
<EA>theboss@ourcompany.com</EA>
</RC>
</DL>
</TO>
<CC />
<BCC>
<RC>
<DN>Jill User</DN>
<EA>Jill.User@email.com</EA>
</RC>
</BCC>
<ENV>
<RC>
<DN>John User</DN>
<EA>John.User@email.com</EA>
</RC>
</ENV>
</RECP>
<AUTH>
<FROM><DN>Chris Davies</DN> <EA>CDavies@ourcompany.com</EA>
</FROM>
<PP><DN>Bill Stephens</DN><EA>BStephens@ourcompany.com
</EA></PP>
</AUTH>
</MSGENV>
This example is not exhaustive. The full XSD also specifies DLs and their
nesting.
The values returned for recipient properties (e.g. reto, renv) for
envelope-journal items are returned from the envelope (P1) unless the message
(P2) contains at least the same number of (or more) recipients for each index
property.
The AUTH element contains the message sender/author details (FROM). Where
a message has been sent on behalf of another user, the AUTH information will
include both the sender (FROM) and delegate (PP) details.
Note 6
The sere property contains the sender and recipient information in XML format.
The following is an example of what it can contain:
<?xml version="1.0" encoding="utf-16?">
<MSG>
<RECP>
<TO>
<RC>
<DN>Joe User</DN>
<EA>Joe.User@email.com</EA>
</RC>
System properties
<DL>
<DN>Internal Users</DN>
<EA>Internal.Users@ourcompany.com</EA>
<RC>
<DN>Administrator</DN>
<EA>admin@ourcompany.com</EA>
</RC>
<RC>
<DN>CEO</DN>
<EA>theboss@ourcompany.com</EA>
</RC>
</DL>
</TO>
<CC />
<BCC />
</RECP>
<AUTH>
<FROM><DN>Chris Davies</DN> <EA>CDavies@ourcompany.com</EA>
</FROM>
<PP><DN>Bill Stephens</DN>
<EA>BStephens@ourcompany.com</EA>
</PP>
</AUTH>
</MSG>
This example is not exhaustive. The sere property follows the same schema as
the menv property, except that the root node is <MSG> rather than <MSGENV>.
Version information
■ The sere property is available in Enterprise Vault 6.0 SP5, Enterprise Vault
7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1,
Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.
■ <AUTH> element of the menv property is available in Enterprise Vault 6.0
SP5, Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See
“Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault
■ Missing content reasons returned in the missing content property, comr, are
available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise
Vault 6.0 SP5” on page 31.
■ The event and task properties, csrt, cend, clon, tddt, tcdt and tsts are
available in Enterprise Vault 8.0 SP3 and later.
■ The shct property is not supported from Enterprise Vault 10.
Defined custom properties
Defined custom properties

The following list of custom properties are also defined in Enterprise Vault.
Table B-2 Defined custom properties
Description Name Type Search- Retriev- Notes

able able
For an item copied by Move Vault.CopiedFrom String See “Note 1”

Archive, provides the following If an archive has been
details: moved several times, there
will be a value for each
■ Time the item was copied move.
■ The source item archive
■ Saveset ID
If message is a journal message, Vault.JournalType String Currently defined values:

the type of journal message ■ E2007
■ E2003
■ E2007ClearText
E2007RMS
See “Note 2”
Message direction Vault.MsgDirection String 32-bit integer as a string.

Currently defined values:
0 - undefined
1 - internal
2 - external-in
3 - external-out
Type of the message. Vault.MsgType String Currently defined values:

■ EXCH
■ Bloomberg
■ IM.vendor
■ FAX.vendor
■ DXL
Note 1
Format is
<UTC_datetime_of_copy>,<source_archive_ID>,<source_item_Saveset_ID>
For example,
2009-11-17
13:37:01Z,16B3597E77206FB4690FB46573DA6D7081110000EVServer.domain.l
ocal,20081114
0000000~200811141011170000~Z~B082EF701FF8FB47509D5228C99D2B51
Defined custom FSA properties
Note 2
If the message is from Exchange Server 2010 with journal report decryption
enabled, then the message is in Exchange Server 2007 report format and
includes both an RMS-protected copy and a clear text copy of the message. Both
copies are stored in the saveset. The advanced setting in the Enterprise Vault
Exchange Journaling policy, ClearText copies of RMS Protected items,
determines whether Enterprise Vault uses the clear text copy or the
RMS-protected copy as the primary message during archiving. If the value of
Vault.JournalType is "E2007RMS", then the primary message is the
RMS-protected copy. A value of "E2007ClearText" indicates that the primary
message is the clear text copy.
See the Administrator’s Guide for more information on this policy setting.
Defined custom FSA properties

The following list of custom properties are defined in Enterprise Vault for FSA
items.
Table B-3 Defined custom FSA properties
Description Name Type Search- Retriev- Notes

able able
Original Name of file at the EVFSA.OriginalFileName String

point of archival
Indicator that item was EVFSADLMImport.DLM String Currently only

imported from DLM populated with
the string
"Imported"
Defined custom SharePoint properties

The following list of custom properties are defined in Enterprise Vault for
SharePoint items.
Table B-4 Defined custom SharePoint properties
Description Name Type Seach- Retriev- Notes

able able
Document title EVSP.Title String
SharePoint documentId EVSP.DocId String

Defined properties for Compliance Accelerator
Table B-4 Defined custom SharePoint properties
Description Name Type Seach- Retriev- Notes

able able
Document version EVSP.Version String
Check in comment EVSP.Comment String
Display name of document EVSP.Editor String

editor
Domain name (Windows EVSP.CreatedBy String

account name) of document
author
Domain name (Windows EVSP.ModifiedBy String

account name) of document
editor
SharePoint Site Id EVSP.SiteId String
SharePoint Site name EVSP.Site String
SharePoint Site Url EVSP.SiteUrl String
Customer configurable EVSPP.<Sharepoint String

properties - any SharePoint property name>
property

The following list of custom properties are defined in Enterprise Vault for items
processed by the Compliance Accelerator Journaling Connector.
Table B-5 Defined custom properties for Journaling Connector
Description Name Type Searchable Retrievable Multi- Notes

Valued
The set of CA KVSCA.DeptAuthor String CA Dept IDs

Department Ids
that the item's
author is a member
of
Table B-5 Defined custom properties for Journaling Connector
Description Name Type Searchable Retrievable Multi- Notes

Valued
The set of CA KVSCA.DeptRecips String CA Dept IDs

Department Ids
that the item's
recipients are
members of
The union of KVSCA.Department String CA Dept IDs

KVSCA.DeptAuthor
and
KVSCA.DeptRecips
Policies, defined in evtag.category String Policy names

the policy
management
software, which do
not affect capture
either way; they
only categorize
emails.
Policies, defined in evtag.exclusion String Policy names

the policy
management
software, which
either preclude
capture or advocate
non-capture.
Policies, defined in evtag.inclusion String Policy names

the policy
management
software, which
either demand or
suggest capture.
The policy action is Vault.PolicyAction String Defined values are:

the overall action ■ NOACTION
■ EXCLUDE
that should be
■ INCLUDE
taken on an item;
the sum result of all
the applied policies.
Appendix C
API return values
This appendix lists the Enterprise Vault API return values.
Content Management API return values

Table C-1 Content Management API return values
Return value Value Description
CONTENTMANAGEMENTAPI_E_UNAVAILABLE 0x80040300 Enterpise Vault is not running
CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL 0x80040301 Time to create a new archive
CONTENTMANAGEMENTAPI_E_BUSY 0x80040302 Enterprise Vault is

temporarily unable to process
the request. The server is
busy, or has insufficient
resources, or is only able to
read data due to ongoing
backups. Wait and retry later.
CONTENTMANAGEMENTAPI_E_NO_ACCESS 0x80040303 Caller has insufficient

permissions to access the
vault store, archive, or item,
or archive is in a read-only
state.
CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 0x80040304 Problem with input

parameters
CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER 0x80040305 An input parameter identifies

more than one object
CONTENTMANAGEMENTAPI_E_INTERNAL_FAILURE 0x80040306 An internal failure occurred

686 API return values
Retention API return values
Table C-1 Content Management API return values
CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND 0x80040307 Item not found
CONTENTMANAGEMENTAPI_E_NOT_FOUND 0x80040308 Archive, Vault Store or

Retention Category does not
exist
CONTENTMANAGEMENTAPI_E_DELETION_BARRED 0x80040309 Deletion of the item is not

permitted
CONTENTMANAGEMENTAPI_E_NO_LICENSE 0x8004020A API is not correctly licensed
CONTENTMANAGEMENTAPI_E_LICENSE_EXPIRED 0x8004030B API license has expired
CONTENTMANAGEMENTAPI_E_INVALID_DEVICE 0x8004030C Not a compliance device
CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID 0x8004030D Attempting to

insert/copy/move item with
an Item Id that is not unique
in the target vault store.
CONTENTMANAGEMENTAPI_E_NOT_SUPPORTED 0x8004030E The operation is not

supported.
Retention API return values

The following return values are defined for the Retention API:
Table C-2 Retention API return values
RetentionCategoryAlreadyExists 0x800700b7 Returned when attempting to add a retention

category, and one already exists with the same
name.
RetentionCategoryNotExist 0x80070002 Returned when attempting to update a retention

category, and the RetentionCategoryId does not
exist in the Enterprise Vault directory.
SiteIdNotFound 0x800704BA Returned if the site specified by

DirectoryDNSAlias does not exist.
API return values 687
Search API return values
Search API return values

The following return values are defined for the Search API:
Table C-3 Search API return values
rvS_OK 0x00000000 Successful completion
rvS_FALSE 0x00000001 Sucessful - but the input data or output

data is empty
rvE_POINTER 0x80004003 An invalid or NULL pointer argument
rvE_INVALIDARG 0x80070057 Invalid argument
rvE_ACCESSDENIED 0x80070005 Caller has insufficient permissions to

access an index
rvE_NOINTERFACE 0x80004002 Interface is not support or not valid
rvE_SERVER_UNAVAILABLE 0x800706BA The index server is not currently available
rvINDEXING_W_ARCHIVE_NOT_SET 0x80041C6B An archive has not been selected
rvINDEXING_W_CANT_ACCESS_DIRECTORY 0x80041C11 The Enterprise Vault Directory is not

available
rvINDEXING_E_ARCHIVE_NOT_FOUND 0xc0041C5C The archive does not exist
rvINDEXING_W_INDEXDISABLED 0x80041C84 The archive's index is current disabled
rvINDEXING_W_ARCHIVE_BEING_DELETED 0x80041C52 The archive is marked for deletion
rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET 0x80041C6C The index volume set identity does not

belong to the currently selected archive
rvINDEXING_W_UNKNOWN_INDEX_VOLUME 0x80041C6D The index volume identity does not belong

to the currently selected archive
rvINDEXING_W_UNABLE_FAILED_VOLUME 0x80041C69 The search failed due to at least one index

volume being marked as failed
rvINDEXING_W_UNABLE_OFFLINE_VOLUME 0x80041C6A The search failed due to at least one index

volume being marked as offline
rvINDEXING_E_TOO_MANY_RESULTS 0xc0041C83 The search request was rejected because

too many search results were requested.
The maximum is defined by the
MaxSearchResultsPerVolumeSet
property.
External Filter API Event log messages
Table C-3 Search API return values
rvINDEXING_E_TOO_MANY_VOLUMES 0xc0041C82 The search request was rejected because

there are too many index volumes to
search. The maximum is defined by the
MaxSearchIndexVolumeSets property.
rvINDEXING_W_SERVICE_BUSY 0x80041C86 The search was rejected because the

indexing service is too busy
rvINDEXING_W_SERVER_STOPPING 0x80041C1A The search was rejected because the index

is being unloaded to allow another index
to be searched
rvINDEXING_W_SERVICE_STOPPING 0x80041C47 The search was rejected because the index

service is being shutdown
rvINDEXING_W_SEARCH_WOULD_BLOCK 0x80041C70 The search was rejected because the index

is currently overloaded with search
requests
rvINDEXING_W_SEARCH_TIMEDOUT 0x80041C71 The search failed because it took too long

to complete. The timeout is defined by the
Timeout property.
rvINDEXING_E_INVALID_QUERY 0xC0041C53 The search was rejected since the search

query was invalid.
rvINDEXING_E_ILLEGAL_WILDCARD_QUERY 0xC0041C5E The search was rejected since the search

query contained invalid wildcard terms.
rvINDEXING_E_FAILED_SEARCH_REQUEST 0xC0041C67 The search failed due to an internal error.

Check the Enterprise Vault event log on
the Enterprise Vault server.
rvINDEXING_E_INDEX_SEARCH_FAILED 0xC0041C0E The search failed due to a failure to search

one or more of the targeted index volumes
sets.

The following events are written to the Enterprise Vault event log by the Task
Filter Controller.
API return values 689
Exchange Server filtering

The following messages are written to the Enterprise Vault event log by the
Exchange Task Filter Controller.
Event Type Description Example
3144 Error Logged by the filter controller Failed whilst initializing the Filter Controller. The
if one or more of the registered agent will now shut down as it cannot reliably
external filters fails to load, or continue.
fails to initialize.
Error: <error information>
3263 Error Logged by the filter controller An error occurred processing the external filter
when an external filter returns '<filter prog id>'. No more filters will be processed.
an error when processing a Error: <error information>
message. (The filter’s
Mailbox: <mailbox DN>
ProcessFilter method returns a
Message Folder: <folder name>
non-zero return value). The Message Title: <message title>
filter controller stops
processing the message.
3146 Error Logged by the filter controller Failed to initialize the external filter with ProgId
when attempting to create an '<filter prog id>'. Either the ProgId is incorrect or
instance of an external filter. the DLL has not been registered.
Please check the ProgId or register the DLL for the
external filter.
3147 Error Logged by the filter controller An error has occurred initializing the external filter
when an external filter returns '<filter prog id>'.
an error when initializing. (The
Error: <error information>
filter’s Initialize method
returns a non-zero return
value).
3150 Error Logged by the filter controller Whilst processing external filters too many
when a stream of consecutive consecutive errors have occurred. This Task will
errors are encountered. now shut down.
45329 Informational Logged by the filter controller External Filter '<filter prog id>' initializing...
at the point of initializing each
external filter.
45330 Informational Logged by the filter controller External Filter '<filter prog id>' stopped.
at the point of stopping each
external filter.
Domino Server filtering

The following messages are written to the Enterprise Vault event log by the
Domino Journaling Task Filter Controller.
Event Type Description Example
41086 Informational Logged by the filter controller The Domino external filter ‘<filter_name>’ has
at the point of initializing each started.
installed filter plug-in.
41087 Informational Logged by the filter controller The Domino external filter ‘<filter_name>’ has
at the point of de-initializing stopped.
each installed filter plug-in.
41088 Error Logged by the filter controller The Domino external filter '<filter_name>' failed to
if a filter plug-in raises an error process an item.
during processing. The reason
Reason: An applicable RuleSet has not been defined
for the error is contained in the for database 'symantec\db_name.nsf' and a default
message text.
Content Category has not been specified.
41036 Error Logged by the filter controller Unable to start the FilterController The following
if a filter plug-in raises an error error occurred:
during initialization. The
Unable to initialize() filter '<filter_name>'.
reason for the error is
contained in the message text. Reason: ...
Index
A Indexing items 517

Indexing levels 517
AddProperty method
IndexSearch2 object
ISearchQuery interface methods
Search API
SearchQuery object 552
SelectArchive method 588
AddQuery method
interface methods
AddProperty
AddQuery
C SearchQuery object 558
compressing items 517 SelectArchive
constants IndexSearch2 object 588
ESearchQueryFlags constant SetProperty
Search API 533 SearchQuery object 550
Converting items 517 ISearchQuery interface methods
Custom Filtering API AddProperty method 552
get_defaultRetentionCategoryId methods AddQuery method 558
IArchivingControl interface 445 SetProperty method 550
ProcessFilter method items
IExternalFilter interface 437 compressing 517
converting 517
E
Enterprise Vault documentation 15 M
ESearchQueryFlags constant methods
Search API 533 SelectArchive
IndexSearch2 object 588
F
flags P
ESearchQueryFlags constant ProcessFilter method
Search API 533 IExternalFilter interface
Custom Filtering API 437
G
get_defaultRetentionCategoryId methods S
IArchivingControl interface Search API
Custom Filtering API 445 ESearchQueryFlags constant 533
searches
overview of performing a search 524
I results, processing 527
Indexes SearchQuery object
updating 517 SearchQuery interface methods
692 Index
AddProperty 552
AddQuery 558
SetProperty 550
SelectArchive method
IndexSearch2 object
Search API 588
SetProperty method

Symantec Enterprise Vault: Application Programmer's Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Symantec Enterprise Vault: Application Programmer's Guide

Uploaded by

Copyright:

Available Formats

Symantec Enterprise Vault™

Application Programmer’s Guide

Enterprise Vault 9.0 SP1

Last updated: November 19, 2010.

THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED

The Licensed Software and Documentation are deemed to be commercial computer

Technical Support .................................................................................................. 3

Chapter 1 About this guide

Chapter 2 API updates

Chapter 3 Enterprise Vault

Chapter 4 Content Management API

General guidelines for using the API ................................................................ 52

IArchive :: ItemCount ........................................................................................144

IContent :: Author .............................................................................................. 235

IHolds :: Count ....................................................................................................318

Chapter 5 NSF Manager API

INSFManager :: CloseNSF ................................................................................. 379

Chapter 6 Retention API

Chapter 7 Filtering APIs

IArchivingControl :: currentVaultId ...............................................................443

ILotusArchivingControl :: Action .................................................................... 491

Chapter 8 Search API

IIndexSearch2 :: IndexVolumeSets .................................................................568

ISearchResults :: Total ...................................................................................... 632

Appendix A About Enterprise Vault indexes

Appendix B Enterprise Vault Properties

Appendix C API return values

Introducing this guide

Enterprise Vault documentation

Comment on the documentation

Notice of future changes

Enterprise Vault Properties

Enterprise Vault 9.0

Content Management API

Ref Change details

MSXML 6.0 or later is now required on the computer where you

900-1652 Guidance on thread priority has been added.

900-2677 Added the method IItem3::Undelete.

Enterprise Vault 8.0 SP5

Content Management API

Ref Change details

E2133959 ISimpleIndexProperty :: Value now has a fuller description of possible values

Ref Change details

8054561, HARD_DELETE is now available as an option in the Domino action

E2095734 The remarks in the section, IArchivingControl2 :: MAPISaveChanges, now

Enterprise Vault properties

Ref Change details

E2027779 Added the property, Vault.CopiedFrom, to the list of custom properties

Ref Change details

Enterprise Vault 8.0 SP4

Content Management API

Ref Change details

E1669297 The description of the EV_STG_API_ITEM_DETAIL enumeration has been

Ref Change details

Ref Change details

Enterprise Vault 8.0 SP3

Content Management API

Ref Change details

Ref Change details

803125, Sometimes files of between 5 MB and 50 MB were truncated when retrieved

Ref Change details

Enterprise Vault 8.0 SP2

Content Management API