EV10 API Reference

Symantec Enterprise Vault
Application Programmer's Guide
10.0
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: 2012-02-27.
Legal Notice
Copyright 2012 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 .................................................................. 19

Introducing this guide ................................................................... 19
Enterprise Vault documentation ..................................................... 19
Comment on the documentation ..................................................... 19
Chapter 2
API updates
.......................................................................... 21
About API updates .......................................................................

Enterprise Vault 10.0.1 .................................................................
Enterprise Vault 10.0 ....................................................................
Enterprise Vault 9.0 SP3 ................................................................
Enterprise Vault 9.0 ......................................................................
Minimum supported OS version ................................................
Changes to programming language support ................................
General changes ....................................................................
NSF Manager API added ..........................................................
Content Management API ........................................................
Retention API ........................................................................
Migration API ........................................................................
New index properties added .....................................................
Corrections ...........................................................................
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise
Vault 6.0 SP5 .........................................................................
Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault
6.0 SP4 .................................................................................
22
22
23
26
26
27
29
30
32
32
34
34
34
34
34
35
38
38
38
39
39
40
42
45
Contents
Chapter 3
Enterprise Vault API overview .......................................... 47

About API overview ......................................................................
Overview of Enterprise Vault APIs ..................................................
Prerequisite software and settings ..................................................
Permissions ..........................................................................
Licensing ....................................................................................
Development licensing ............................................................
Production licensing ...............................................................
Deploying an application that uses the API .......................................
Enterprise Vault API runtime MSI .............................................
Checking the API runtime version and the installation path ...........
Deploying .NET applications ....................................................
Installing the Enterprise Vault SDK .................................................
Checking the SDK version and installation path ...........................
SDK examples .......................................................................
Programming notes ......................................................................
Using the Enterprise Vault APIs in C++ ......................................
Using Enterprise Vault APIs in .NET managed languages ..............
Using Enterprise Vault APIs in Visual Basic Script .......................
Code samples ........................................................................
Chapter 4
47
47
49
49
50
50
50
51
51
51
53
54
55
55
56
56
56
57
57
Content Management API ................................................. 59

About the Content Management API ................................................
Architecture of Content Management API ..................................
General guidelines for using the API ................................................
Use of objects ........................................................................
Enumerating vault stores, archives and items .............................
Saveset IDs and Transaction IDs ...............................................
Property validation ................................................................
How Enterprise Vault processes message items ...........................
Adding custom index metadata .................................................
Audit logging ........................................................................
Diagnostic logging and tracing .................................................
Enumerations ..............................................................................
EV_API_DELETION_LEVEL enumeration ....................................
EV_API_EVENT_TYPE enumeration ..........................................
EV_API_ITEMS_ORDERBY enumeration ....................................
EV_API_TRACE_LEVEL enumeration .........................................
EV_STG_API_ARCHIVE_TYPE enumeration ................................
EV_STG_API_AUTHENTICATE_USING enumeration ....................
EV_STG_API_CAN_DELETE enumeration ...................................
EV_STG_API_CONVERTED_CONTENT enumeration ....................
65
66
69
69
70
71
71
72
72
74
75
75
75
76
76
76
77
77
78
79
Contents
EV_STG_API_CP_SETBY enumeration ....................................... 79

EV_STG_API_CP_UNITS enumeration ....................................... 80
EV_STG_API_DELETION_REASON enumeration ......................... 80
EV_STG_API_EXPIRE_ITEMS enumeration ................................. 81
EV_STG_API_INDEX_LEVEL enumeration .................................. 81
EV_STG_API_INDEX_URGENCY enumeration ............................. 82
EV_STG_API_ITEM_COPYOPTIONS enumeration ........................ 82
EV_STG_API_ITEM_DETAIL enumeration .................................. 83
EV_STG_API_PERMISSIONS_TYPE enumeration ......................... 85
EV_STG_API_STATUS enumeration .......................................... 86
ContentManagementAPI object ...................................................... 87
IContentManagementAPI :: Archive ................................................. 91
IContentManagementAPI :: Item ..................................................... 93
IContentManagementAPI :: Holds ................................................... 94
IContentManagementAPI :: Hold ..................................................... 96
IContentManagementAPI :: DirectoryDNSAlias ................................. 97
IContentManagementAPI :: AuthenticationMode ............................... 99
IContentManagementAPI2 :: VaultStores ........................................ 100
IContentManagementAPI2 :: VaultStore ......................................... 101
IContentManagementAPI2 :: Archives ............................................ 103
IContentManagementAPI3 :: Items ................................................ 103
IContentManagementAPI3 :: IDispatchQueryInterface ...................... 104
IContentManagementAPI4 :: LastError ........................................... 106
VaultStores object ...................................................................... 107
IVaultStores :: Computer .............................................................. 109
VaultStore object ........................................................................ 110
IVaultStore :: Id .......................................................................... 112
IVaultStore :: Name ..................................................................... 113
IVaultStore :: Description ............................................................. 114
IVaultStore :: Status .................................................................... 115
IVaultStore :: ArchiveCount .......................................................... 116
IVaultStore :: DirectoryDNSAlias ................................................... 117
IVaultStore :: Get ........................................................................ 118
Archives object .......................................................................... 119
IArchives :: Computer .................................................................. 122
IArchives :: VaultStoreId .............................................................. 123
IArchives :: ArchiveName ............................................................. 124
IArchives :: Permissions ............................................................... 126
IArchives :: ArchiveTypes ............................................................ 127
Archive object ............................................................................ 128
IArchive :: VaultStoreId ............................................................... 131
IArchive :: Id .............................................................................. 132
IArchive :: Name ......................................................................... 133
Contents
IArchive :: Description .................................................................

IArchive :: ExpireItems ................................................................
IArchive :: ConvertedContent ........................................................
IArchive :: IndexUrgency .............................................................
IArchive :: IndexLevel ..................................................................
IArchive :: Size ...........................................................................
IArchive :: SecurityDescriptor .......................................................
IArchive :: ComplianceDevice ........................................................
IArchive :: ItemCount ..................................................................
IArchive :: Create ........................................................................
IArchive :: Get ............................................................................
IArchive2 :: Type ........................................................................
IArchive2 :: Status ......................................................................
IArchive2 :: HasFolders ................................................................
IArchive2 :: Full ..........................................................................
IArchive2 :: DirectoryDNSAlias .....................................................
IArchive3 :: SecurityDescriptor .....................................................
IArchive3 :: SecurityDescriptorString .............................................
IArchive3 :: Type ........................................................................
Items object ...............................................................................
IItems :: ArchiveId ......................................................................
IItems :: StartSequenceNum .........................................................
IItems :: OrderBy ........................................................................
Item object ................................................................................
IItem :: ArchiveId .......................................................................
IItem :: Id ..................................................................................
IItem :: Content ..........................................................................
IItem :: ArchiveMetaData .............................................................
IItem :: BrowserViewURL .............................................................
IItem :: DefaultMSGFormat ..........................................................
IItem :: Holds .............................................................................
IItem :: NativeItemURL ................................................................
IItem :: DeletionLevel ..................................................................
IItem :: CopyOptions ...................................................................
IItem :: Insert .............................................................................
IItem :: Get ................................................................................
IItem :: Delete ............................................................................
IItem :: CanBeDeleted ..................................................................
IItem :: CopyTo ..........................................................................
IItem :: MoveTo ..........................................................................
IItem2 :: DeletionReason ..............................................................
IItem3 :: Undelete .......................................................................
Content object ...........................................................................
134
136
138
140
142
143
145
147
148
149
152
153
154
155
156
157
157
159
162
164
168
169
170
172
174
175
177
178
179
181
183
184
185
187
191
194
198
200
201
205
208
210
212
Contents
IContent :: Title ..........................................................................

IContent :: OriginalLocation .........................................................
IContent :: FileExtension ..............................................................
IContent :: MIMEFormat ..............................................................
IContent :: CreatedDate ................................................................
IContent :: ModifiedDate ..............................................................
IContent :: Data ..........................................................................
IContent :: OriginalSize ................................................................
IContent :: Author .......................................................................
ArchiveMetaData object ..............................................................
IArchiveMetaData :: RetentionCategory ..........................................
IArchiveMetaData :: ComplianceDevice ..........................................
IArchiveMetaData :: OverrideOnHoldRetCat ....................................
IArchiveMetaData :: ArchivedDate .................................................
IArchiveMetaData :: ComplianceData .............................................
IArchiveMetaData :: SavesetSize ...................................................
IArchiveMetaData :: RetentionExpires ............................................
IArchiveMetaData :: IndexData .....................................................
IArchiveMetaData :: IsItemSecured ................................................
IIArchiveMetaData :: CustomIdentifier ...........................................
IIArchiveMetaData :: CustomQualifier ............................................
IIArchiveMetaData :: CustomProperties ..........................................
IArchiveMetaData :: Update .........................................................
IArchiveMetaData2 :: CurrentLocation ...........................................
IArchiveMetaData2 :: CurrentFolderId ............................................
IArchiveMetaData2 :: SequenceNum ..............................................
IArchiveMetaData2 :: ArchivedDate ...............................................
SimpleIndexMetadata object ........................................................
ISimpleIndexMetadata :: _NewEnum ..............................................
ISimpleIndexMetadata :: DateTimesUTC .........................................
ISimpleIndexMetadata :: Count .....................................................
ISimpleIndexMetadata :: Add ........................................................
ISimpleIndexMetadata :: Clear ......................................................
ISimpleIndexMetadata :: ToXML ...................................................
ISimpleIndexMetadata :: FromXML ................................................
ISimpleIndexMetadata :: ToLocalTime ............................................
ISimpleIndexMetadata :: ToUTCTime .............................................
SimpleIndexProperty object .........................................................
ISimpleIndexProperty :: Set ..........................................................
ISimpleIndexProperty :: Name ......................................................
ISimpleIndexProperty :: Value ......................................................
ISimpleIndexProperty :: Searchable ...............................................
ISimpleIndexProperty :: Retrievable ...............................................
214
214
215
217
218
219
220
222
223
225
228
229
230
232
233
234
235
236
237
239
240
242
243
245
251
253
255
256
259
260
261
262
265
265
267
268
269
269
270
272
275
277
278
10
Contents
ISimpleIndexProperty :: System ....................................................

ComplianceData object ................................................................
IComplianceData :: Units .............................................................
IComplianceData :: Value .............................................................
IComplianceData :: SetBy .............................................................
Holds object ..............................................................................
IHolds :: _NewEnum ....................................................................
IHolds :: Item .............................................................................
IHolds :: Count ...........................................................................
IHolds :: GroupId ........................................................................
IHolds :: ConsumerGUID ..............................................................
IHolds :: Metadata .......................................................................
IHolds :: Add ..............................................................................
IHolds :: PlaceHolds ....................................................................
IHolds :: ReleaseHolds .................................................................
IHolds2 :: ReleaseHolds2 ..............................................................
Hold object ................................................................................
IHold :: ArchiveId .......................................................................
IHold :: ItemId ............................................................................
IHold :: Id ..................................................................................
IHold :: Status ............................................................................
IHold :: Metadata ........................................................................
IHold :: ConsumerGUID ...............................................................
IHold :: GroupId .........................................................................
ICollectionBase : IDispatch ...........................................................
ICollectionBase :: Count ...............................................................
ICollectionBase :: _NewEnum ........................................................
ICollectionBase :: Item .................................................................
ICollectionBase :: Maximum .........................................................
ICollectionBase :: More ................................................................
ICollectionBase :: Get ...................................................................
ICollectionBase :: Clear ................................................................
ICollectionBase :: Reset ................................................................
ExtendedErrorInfo object .............................................................
IExtendedErrorInfo :: Error ..........................................................
IExtendedErrorInfo :: Description ..................................................
IExtendedErrorInfo :: InnerError ...................................................
IExtendedErrorInfo :: InnerErrorDescription ...................................
IExtendedErrorInfo :: Source ........................................................
DiagnosticsAPI object ..................................................................
IDiagnosticsAPI : Name ...............................................................
IDiagnosticsAPI : IsTraceEnabled ..................................................
IDiagnosticsAPI : LogEvent ..........................................................
279
281
282
283
284
285
287
288
289
290
292
293
294
295
296
298
300
301
302
304
305
306
306
307
308
309
310
311
312
313
314
315
315
316
320
320
321
322
322
323
324
325
325
Contents
IDiagnosticsAPI : Trace ............................................................... 326
Chapter 5
NSF Manager API ............................................................... 329

About NSF Manager API ..............................................................
NSF Manager API .......................................................................
Components ........................................................................
Security ..............................................................................
Enumerations ............................................................................
InitializeNotes enumeration ...................................................
NSFManager object .....................................................................
INSFManager :: OpenNSF .............................................................
INSFManager :: CreateNSF ...........................................................
INSFManager :: CloseNSF .............................................................
INSFManager :: ViewNote ............................................................
INSFManager :: ImportNote ..........................................................
INSFManager :: ExportNote ..........................................................
INSFManager :: DeleteNote ..........................................................
INSFManager :: InitializeNotes ......................................................
INSFManager :: TerminateNotes ...................................................
INSFManager :: SwitchToID ..........................................................
Chapter 6
Filtering APIs
329
330
331
331
332
332
332
333
334
335
336
337
338
339
340
341
342
...................................................................... 345
About the Filtering APIs ..............................................................

Exchange Filtering API ................................................................
Developing Exchange external filters .......................................
Exchange filtering registry settings .........................................
Enumerations (Exchange filtering) ................................................
EV_ACTION enumeration ......................................................
EV_ATTACHMENT_ACTION enumeration ................................
EV_RETRY_STATUS enumeration ...........................................
EV_REARCHIVE_STATUS enumeration ....................................
Message direction enumeration ..............................................
IExternalFilter interface ..............................................................
IExternalFilter :: Initialize ............................................................
IExternalFilter :: ProcessFilter ......................................................
IExternalFilter :: FilteringComplete ................................................
IArchivingControl interface for Exchange filtering ...........................
IArchivingControl :: currentVaultId ...............................................
IArchivingControl :: currentRetentionCategoryId .............................
IArchivingControl :: defaultRetentionCategoryId ..............................
IArchivingControl :: deleteOriginalItem ..........................................
IArchivingControl :: createShortcutToItem .....................................
348
350
352
352
356
356
356
357
357
358
358
359
359
360
360
365
365
366
367
367
11
12
Contents
IArchivingControl :: Action ..........................................................

IArchivingControl :: MAPISession ..................................................
IArchivingControl :: MAPIMessage ................................................
IArchivingControl :: AddIndexedProperty .......................................
IArchivingControl :: IndexedPropertiesSet ......................................
IArchivingControl :: AddIndexPropertyToSet ..................................
IArchivingControl :: AddIndexPropertySet ......................................
IArchivingControl :: TransactionID ................................................
IArchivingControl :: AgentType .....................................................
IArchivingControl :: AgentAssignedRetentionCategoryId ...................
IArchivingControl :: AgentAssignedVaultId .....................................
IArchivingControl :: GetFilterProperty ...........................................
IArchivingControl :: PutFilterProperty ...........................................
IArchivingControl :: AttachmentAction ..........................................
IArchivingControl :: RetryStatus ...................................................
IArchivingControl :: ReArchiveStatus .............................................
IArchivingControl2 :: BrowserViewURL ..........................................
IArchivingControl2 :: NativeItemURL .............................................
IArchivingControl2 :: MessageClass ...............................................
IArchivingControl2 :: MAPISaveChanges ........................................
IArchivingControl3 :: SenderRecipientXML .....................................
IArchivingControl3 :: EnvelopeSenderRecipientXML .........................
IArchivingControl3 :: MessageDirection ..........................................
IArchivingControl4 :: AddIndexedPropertyEx ..................................
Domino Filtering and File System Filtering APIs ..............................
About the Domino Filtering API ..............................................
About the File System Filtering API .........................................
Developing external filters .....................................................
Domino filtering registry settings ............................................
File System filtering registry settings .......................................
Enumerations (Domino filtering) ...................................................
Message direction enumeration ..............................................
Domino action enumeration ...................................................
Enumerations (File System Filtering) .............................................
File System Archiving action enumeration ................................
IExternalFilter interface ..............................................................
IExternalFilter :: Initialize ............................................................
IExternalFilter :: ProcessFilter ......................................................
IExternalFilter :: FilteringComplete ................................................
IExternalFilter :: Shutdown ..........................................................
IArchivingControl interface .........................................................
IArchivingControl :: OriginalVaultID ..............................................
IArchivingControl :: CurrentVaultID ..............................................
368
368
369
369
370
371
372
373
373
374
374
375
375
376
377
378
378
379
380
381
382
383
385
385
389
389
391
393
394
395
397
397
397
398
398
399
400
400
401
401
402
403
403
Contents
IArchivingControl :: OriginalRetentionCategoryID ............................

IArchivingControl :: CurrentRetentionCategoryID ............................
IArchivingControl :: IndexData .....................................................
IArchivingControl :: FilterProperties ..............................................
ILotusArchivingControl interface ..................................................
ILotusArchivingControl :: Action ...................................................
ILotusArchivingControl :: NoteHandle ............................................
ILotusArchivingControl :: DatabaseHandle ......................................
ILotusArchivingControl :: DatabaseName ........................................
ILotusArchivingControl :: SenderRecipientXML ...............................
ILotusArchivingControl :: StoreIdentifier ........................................
ILotusArchivingControl :: Direction ...............................................
IFileArchivingControl interface ....................................................
IFileArchivingControl :: Action .....................................................
IFileArchivingControl :: Name .......................................................
IFileArchivingControl :: Attributes ................................................
IFileArchivingControl :: CreationTimeUtc .......................................
IFileArchivingControl :: LastAccessTimeUtc ....................................
IFileArchivingControl :: LastWriteTimeUtc .....................................
IFileArchivingControl :: GetAccessControl ......................................
IFileArchivingControl :: SetAccessControl .......................................
IFileArchivingControl :: Length .....................................................
IFileArchivingControl :: Open .......................................................
IFileArchivingControl :: StreamNames ...........................................
IFileArchivingControl :: OpenStream .............................................
IFileArchivingControl :: DeleteStream ............................................
IFileArchivingControl :: ExtendedAttributes ....................................
IIndexMetadata interface .............................................................
IIndexMetadata :: ToXML .............................................................
IIndexMetadata :: FromXML .........................................................
IIndexMetadata :: Add .................................................................
IIndexMetadata :: Clear ................................................................
IIndexMetadata :: Count ...............................................................
IIndexMetadata :: DateTimesUTC ..................................................
IIndexProperty interface .............................................................
IIndexProperty :: Set ...................................................................
IIndexProperty :: Name ................................................................
IIndexProperty :: Value ................................................................
IIndexProperty :: Searchable .........................................................
IIndexProperty :: Retrievable ........................................................
IKeyedList interface ....................................................................
IKeyedList :: Insert ......................................................................
IKeyedList :: RemoveAt ................................................................
404
404
405
405
406
406
407
407
407
408
409
410
410
411
412
413
414
415
416
417
417
418
418
420
420
422
423
424
425
425
426
428
428
428
428
430
430
430
431
431
431
432
433
13
14
Contents
Chapter 7
Search API ........................................................................... 435

About Search API .......................................................................
About storing data in Enterprise Vault ...........................................
Introduction to Enterprise Vault indexing .......................................
Index Servers and Index Server groups .....................................
About index volumes .............................................................
About indexing options .........................................................
About index properties ..........................................................
Granularity of search results ..................................................
Using the Search API ..................................................................
Constructing a search query ...................................................
ESQfilter searches ................................................................
Special characters in search queries .........................................
Performing a search ..............................................................
Processing the search results ..................................................
Enterprise Vault index properties ............................................
Search API example ..............................................................
Constants and enumerations ........................................................
Index Property constants .......................................................
ESearchQueryFlags enumeration ............................................
ESearchQueryOperators enumeration ......................................
ESearchOperatorScope enumeration ........................................
EOptionsFlags enumeration ...................................................
EPropertySets enumeration ...................................................
ETruncationReason enumeration ............................................
EXMLResultsFormatOptions enumeration ................................
SearchQuery object .....................................................................
ISearchQuery :: Query .................................................................
ISearchQuery :: Clear ..................................................................
ISearchQuery :: SetTerm ..............................................................
ISearchQuery :: AddTerm .............................................................
ISearchQuery :: SetRange .............................................................
ISearchQuery :: AddRange ............................................................
ISearchQuery :: SetProperty .........................................................
ISearchQuery :: AddProperty ........................................................
ISearchQuery :: AddOp ................................................................
ISearchQuery :: Combine ..............................................................
ISearchQuery :: AddQuery ............................................................
ISearchQuery2 :: SetPropertyRange ...............................................
ISearchQuery2 :: AddPropertyRange ..............................................
IndexSearch object .....................................................................
IIndexSearch2 :: IndexVolumeSets .................................................
438
438
439
439
441
442
443
443
445
446
448
449
449
452
453
453
457
457
458
459
459
460
460
461
461
462
464
465
466
468
470
472
474
476
478
479
481
482
484
485
489
Contents
IIndexSearch2 :: Options ..............................................................

IIndexSearch2 :: SortBy ...............................................................
IIndexSearch2 :: ResultsPropertySet ..............................................
IIndexSearch2 :: AdditionalResultsProperties ..................................
IIndexSearch2 :: Timeout .............................................................
IIndexSearch2 :: ArchiveEntryId ...................................................
IIndexSearch2 :: ArchiveName ......................................................
IIndexSearch2 :: HasFolders .........................................................
IIndexSearch2 :: IndexVolumeSetIdentity .......................................
IIndexSearch2 :: IndexVolumeIdentity ............................................
IIndexSearch2 :: IndexVolumeSetCount ..........................................
IIndexSearch2 :: MaxSearchIndexVolumeSets ..................................
IIndexSearch2 :: MaxSearchResultsPerVolumeSet ............................
IIndexSearch2 :: SelectArchive ......................................................
IIndexSearch2 :: ListIndexVolumeSets ............................................
IIndexSearch2 :: SelectIndexVolumeSet ..........................................
IIndexSearch2 :: SelectIndexVolume ..............................................
IIndexSearch2 :: Search ...............................................................
IIndexSearch2 :: SearchToXML .....................................................
IIndexSearch2 :: AddAdditionalResultsProperty ...............................
IIndexSearch2 :: AddAdditionalResultsCustomProperty ....................
IIndexSearch2 :: Reset .................................................................
IndexVolumeSets object ..............................................................
IIndexVolumeSets :: ArchiveEntryId ..............................................
IIndexVolumeSets :: ArchiveName .................................................
IIndexVolumeSets :: HasFolders ....................................................
IIndexVolumeSets :: Count ...........................................................
IIndexVolumeSets :: _NewEnum ....................................................
IIndexVolumeSets :: Item .............................................................
IndexVolumeSet object ................................................................
IIndexVolumeSet :: Identity ..........................................................
IIndexVolumeSet :: ArchiveEntryID ...............................................
IIndexVolumeSet :: ArchiveName ..................................................
IIndexVolumeSet :: FirstItemIndexSequenceNumber ........................
IIndexVolumeSet :: OldestArchivedDate .........................................
IIndexVolumeSet :: YoungestArchivedDate .....................................
IIndexVolumeSet :: OldestItemDate ...............................................
IIndexVolumeSet :: YoungestItemDate ...........................................
IIndexVolumeSet :: DateTimesUTC ................................................
SearchResults object ...................................................................
ISearchResults :: Results ..............................................................
ISearchResults :: Count ................................................................
ISearchResults :: Total .................................................................
490
491
493
494
495
497
497
498
499
500
501
502
504
505
506
508
510
511
514
517
518
519
519
521
522
522
523
524
525
527
528
529
530
531
531
532
533
534
534
536
538
539
540
15
16
Contents
ISearchResults :: Start .................................................................

ISearchResults :: Options .............................................................
ISearchResults :: SortBy ...............................................................
ISearchResults :: _NewEnum ........................................................
ISearchResults :: Item ..................................................................
ISearchResults2 :: InSync .............................................................
ISearchResults2 :: TruncationReason .............................................
ISearchResults2 :: DateTimesUTC ..................................................
ISearchResults2 :: LoadResults ......................................................
SearchResult object ....................................................................
ISearchResult :: Result .................................................................
ISearchResult :: Number ..............................................................
ISearchResult :: Prop ...................................................................
ISearchResult :: Prop2 .................................................................
ISearchResult2 :: Count ...............................................................
ISearchResult2 :: Item .................................................................
ISearchResult2 :: DateTimesUTC ...................................................
Chapter 8
541
542
543
543
545
546
547
548
549
550
551
552
553
554
556
557
558
Retention API ...................................................................... 561

About Retention API ...................................................................
Retention API ............................................................................
Components ........................................................................
Security ..............................................................................
Enumerations ............................................................................
Retention Units enumeration .................................................
Retention Date Basis enumeration ...........................................
RetentionCategories object ...........................................................
IRetentionCategories :: Count .......................................................
IRetentionCategories :: _NewEnum ................................................
IRetentionCategories :: Item .........................................................
IRetentionCategories :: DirectoryDNSAlias ......................................
IRetentionCategories :: Lookup .....................................................
IRetentionCategories :: Create .......................................................
IRetentionCategories :: Add ..........................................................
IRetentionCategories :: Update ......................................................
IRetentionCategories2 :: Get .........................................................
RetentionCategory object .............................................................
IRetentionCategory :: Period .........................................................
IRetentionCategory :: Units ..........................................................
IRetentionCategory :: IsVisible ......................................................
IRetentionCategory :: Identifier .....................................................
IRetentionCategory :: Name ..........................................................
562
562
562
563
563
563
563
564
565
567
568
569
571
572
574
576
577
578
579
581
583
585
587
Contents
IRetentionCategory :: Description ..................................................

IRetentionCategory :: OnHold .......................................................
IRetentionCategory :: Locked ........................................................
IRetentionCategory2 :: ExpiryBasis ................................................
Appendix A
Enterprise Vault properties ............................................. 595

About Enterprise Vault properties .................................................
System properties ......................................................................
Note 1 ................................................................................
Note 2 ................................................................................
Note 3 ................................................................................
Note 4 ................................................................................
Note 5 ................................................................................
Note 6 ................................................................................
Version information .............................................................
Defined custom properties ...........................................................
Note 1 ................................................................................
Note 2 ................................................................................
Defined custom FSA properties .....................................................
Defined custom SharePoint properties ...........................................
Defined properties for Compliance Accelerator ................................
Appendix B
595
596
609
609
610
610
611
612
613
614
615
615
616
616
617
API return values ............................................................... 619

About API return values ..............................................................
Content Management API return values .........................................
Retention API return values .........................................................
Search API return values .............................................................
External Filter API Event log messages ...........................................
Exchange Server filtering ......................................................
Domino Server filtering .........................................................
File System filtering ..............................................................
Appendix C
588
589
591
593
619
619
620
621
623
623
624
625
Understanding how Enterprise Vault archives and

indexes messages ........................................................ 627
About storing and retrieving message items ....................................
Exchange (MAPI) messages ..........................................................
How the Enterprise Vault archiving agent processes Exchange
mailbox messages ...........................................................
How the Content Management API processes Exchange mailbox
messages ......................................................................
627
628
628
633
17
18
Contents
How the Enterprise Vault archiving agent processes Exchange

envelope journal messages ...............................................
How the Content Management API processes Exchange envelope
journal messages ............................................................
Lotus Notes messages ..................................................................
How the Enterprise Vault archiving agent processes Lotus Notes
mailbox messages ...........................................................
How the Content Management API processes Lotus Notes mailbox
messages ......................................................................
journal messages ............................................................
How the Content Management API processes Lotus Notes journal
messages ......................................................................
SMTP messages .........................................................................
How the Content Management API processes SMTP
messages ......................................................................
Copying message items ................................................................
Intra-site copying of archived items .........................................
Inter-site copying of archived items .........................................
Why a retrieved item is not a binary copy of the original item .............
640
640
641
641
645
646
647
648
648
650
650
651
652
Index ................................................................................................................... 653
Chapter
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.

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 presented?
20
About this guide

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
API updates
About API updates
Enterprise Vault 10.0.1
Enterprise Vault 10.0
Enterprise Vault 9.0 SP3
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0
SP5
Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4
22
API updates
About API updates
About 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.
Enterprise Vault 10.0.1

This section lists the changes and corrections in Enterprise Vault 10.0.1.
Table 2-1
Changes and corrections
Ref
Change details
E2595657
Note the following information about dates in Enterprise Vault index

properties.
The supported date range in index properties has changed. The
supported range is now 1 January 1970 to 1 January 2038. In previous
releases the supported range was 1 January 1970 to 31 December 2148.
In index search results, items that are indexed with date properties
earlier than 1 January 1970 are returned in the index search results,
but the retrieved date values defaults to 1 January 1970. Items that
are indexed with date properties later than 1 January 2038 are also
returned in the index search results, but the retrieved date values
defaults to 1 January 2038.
Tips and hints about adding custom index properties are provided in
the introduction to the Content Management API.
See Adding custom index metadata on page 72.
10788
Exchange Filtering API

The IArchivingControl interface of the Exchange Filtering API has
been extended to add a new method, IArchivingControl4 ::
AddIndexedPropertyEx. This method accepts a VARIANT data
structure when specifying string, integer and date custom index
property values. This enables searching on date-based selection
criteria.
Use AddIndexedPropertyEx to add custom index properties instead
of the methods, AddIndexedProperty, AddIndexPropertySet, and
AddIndexPropertyToSet.
See IArchivingControl interface for Exchange filtering on page 360.
API updates
Table 2-1
Changes and corrections (continued)
Ref
Change details
9912, E2478239
Content Management API

Filtering archives by permissions (IArchives :: Permissions) did not
return results unless archive types (IArchives::ArchiveTypes) were
also specified.
This has been fixed.
12266, E2603468

A memory leak occurred when IArchive::Get or IArchive::Create were
called. This has been fixed.

This section lists the changes and corrections in Enterprise Vault 10.0.
Note: Enterprise Vault 10.0 includes a new, 64-bit, indexing engine. To take
advantage of the new indexing engine, Enterprise Vault now runs on 64-bit systems
only. For more details of the indexing engine, see the Enterprise Vault 10.0
ReadMeFirst.
If you run Enterprise Vault client application scripts on a 64-bit operating system,
use the 32-bit version of command prompt, C:\Windows\SysWOW64\cmd.exe.
Table 2-2
Changes to Filtering APIs
Ref
Change details
100-2538,
100-5024,
100-5049,
100-5743,
100-5815,
100-6252,
CAS-6002
The File System Filtering API has been added to the Filtering APIs
chapter. This API enables you to create external custom filters for File
System Archiving tasks. The filters define how the archiving task
selects and processes files. Two example filters that use the File System
Filtering API are included in the SDK. The ReadMe file in the folder
InstallFolder\sdk\samples\FSA Filter Sample describes
the example filters and gives instructions on how to install and use
them.
See Domino Filtering and File System Filtering APIs on page 389.
23
24
API updates
Table 2-2
Changes to Filtering APIs (continued)
Ref
Change details
100-6002
Filters developed using the Domino Filtering and File System Filtering
APIs must reference the .NET assembly:
Symantec.EnterpriseVault.FilterInterfaces.dll
The API interfaces are loaded within the namespace:
Symantec.EnterpriseVault.FilterInterfaces
Note: If you have existing filters developed using the Domino Filtering
API, then you need to rebuild the filters after upgrading to Enterprise
Vault 10. References in the existing filters to the .NET assembly,
KVS.EnterpriseVault.LotusDominoInterfaces.dll, must be
redirected to the new .NET assembly,
Symantec.EnterpriseVault.FilterInterfaces.dll.
100-6100
Table 2-3
Ref
When entering the registry setting value for a file system or Domino
custom filter, the class name must include the namespace. The
separator used between the assembly and the class name must be "!".
Changes to Search API

Change details
Federated searches can be performed across 32-bit and 64-bit indexes
for customers upgrading from earlier releases.
The following search operators are no longer supported 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.
Indexing service now updates indexes every hour.
API updates
Table 2-3
Changes to Search API (continued)
Ref
Change details
100-8848
The default timeout value for search requests (IIndexSearch2 ::

Timeout) has been changed to 120 (seconds).
See IIndexSearch2 :: Timeout on page 495.
Table 2-4
Changes to Content Management API
Ref
Change details
E2082521
The Enterprise Vault system property, shct, is no longer supported.
100-5709
In the EV_STG_API_INDEX_LEVEL enumeration,

INDEX_LEVEL_MEDIUM value is not supported on Enterprise Vault
10.0 servers. If medium level indexing is requested on an Enterprise
Vault 10.0 server, then full indexing is implemented.
100-6261
If you used the IArchiveMetaData::CustomIdentifier and

IArchiveMetaData::CustomQualifier properties to identify an archived
item, the scope for identifying the item was the vault store. This could
result in ambiguity errors if the properties identified the item in
several different archives in the vault store. Enterprise Vault now
determines the ArchiveId, and includes this information when the
CustomIdentifier and CustomQualifier properties are used to identify
an item. In this way the scope for identifying the item is limited to the
archive.
100-7987
The sender and recipient indexing metadata and the Vault

MsgDirection and Vault.MsgType custom index properties that are
associated with SMTP messages (.eml files) and Digitally Signed MAPI
messages (.msg files, message class
"IPM.Note.SMIME.MultipartSigned") are now stored on item insert
operations. They are also preserved when performing copy or move
item operations using the Content Management API. In earlier releases
this functionality only applied to regular MAPI messages (.msg files,
message class "IPM.Note") that were ingested using the Content
Management API.
See Defined custom properties on page 614.
100-6424
When attempting to retrieve items from slow devices, Enterprise Vault

reported timeouts and a fatal internal error.
In such circumstances, Enterprise Vault now returns the temporary
error, CONTENTMANAGEMENTAPI_E_BUSY, so that the application
can retry the retrieval after a sleep period.
25
26
API updates
Table 2-4
Changes to Content Management API (continued)
Ref
Change details
100-6481
Error reporting has been improved for the situation where an archive
is created, but no index locations have been configured for the archive.
Use the ExtendedErrorInfo object to access detailed error information.
100-7796
A new ReadMe file is included with the Content Management API

example application (in the folder InstallFolder\samples\ECM
API Sample). The ReadMe provides a description of the application,
and gives instructions on how to install and use it.
Table 2-5
Documentation change
Ref
Change details
100-9330,
E2365577
A new appendix has been added to this manual. This appendix provides
information on the following topics:
How the Content Management API processes message items. In
particular, how Enterprise Vault processes sender and recipient
details for different message types, and key changes over recent
releases of Enterprise Vault.
Why a retrieved item is not a binary copy of the original item.
Using the Content Management API to migrate Enterprise Vault

archived messages from one Enterprise Vault installation to
another.
See About storing and retrieving message items on page 627.

This section lists the changes and corrections made for Enterprise Vault 9.0 SP3.
Table 2-6
Ref
Change details
903-11055
The default value for the enumeration EV_STG_API_CP_SETBY has

changed from SETBY_NOTSET to SETBY_RETCAT.
See EV_STG_API_CP_SETBY enumeration on page 79.

This section lists the changes and corrections made for Enterprise Vault 9.0.
API updates
Table 2-7
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 69.
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 210.
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 191.
See IContent :: FileExtension on page 215.
See IContent :: MIMEFormat on page 217.

Table 2-8
Ref
Change details
8053386,
E2030385
The property type for IArchive::Size was incorrectly shown as

ULONGLONG instead of VT_UI8. This has been corrected.
See IArchive :: Size on page 143.
27
28
API updates
Table 2-8
Ref
Change details
E2133959
ISimpleIndexProperty :: Value now has a fuller description of possible

values for the property.
See ISimpleIndexProperty :: Value on page 275.
Table 2-9
Changes to Filtering APIs
Ref
Change details
8054561,
E2096343
HARD_DELETE is now available as an option in the Domino action

enumeration.
See EV_ACTION enumeration on page 356.
E1980890
The following sections have been expanded to provide more

information on the filtering registry settings:
See Exchange filtering registry settings on page 352.
See Domino filtering registry settings on page 394.
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 381.
Table 2-10
Changes to 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 614.
API updates
Table 2-10
Changes to Enterprise Vault properties (continued)
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 596.

Table 2-11
Ref
Change details
E1927661
Updated IContent :: FileExtension section in the manual to clarify the

when a preceding period is included in file extensions.
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 83.
804-1613,
E1948433
When using the CopyTo function, the source item's Sender/Recipients

P1 data was not retained and merged with any specified custom index
properties for adding to the destination/copied item.
29
30
API updates
Table 2-11
Ref
Change details
8041728,
E1950563
If the converted content for an item or attachment is larger than 5MB,

then 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 194.
Table 2-12
Changes to Search API
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 449.

Table 2-13
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 208.
803137
Soft deleted items are no longer included when populating the Items
collection object.
See Items object on page 164.
API updates
Table 2-13
Ref

Change details
803069, E1630338 When using the Archive object to retrieve details for an archive that
was 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, E1737966 When populating very large Archives collection objects, the value of
the 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, E1726196, Sometimes files of between 5 MB and 50 MB were truncated when
E1739537
retrieved using the Content Management API .
31
32
API updates
Table 2-13
Ref

Change details
803327, E1792685 Retrieving large items (that is, files larger than 50 MB) resulted in
corrupt 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.

Table 2-14
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 316.
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 77.
802559, E1703228, IContent::Title no longer needs to be populated before calling Insert.

E1639951
802577, E1476982, IArchive::Name and IArchive::Description can contain printable,
E1600648
Unicode characters.
IArchive::Name is mandatory and cannot be blank or an empty string.
IArchive::Description is optional.
See IArchive :: Name on page 133.
See IArchive :: Description on page 134.

API updates
Table 2-15
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 82.
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 298.
8010204,
E1422959
If the source archive was in a read-only state, CopyTo failed and

returned the 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.
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.
33
34
API updates

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 74.
The name of the Enterprise Vault SDK kit has changed to Symantec Enterprise
Vault Software Development Kit.msi.
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.
API updates

Enterprise Vault 8.0 includes the following additions and changes to the Content
Management API documentation:
Table 2-16
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 104.
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 place of the DV_DS_E_PERMISSION enumerator when creating
the security descriptor for use with IArchive::SecurityDescriptor.
BAU2464
BAU0225
A new interface, IItems, has been added to facilitate the enumeration

of items in an archive.
See Enumerating vault stores, archives and items on page 70.
35
36
API updates
Table 2-16
Ref
Change details
BAU0778
Significant changes have been made to facilitate copying and

moving items from one archive to another :
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 IItem :: CopyOptions on page 187.
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 IArchiveMetaData2 :: CurrentLocation on page 245.
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.
BAU0795
BAU1179
API updates
Table 2-16
Ref
Change details
BAU1179
The following properties, which were previously hidden, have now

been 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 71.
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
BAU2013
BAU2853
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.
MSXML 3.0 is now the minimum version of MSXML required on
the computer where you install the application using the Content
Management API.
37
38
API updates
Retention API
Table 2-17
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-18
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-19
New index properties
Ref
Index property name
Description
BAU0585
crct
Current Retention Category Id,

searchable and retrievable
BAU0931
clcn
Current location, retrievable only
cllf
Current leaf folder name,

retrievable only
clfn
crcn
Current location folder names,

retrievable only
Current Retention Category name,
retrievable only
API updates
Table 2-19
New index properties (continued)
Ref
Index property name
Description
BAU1320
cnhv
Conversation Hierarchical View,

retrievable only
BAU1426
fpdd
Index Fingerprint of item,

fpcn
Index Fingerprint of content,

Corrections
Table 2-20
Corrections
Ref
Change details
1088101, 847952
The Storage service is no longer accessed when enumerating archives.
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.

Table 2-21
Corrections
Ref
Change details
E1107082
Updated description of IContent::FileExtension.

E1143215
Added description of the use of wildcard characters in ESQfilter

searches.
E1167957
Updated information about supported combinations of properties in

Archives object.
See Archives object on page 119.
39
40
API updates
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5
Table 2-21
Corrections (continued)
Ref
Change details
E1185396
Added IContentManagementAPI2 :: VaultStore.

See IContentManagementAPI2 :: VaultStore on page 101.
E1187820
Corrected description of ISimpleIndexMetadata :: Count.

See ISimpleIndexMetadata :: Count on page 261.
E1188342
Corrected description of IItem :: CanBeDeleted.

See IItem :: CanBeDeleted on page 200.
E1191078
Added example format for the consumer GUID in IHold ::

ConsumerGUID.
See IHold :: ConsumerGUID on page 306.
E1193018
Updated information about retrieving items, and added information

about retrieving hold data, in IItem :: Id.
See IItem :: Id on page 175.
E1196051
Updated description of ComplianceData object to note that it is for

use only with compliance devices, and updated Return values for
IArchiveMetaData :: Update.
See ComplianceData object on page 281.
See IArchiveMetaData :: Update on page 243.
E1203217
Updated Remarks section of IHolds :: Item to note that the index

supplied to the property is 1-based not 0-based.
See IHolds :: Item on page 288.
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.
API updates
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5
Table 2-22
Ref
Change details
751207, 703021,
605047
751208, 703020,
605036
751127, 703010
Availability
New sere index property. This Enterprise Vault 6.0 SP5,

property returns sender and Enterprise Vault 7.0 SP3,
recipient details from the
Enterprise Vault 2007 SP1
message header (P2) if the
archived item is a message.
See Table A-1 on page 596.
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.
New interface for Exchange
Enterprise Vault 6.0 SP5,
filtering, IArchvingControl3, Enterprise Vault 7.0 SP3,
to retrieve sender and
recipient information as XML.
See IArchivingControl
interface for Exchange
filtering on page 360.
SimpleIndexProperty object: Enterprise Vault 7.0 SP3,

Added new attachment
number ("anum") in the
returned 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 272.
menv index property: This
property now includes the
message sender/author and
delegate sender (if applicable)
encoded in the <AUTH>
element.
41
42
API updates
Table 2-22
Ref
Change details
751143, 703011
Availability
Previously, where an item's

content data was unobtainable, Enterprise Vault 2007 SP1
the cont index metadata
property 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.
703038, E1143932 IArchive::Create: updated

description of properties and
examples.
See IArchive :: Create
on page 149.

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.
API updates
Table 2-23
Ref
Change details
DOR610
DOR620
Availability
The following new Content

Enterprise Vault 2007
Management API 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.
Simple API removed from API Enterprise Vault 2007
Guide. Refer to 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.
43
44
API updates
Table 2-23
Ref
Change details
702045, 604133,
E974294
702045, 604133
Availability
When the enumerated value, Enterprise Vault 6.0 SP4,

DETAIL_LEVEL_ITEM_CONTENT, Enterprise Vault 7.0 SP2
was included as part of the
input parameter for the
method, IItem::Get(), the
current date and time was
returned by
IContent::ModifiedDate and
IContent::CreatedDate.
In previous releases, you could Enterprise Vault 6.0 SP4,

not retrieve expanded
distribution list information
from the 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_INDEXDATA 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 83.
The menv index property is
described.
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 272.
API updates

Table 2-24
Ref
Change details
CAP031
It is now possible to use the

transaction Id instead of the
saveset id when setting the
Item::Id property.
CAP433
An API license is no longer

required in order to develop
applications against the
Enterprise Vault APIs.
CAP463
In previous releases, if an item Enterprise Vault 7.0

had been marked "on hold"
using the retention category,
then it could not be deleted,
and hence could not be moved.
CAP545, CAP721,
E804597
IArchivingControl2 interface Enterprise Vault 7.0

added to Exchange Server
Filtering API.
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 Enterprise Vault 7.0

a new property:
AuthenticationMode, which
specifies the mode of
authentication to be used when
the calling application contacts
Enterprise Vault.
E775452
Availability
45
46
API updates
Chapter
Enterprise Vault API

overview
About API overview
Overview of Enterprise Vault APIs
Prerequisite software and settings
Licensing
Deploying an application that uses the API
Installing the Enterprise Vault SDK
Programming notes
About 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.

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 IContentManagementAPI and
IItem interfaces.
In general, applications which use the APIs should be run from a client computer,
and not on the Enterprise Vault server.
48
Enterprise Vault API overview

To help you choose the appropriate APIs for your application, Table 3-1 lists the
available APIs. Examples of possible applications are also given to provide
guidance:
Table 3-1
Enterprise Vault APIs
API
Description
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.

Table 3-1
API
Enterprise Vault APIs (continued)

Description
Exchange Filtering External filters enable preprocessing of items in order to decide on

API
the actions to take; for example, whether to archive the item and which
archive settings to apply.
Domino Filtering
The Filtering APIs provide the ability to:
API
File System
Filtering API
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.

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.
Enterprise Vault administration roles are described in the Enterprise Vault
Administrator's Guide.
49
50

Licensing
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:

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
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 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:


8.0 or later) for ingesting content into Enterprise Vault. This license also covers
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
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.
51
52

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 on page 54.
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
Using Visual Studio the required API COM libraries, for example
EVContentManagementAPI.dll, should be added to the application's References.
53
54

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:
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>
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 elsewhere.
See Checking version and installation path details prior to Enterprise Vault 8.0
on page 52.
SDK examples
The following examples are included in the SDK:
An example application for the Content Management API is installed in the

folder, InstallFolder\samples\ECM API Sample. This application provides
a UI that enables you to test out API functions such as creating an archive,
storing an item in an archive, retrieving items, and viewing properties on items
and archives. A ReadMe file in the folder provides instructions on how to install
and use the application.
Two example filters that use the File System Filtering API are installed in the
folder, InstallFolder\samples\FSA Filter Sample. A ReadMe file in the
folder provides instructions on how to install and use the filters.
Example filter 1 (SampleFilter.cs) configures different actions for the File

System Archiving task, depending on a variety of file properties. For
example, one action is to delete files with any of the extensions, mp3, avi,
or mpeg.
55
56

Programming notes
Example filter 2 (CustomProp.cs) configures the File System Archiving task

actions for Microsoft Office 2007 files that have custom properties added.
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.
When running scripts on a 64-bit operating system, use the 32-bit version of
command prompt, C:\Windows\SysWOW64\cmd.exe.
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 in .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 53.

Programming notes
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
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.
57
58

Programming notes
Chapter

About the Content Management API
General guidelines for using the API
Enumerations
ContentManagementAPI object
IContentManagementAPI :: Archive
IContentManagementAPI :: Item
IContentManagementAPI :: Holds
IContentManagementAPI :: Hold
IContentManagementAPI :: DirectoryDNSAlias
IContentManagementAPI :: AuthenticationMode
IContentManagementAPI2 :: VaultStores
IContentManagementAPI2 :: VaultStore
IContentManagementAPI2 :: Archives
IContentManagementAPI3 :: Items
IContentManagementAPI3 :: IDispatchQueryInterface
IContentManagementAPI4 :: LastError
VaultStores object
IVaultStores :: Computer
60
VaultStore object
IVaultStore :: Id
IVaultStore :: Name
IVaultStore :: Description
IVaultStore :: Status
IVaultStore :: ArchiveCount
IVaultStore :: DirectoryDNSAlias
IVaultStore :: Get
Archives object
IArchives :: Computer
IArchives :: VaultStoreId
IArchives :: ArchiveName
IArchives :: Permissions
IArchives :: ArchiveTypes
Archive object
IArchive :: VaultStoreId
IArchive :: Id
IArchive :: Name
IArchive :: Description
IArchive :: ExpireItems
IArchive :: ConvertedContent
IArchive :: IndexUrgency
IArchive :: IndexLevel
IArchive :: Size
IArchive :: SecurityDescriptor
IArchive :: ComplianceDevice
IArchive :: ItemCount
IArchive :: Create
IArchive :: Get
IArchive2 :: Type
IArchive2 :: Status
IArchive2 :: HasFolders
IArchive2 :: Full
IArchive2 :: DirectoryDNSAlias
IArchive3 :: SecurityDescriptor
IArchive3 :: SecurityDescriptorString
IArchive3 :: Type
Items object
IItems :: ArchiveId
IItems :: StartSequenceNum
IItems :: OrderBy
Item object
IItem :: ArchiveId
IItem :: Id
IItem :: Content
IItem :: ArchiveMetaData
IItem :: BrowserViewURL
IItem :: DefaultMSGFormat
IItem :: Holds
IItem :: NativeItemURL
IItem :: DeletionLevel
IItem :: CopyOptions
IItem :: Insert
IItem :: Get
61
62
IItem :: Delete
IItem :: CanBeDeleted
IItem :: CopyTo
IItem :: MoveTo
IItem2 :: DeletionReason
IItem3 :: Undelete
Content object
IContent :: Title
IContent :: OriginalLocation
IContent :: FileExtension
IContent :: MIMEFormat
IContent :: CreatedDate
IContent :: ModifiedDate
IContent :: Data
IContent :: OriginalSize
IContent :: Author
ArchiveMetaData object
IArchiveMetaData :: RetentionCategory
IArchiveMetaData :: ComplianceDevice
IArchiveMetaData :: OverrideOnHoldRetCat
IArchiveMetaData :: ArchivedDate
IArchiveMetaData :: ComplianceData
IArchiveMetaData :: SavesetSize
IArchiveMetaData :: RetentionExpires
IArchiveMetaData :: IsItemSecured
IIArchiveMetaData :: CustomIdentifier
IIArchiveMetaData :: CustomQualifier
IIArchiveMetaData :: CustomProperties
IArchiveMetaData :: Update
IArchiveMetaData2 :: CurrentLocation
IArchiveMetaData2 :: CurrentFolderId
IArchiveMetaData2 :: SequenceNum
IArchiveMetaData2 :: ArchivedDate
SimpleIndexMetadata object
ISimpleIndexMetadata :: _NewEnum
ISimpleIndexMetadata :: DateTimesUTC
ISimpleIndexMetadata :: Count
ISimpleIndexMetadata :: Add
ISimpleIndexMetadata :: Clear
ISimpleIndexMetadata :: ToXML
ISimpleIndexMetadata :: FromXML
ISimpleIndexMetadata :: ToLocalTime
ISimpleIndexMetadata :: ToUTCTime
SimpleIndexProperty object
ISimpleIndexProperty :: Set
ISimpleIndexProperty :: Value
ISimpleIndexProperty :: Searchable
ISimpleIndexProperty :: Retrievable
ISimpleIndexProperty :: System
ComplianceData object
IComplianceData :: Units
IComplianceData :: Value
63
64
IComplianceData :: SetBy
Holds object
IHolds :: _NewEnum
IHolds :: Item
IHolds :: Count
IHolds :: GroupId
IHolds :: ConsumerGUID
IHolds :: Metadata
IHolds :: Add
IHolds :: PlaceHolds
IHolds :: ReleaseHolds
IHolds2 :: ReleaseHolds2
Hold object
IHold :: ArchiveId
IHold :: ItemId
IHold :: Id
IHold :: Status
IHold :: Metadata
IHold :: ConsumerGUID
IHold :: GroupId
ICollectionBase : IDispatch
ICollectionBase :: Count
ICollectionBase :: _NewEnum
ICollectionBase :: Item
ICollectionBase :: Maximum
ICollectionBase :: More
ICollectionBase :: Get

ICollectionBase :: Clear
ICollectionBase :: Reset
ExtendedErrorInfo object
IExtendedErrorInfo :: Error
IExtendedErrorInfo :: Description
IExtendedErrorInfo :: InnerError
IExtendedErrorInfo :: InnerErrorDescription
IExtendedErrorInfo :: Source
DiagnosticsAPI object
IDiagnosticsAPI : Name
IDiagnosticsAPI : IsTraceEnabled
IDiagnosticsAPI : LogEvent
IDiagnosticsAPI : Trace

The Content Management API comprises the following interfaces:
IContentManagementAPI
IVaultStores
IVaultStore
IArchives
IArchive
IArchive2
IArchive3
IItems
IItem
65
66

IItem2
IItem3
IContent
IArchiveMetaData
IArchiveMetaData2
ISimpleIndexMetadata
IComplianceData
IHolds
IHold
IExtendedErrorInfo
IDiagnosticsAPI
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.

Figure 4-1
Hierarchy of Content Management API objects
<<object>>
ContentManagementAPI
<<object>>
<<object>>
<<object>>
<<object>>
VaultStores
Archives
Items
Holds
<<object>>
VaultStore
<<object>>
Archive
<<object>>
Item
<<object>>
ArchiveMetaData
<<object>>
ComplianceData
<<object>>
Hold
<<object>>
Content
<<object>>
SimpleIndexMetadata
<<object>>
ExtendedErrorInfo
<<object>>
DiagnosticsAPI
<<object>>
SimpleIndexProperty
All the objects shown are exposed by the Content Management API:
67
68

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 Archive object enables the creation of archives in an Enterprise Vault

vault store.
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 archived
item first). The Items object exposes a standard COM collection interface that
manages a collection of Item objects.
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 ContentManagementAPI object on page 87.
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.
69
70

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.
71
72

How Enterprise Vault processes message items

How Enterprise Vault processes message items is described later in an appendix
to this guide. The appendix includes information about how Enterprise Vault
processes sender and recipient details when archiving and retrieving messages,
and copying or moving archived messages. Details are given for the different
types of messages supported.
Adding custom index metadata

Applications can add custom index metadata to an item as it is archived. 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. When an archive is searched, the search is performed on the index
associated with the archive, not on the archive itself.
Note that custom index metadata properties cannot be added to attachments.
Figure 4-2 illustrates how custom index metadata is added to an item using the

Figure 4-2
Adding metadata to the index of an item
Third party
application
ContentManagementAPI
Enterprise
Vault Storage
Vault store
service
Insert()
+ metadata
Item
ID
ArchiveID
Content
ArchiveMetaData
IndexData
Enterprise
Vault Indexing
Index
service
SimpleIndexPropert
SimpleIndexPropert
y SimpleIndexPropert
y ySimpleIndexPropert
ySimpleIndexPropery
Enterprise Vault server
You can add custom index metadata to an item using the Content Management
API, or one of the Filtering APIs:
In the Content Management API, use the methods on the ISimpleIndexMetadata

interface.
See SimpleIndexMetadata object on page 256.
See IArchiveMetaData :: IndexData on page 236.
In the Exchange Filtering API, use the method IArchivingControl4 ::

AddIndexedPropertyEx. Custom filtering is available for Exchange Mailbox
Archiving Tasks, Exchange Public Folder Tasks and Exchange Journaling Tasks.
In the Domino Filtering API and File System Filtering API, use the Add method
in the IndexMetadata class.
See IArchivingControl interface on page 402.
73
74

To check that the metadata has been indexed, perform an archive search for the
custom information. If the custom index property is defined as searchable, you
can use the Other attribute fields in Enterprise Vault browser search to specify
the name and value of the custom index property. In the Name field, specify the
property set and name of the custom index property in the form
propertySet.propertyName. To see the Other attribute fields in browser search,
add ?advanced to the browser search URL. For example:
http://evserver/enterprisevault/search.asp?advanced
About number and date custom index properties

When adding dateTime index properties where the time element is significant,
specify the value of a dateTime index property using the ISO 8601 format. For
example, 2012-07-27T19:30:00+01:00. This avoids time zone ambiguities.
When searching using date search criteria, the date range values that can be
returned in search results are limited to the UTC date range 1st January 1970 to
1st January 2038. Items that are indexed with dateTime properties earlier than 1
Jan 1970 are returned in the index search results, but the retrieved date values
defaults to 1 Jan 1970. Items that are indexed with dateTime properties later than
1 Jan 2038 are also returned in the index search results, but the retrieved date
values defaults to 1 Jan 2038.
If you want to add a custom index date property that is retrievable only, then you
can specify a string index property instead of a dateTime index property. When
an index property is stored in the index as a string, no attempt is made to parse
the value as a date, and the string value is returned in search results without
alteration.
Note that adding a large number of custom index properties will increase the
index size, and can reduce search performance. In particular, searchable numbers
and dateTime index properties impact search performance more than string
properties.
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.

Enumerations
Table 4-1
Operations logged and the associated audit category
API operation
Enterprise Vault Audit Category
Insert
Archive
CopyTo
MoveTo
Archive
Delete1
Delete
Delete
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
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.
75
76

Enumerations
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 185.
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 325.
EV_API_ITEMS_ORDERBY enumeration
Items collection order defines whether to increase or decrease the index sequence
number when enumerating a collection of items.
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:

Enumerations
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 325.
See IDiagnosticsAPI : Trace on page 326.
EV_STG_API_ARCHIVE_TYPE enumeration
Archive type enumeration indicates the type of archive:
enum EV_STG_API_ARCHIVE_TYPE
{
ARCHIVE_TYPE_NOT_SET
ARCHIVE_TYPE_SHARED
ARCHIVE_TYPE_EXCHANGE_MAILBOX
ARCHIVE_TYPE_EXCHANGE_JOURNAL
ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER
ARCHIVE_TYPE_FILE_SYSTEM
ARCHIVE_TYPE_SHAREPOINT
ARCHIVE_TYPE_DOMINO_JOURNAL
ARCHIVE_TYPE_DOMINO_MAILBOX
};
=
=
=
=
=
=
=
=
=
0x00000000,
0x00000001,
0x00000002,
0x00000004,
0x00000008,
0x00000010,
0x00000020,
0x00000040,
0x00000080
The properties, IArchives::ArchiveTypes and IArchive3::Type, select archives

based on the type of archive specified by this enumeration.
See IArchives :: ArchiveTypes on page 127.
See IArchive3 :: Type on page 162.
EV_STG_API_AUTHENTICATE_USING enumeration
Storage authentication enumeration indicates the authentication mode to use
when authenticating to Enterprise Vault.
77
78

Enumerations
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 99.
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 200.

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 138.
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
(Default) The compliance retention period

is set by the associated Enterprise Vault
retention category.
See IArchiveMetaData :: ComplianceData on page 233.
79
80

Enumerations
See IComplianceData :: SetBy on page 284.
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 282.
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.

Enumerations
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.
DELETION_REASON_UNKNOWN
Indicates that the reason why the item was

deleted cannot be identified.
See IItem2 :: DeletionReason on page 208.
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 136.
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
81
82

Enumerations
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.
Note: INDEX_LEVEL_MEDIUM is only available on servers running Enterprise
Vault 9 or earlier. If INDEX_LEVEL_MEDIUM is requested on an Enterprise Vault
10.0 server, then INDEX_LEVEL_FULL is implemented.
See About indexing options on page 442.
FULL indexing is required for phrase searches of the content property
(IndexPropCONT).
The property, IArchive::IndexLevel, is used to determine the level of detail stored
in the archive's index.
See IArchive :: IndexLevel on page 142.
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.
See IArchive :: IndexUrgency on page 140.
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.

Enumerations
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
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.
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
83
84

Enumerations
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 212.
See Item object on page 172.
See ArchiveMetaData object
on page 225.
DETAIL_LEVEL_ITEM_CONTENT
IContent.Data
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

Enumerations
Table 4-2
Properties populated for EV_STG_API_ITEM_DETAIL

enumeration values (continued)
Enumeration value
Properties populated
DETAIL_LEVEL__HOLD_DATA
IItem.Holds
See Holds object on page 285.
DETAIL_LEVEL__CUSTOM_INDEX_METADATA
IArchiveMetadata.IndexData custom
index properties only. (System
properties are not included).
See Adding custom index metadata
on page 72.
DETAIL_LEVEL__SYSTEM_INDEXDATA
IArchiveMetadata.IndexData system
properties only, excluding the "menv"
and "sere" properties.
DETAIL_LEVEL__MESSAGE_ENVELOPE_INDEXDATA
IArchiveMetadata.IndexData "menv"
system property only.
DETAIL_LEVEL__SENDER_RECIPIENT_INDEXDATA
IArchiveMetadata.IndexData "sere"
system property only.

EV_STG_API_PERMISSIONS_TYPE enumeration
Archive permissions enumeration indicates archive permissions:
enum EV_STG_API_PERMISSIONS_TYPE
{
PERMISSIONS_UNSPECIFIED
= 0x00000000,
PERMISSIONS_SEARCH
= 0x00000080,
PERMISSIONS_READ
= 0x00000001,
PERMISSIONS_WRITE
= 0x00000002,
PERMISSIONS_DELETE
= 0x00000004,
PERMISSIONS_FOLDER_READ
= 0x00000008,
PERMISSIONS_FOLDER_WRITE = 0x00000010,
PERMISSIONS_FOLDER_DELETE = 0x00000020,
85
86

Enumerations
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 126.
See IArchive3 :: SecurityDescriptor on page 157.
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
};

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.
See IVaultStore :: Status on page 115.
See IArchive2 :: Status on page 154.
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:
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
interface
interface
interface
IContentManagementAPI : IDispatch
IContentManagementAPI2 : IContentManagementAPI
IContentManagementAPI3 : IContentManagementAPI2
IContentManagementAPI4 : IContentManagementAPI3
87
88

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

of an Item object.
Holds
Read only

of a Holds object.
Hold
Read only

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
Property
Read/Write
Description
VaultStores
Read only

of a VaultStores object.
VaultStore
Read only

of a VaultStore object.
Archives
Read only

of an Archives object.
Table 4-5
IContentManagementAPI3 property
Property
Read/Write
Description
Items
Read only

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
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.
See General guidelines for using the API on page 69.
Requirements
MSXML 6.0 or later is required on the computer where you install the Enterprise
Vault API runtime.
CLSID
E4BE20A4-9EF1-4B05-9117-AF43EAB4B295
89
90

Prog ID
EnterpriseVault.ContentManagementAPI
Type Library
EVContentManagementAPILib
DLL
EVContentManagementAPI.dll
.NET Primary
Interop Assembly
(PIA)
.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
}
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.
91
92

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.
[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;

93
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);
94

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
See ArchiveMetaData object on page 225.
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

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
95
96

See Hold object on page 300.
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

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
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);
97
98

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
\Wow6432Node
\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;
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
The EV_STG_API_AUTHENTICATE_USING enumerator defines the authentication
mode to use.
99
100

See EV_STG_API_AUTHENTICATE_USING enumeration on page 77.

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;
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.
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
See VaultStores object on page 107.
This property returns an empty instance of the VaultStore object, which can be
used to read the details of a vault store.
101
102

Syntax
HRESULT VaultStore([out, retval] IUnknown** pVal);
Parameters
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.
pVal is NULL
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
See VaultStore object on page 110.

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
An instance of an Archives object.
Return value
S_OK
Success.
pVal is NULL
Example
[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
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.
103
104

Syntax
HRESULT Items([out, retval] IUnknown** pVal);
Parameters
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.
pVal is NULL
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
This method enables calling applications written in Visual Basic Script to access
the properties of the following interfaces:

IArchive3
IArchiveMetaData2
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.
When running scripts on a 64-bit operating system, use the 32-bit version of
command prompt, C:\Windows\SysWOW64\cmd.exe.
Return value
S_OK
Success
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.
105
106

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
See Archive object on page 128.
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

VaultStores object
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 56.
Return value
S_OK
Success
See also
See ExtendedErrorInfo object on page 316.
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
Property
Read/Write
Description
Computer
Read/Write
Identity of an Enterprise Vault

server running a Directory
Service.
Details of the properties and methods of the ICollectionBase interface are provided
in later sections of this guide.
See Table 4-9 on page 108.
107
108

VaultStores object
Table 4-9
ICollectionBase properties
Property
Read/Write
Description
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.
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 110.
Version information
This interface is available from Enterprise Vault 2007.
Example
This example code lists all vault stores based on a Computer DNS name.
[C#]
IContentManagementAPI3 cmAPI = (IContentManagementAPI3)

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);
}
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.
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
109
110

VaultStore object
The Id of an Enterprise Vault Site can be found in the following registry entry on
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\KVS
\Enterprise Vault
\SiteID
The Id of an archive can be found in the Enterprise Vault Administration Console,

Similarly, the Id of a vault store can be found in the Administration Console, in
If the Computer property is left empty, its value defaults to the current value of
the DirectoryDNSAlias property of the parent IContentManagementAPI instance.
Return value
S_OK
Success.
pVal is NULL
Example
[C#]
IContentManagementAPI3 cmAPI = (IContentManagementAPI3)
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
Property
Read/Write
Description
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
Table 4-12
Identifies an Enterprise Vault

server running an Enterprise
Vault Directory Service.
IVaultStore methods
Method
Description
Get
Get the details of the selected vault store.
Remarks
If you use the ICollectionBase interface to enumerate vault stores, then the
IVaultStore properties are populated automatically for each vault store returned.
See VaultStores object on page 107.
Alternatively, if you select a specific vault store using the Id property, you can
call the Get method to populate the VaultStore properties.
Version information
111
112

IVaultStore :: Id
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
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.
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.

IVaultStore :: Name
pVal is NULL, pVal is not

a valid Vault Store
identity, or the object is
already populated.
Example
[C#]
vaultStore.Get();
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
Name of the vault store.
Return value
S_OK
Success.
pVal is NULL.
113
114

Example
[C#]
vaultStore.Get();
This property contains the vault store description.
Syntax
HRESULT Description([out, retval] BSTR* pVal);
Parameter
Vault store description.
Return value
S_OK
Success.
pVal is NULL.
Example
[C#]
vaultStore.Get();


long count = vaultStore.Count;
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 86.
Return value
S_OK
Success.
pVal is NULL.
Example
[C#]
vaultStore.Get();
115
116


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.
pVal is NULL.
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();
This property contains the DNS Alias created for the Enterprise Vault Site.
Syntax
Parameter
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.
pVal is NULL.
117
118

IVaultStore :: Get
Example
[C#]
vaultStore.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.
The Id property is empty.
CONTENTMANAGEMENTAPI_E_NOT_FOUND
The vault store does not

exist.

Directory service is not
running.

Archives object
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();
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
119
120

Archives object
Member summary
Table 4-13
IArchives properties
Property
Read/Write
Description
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

Permissions
Read/Write
Caller's access permissions on the

ArchiveTypes
Read/Write
Types of archives required.
The properties and methods of the ICollectionBase interface are described in later
sections.
Table 4-14
Property
Read/Write
Description
Count
Read only
Number of archives in the

collection.
_NewEnum
Read only

Item
Read only
Instance of the archive at 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.

Archives object
Table 4-15
Method
Description
Get
Clear
Reset
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.
No other combinations of properties are supported.
Version information
This interface requires Enterprise Vault 2007 or later.
Example
This example lists all Exchange Server mailbox archives that can be searched by
the caller, based on the DNS Alias for an Enterprise Vault Site.
[C#]
IArchives archives = (IArchives)cmAPI.Archives;
121
122

See also
See ICollectionBase : IDispatch on page 308.
See Archive object on page 128.
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.
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

HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\KVS
\Enterprise Vault
\SiteID

If the Computer property is left empty, its value defaults to the current value of
the DirectoryDNSAlias property of the parent IContentManagementAPI instance.
Return value
S_OK
Success.
pVal is NULL.
Example
This example gets all the archives that the user has permission to search.
[C#]
archives.Computer = "EV1.acme.com";
archives.Permissions =
EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;
archives.Get();
This property contains the Id of the vault store that contains the required archive
or archives.
123
124

Syntax
HRESULT VaultStoreId([in] BSTR pVal);
HRESULT VaultStoreId([out, retval] BSTR* pVal);
Parameters
[in] 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.
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 =
archs.ArchiveTypes =
EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX;
archs.Get();
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.
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.
pVal is NULL.
125
126

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();
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 enumeration on page 85.
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.
pVal is NULL.
Example
[C#]
archives.Computer = "EV1.acme.com";
archives.Get();
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 77.
127
128

Archive object
Return value
S_OK
Success.
pVal is NULL.
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
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

Archive object
Member summary
Table 4-16
IArchive properties
Property
Read/Write
Description
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.
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
Property
Read/Write
Description
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.
129
130

Archive object
Table 4-17
IArchive2 properties (continued)
Property
Read/Write
Description
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.
Table 4-18
IArchive3 properties
Property
Read/Write
Description
SecurityDescriptor
Read/Write
The security permissions on the archive

specified as a variant byte array
containing a SECURITY_DESCRIPTOR
structure.
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.

131
Example
[C#]
IArchive arch = cmAPI.Archive
arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";
arch.Get();
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
[out,retval] BSTR* pVal
Pointer to a BSTR that contains the Id of the required

vault store
Return value
S_OK
Success.
Incorrect Id format.
Example
arch.VaultStoreId =
arch.Get();
132

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.
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.
pVal is NULL, pVal is not a

valid archive identity, or the
object is already populated.
Examples
arch.VaultStoreId =

IArchive :: Name
arch.Get();
or
[out]
Assume an Archives object, archives, has been populated.

foreach (IArchive archive in archives)
{
SearchArchive(archive.Id);
}
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.
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.
133
134

Return value
S_OK
Success.
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;
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;
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* Pointer to a BSTR that will contain the description of the archive.
pVal
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.
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
135
136

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
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 81.
It may be necessary to cast this to an integer if using in C#.
Return value
S_OK
Success.
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;
137
138

//Now check value

ei = archive.ExpireItems;
//try changing value
archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;
//ERROR
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_
CONVERTED_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.
See EV_STG_API_CONVERTED_CONTENT enumeration on page 79.

Return value
S_OK
Success.
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
139
140

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
EV_STG_API_
INDEX_URGENCY
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 82.
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.


invalid, or the object is already
populated.
Examples
[C++]
EV_STG_API_INDEX_URGENCY
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
141
142

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 81.
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.

invalid, or the object is
already populated.

IArchive :: Size
Examples
[C++]
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_BRIEF;
archive. IndexLevel = il;
//check value
il = Archive. IndexLevel;

archive. IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;
//ERROR
IArchive :: Size
This property contains the size of the archive.
143
144

IArchive :: Size
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.
pVal is NULL, or the object has

not been populated.
The Enterprise Vault Directory

or Storage services are not
running

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


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.
permissions for an archive.
The values of the EV_STG_API_PERMISSIONS_TYPE enumeration 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.
145
146

Version information
At Enterprise Vault 8.0, this property is superseded by the
IArchive3::SecurityDescriptor property.
See IArchive3 :: SecurityDescriptor on page 157.
Return value
S_OK
Success.
newVal is invalid, or the object

is already populated.
Example
To create 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();
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.

not been populated.
147
148


running.

be retried later.
Example
arch.Get();
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.

IArchive :: Create
149
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.

not been populated.

running.

be retried later.
Example
arch.Get();
;
IArchive :: Create
This method is used to create an archive.
150

IArchive :: Create
Syntax
HRESULT Create(void)
Remarks
To create an archive the calling application must be in a role that includes the
operation, 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.
Return value
S_OK
Success.
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.

IArchive :: Create

Directory or Storage
services are not running.

not have sufficient
Caller not in a role that

includes the operation,
Can manage Enterprise
Vault Stores. (The default
Enterprise Vault Storage
Administrator and Power
Administrator roles
include this operation).
Examples
[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;
151
152

IArchive :: Get
archive.IndexLevel = EV_STG_API_INDEX_LEVEL.INDEX_LEVEL_FULL;
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
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.
The Id property is empty.
The archive does not exist.

running.

be retried later.
Example
arch.VaultStoreId =

IArchive2 :: Type
arch.Get();
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 superseded by the IArchive3::Type
property.
153
154

IArchive2 :: Status
Return value
S_OK
Success
pVal is NULL.
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
Pointer to an EV_STG_API
_STATUS that contains the
current value.
[out, retval] EV_STG_API_STATUS* pVal
Remarks
EV_STG_API_STATUS enumeration indicates the status of the archive.
See EV_STG_API_STATUS enumeration on page 86.
Return value
S_OK
Success
pVal is NULL.
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
This property indicates whether the archive is flat or contains a folder structure.
Syntax
HRESULT HasFolders([out, retval] VARIANT_BOOL* pVal);
Parameters
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
pVal is NULL.
Example
bool hasFolders = arch2.HasFolders;
if (hasFolders == true)
155
156

IArchive2 :: Full
{
//do something
IArchive2 :: Full
This property indicates whether the archive is full.
Syntax
HRESULT Full([out, retval] VARIANT_BOOL* pVal);
Parameters
Pointer to a VARIANT_BOOL that

Remarks
If the archive is full, no more items can be stored in it.
Return value
S_OK
Success
pVal is NULL.
Example
bool full = arch2.Full;
if (!full)
{
//store some items

This property contains the DNS Alias created for the Enterprise Vault Site.
Syntax
Parameters
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
pVal is NULL.
Example
arch.VaultStoreId =
string dnsAlias = arch2.DirectoryDNSAlias;
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
Administration Console.
157
158


We recommend that you use the SecurityDescriptorString property to retrieve
and set the security descriptor from applications.
See IArchive3 :: SecurityDescriptorString on page 159.
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.
permissions for an archive. The values are logically OR'd to get the combined
permissions.
Any attempt to modify the security descriptor of an existing archive will result
in an error.
Return value
S_OK
Success.

already populated.

Example
This example illustrates how to fetch the SecurityDescriptor property value.
[C++]
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);
}
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 Administration Console.
159
160

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.
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.
Any attempt to change this value on an existing archive will result in an error.
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.
Return value
S_OK
Success.

already populated.
Examples
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.
The following example includes the access described in the example above, 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)"
The following example includes the access described in the first example above,
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)"
161
162

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.
Any attempt to change this value on an existing archive will result in an error.
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

IArchive3 :: Type
Table 4-20
Structure of archive types (continued)
EV_STG_API_ARCHIVE_TYPE value
HasFolders
property
value
ARCHIVE_TYPE_FILE_SYSTEM
True
ARCHIVE_TYPE_SHAREPOINT
True
ARCHIVE_TYPE_DOMINO_MAILBOX
False
ARCHIVE_TYPE_DOMINO_JOURNAL
False
Return value
S_OK
Success.

invalid, the object is
already populated.
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";
163
164

Items object
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
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
Property
Read/Write
Description
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
The index sequence number

ordering to be used when
enumerating items in the
collection.
Read/Write
The properties and methods of the ICollectionBase interface are described in later
sections.

Items object

Table 4-22
Property
Read/Write
Description
Count
Read only
Number of items in the collection.
_NewEnum
Read only

Item
Read only
Instance of the item at the

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

collection.
More
Read only

items than Maximum.
Table 4-23
Method
Description
Get
Clear
Reset
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
IArchiveMetaData::RetentionCategory
IItem::CopyOptions
165
166

Items object
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.
Version information
This interface requires Enterprise Vault 8.0 or later.
Example
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.
[C++]
// 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)

Items object
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
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;
167
168

IItems :: ArchiveId
}
} while (vbMore)
See also
See ICollectionBase : IDispatch on page 308.
See Item object on page 172.
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.

Maximum length of string: 127
characters.
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 Administration
Console.
The following gives an example value of the ArchiveId property:

169
Return value
S_OK
Success.
pVal is NULL or newVal is

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

items.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";
items.StartSequenceNum = 1000;
items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC;
items.Get();
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.
170

IItems :: OrderBy
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 253.
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.
pVal is NULL or newVal

is not a valid archive
identity.
Example
(IContentManagementAPI3)ContentManagementAPIClass();

items.Get();
IItems :: OrderBy
This property is used to specify the index sequence number order to be used when
enumerating items in the collection.

IItems :: OrderBy
171
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 76.
Return value
S_OK
Success.
pVal is NULL or newVal is

invalid.
Example
(IContentManagementAPI3)ContentManagementAPIClass();

items.Get();
172

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
Property
Read/Write
Description
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.

Item object
Table 4-24
Property
IItem properties (continued)

Read/Write
Description
DefaultMSGFormat Read/Write
Sets the format (ANSI or Unicode)

for the item being retrieved, where
the original format has not been
stored.
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.
173
174

IItem :: ArchiveId
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
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.

Maximum length of string: 127
characters.

IItem :: Id
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.
pVal is NULL, or newVal is

not a valid Archive Id.
Example
[C#]
IItem itm = cmAPI.Item;
itm.ArchiveId = ""181E669473B52E64384C9A7D9EACA0E7E1110000evsite";
itm.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7
9f3298dc8a1e60";
IItem :: Id
This property identifies the item in the archive.
Syntax
175
176

IItem :: Id
Parameters
[in] BSTR newVal
Id of stored item.

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.
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")

IItem :: Content
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
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
177
178

MimeFormat
CreatedDate
ModifiedDate
Data
OriginalSize
Author
Return value
S_OK
Success.
pVal is NULL.
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);
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.
Return value
S_OK
Success.
pVal is NULL.
Example
item.Get((int)EV_STG_API_ITEM_DETAIL.
IArchiveMetaData amd = item.ArchiveMetaData;
See also
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)
179
180

Parameters
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 architecture.
Return value
S_OK
Success.
Either the Archive Id or

Saveset Id have not been
set or the Saveset Id is
invalid.

Directory Service is not
running.

not have sufficient
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;
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 below.
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:"
Return as ANSI code page. For example, "A:932" return as Japanese

ANSI.
181
182

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.
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");
[C#]
itm.DefaultMSGFomart = "U";
//do something - set ids etc
//
ERROR

IItem :: Holds
Itm.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ALL));
Itm.=defaultMSGFormat = "N";
//ERROR
IItem :: Holds
This property gives access to the set of holds currently placed on the item. The
property is read only.
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.
This property is a collection of IHold pointers, each of which defines a hold placed
on the particular item.
Return value
S_OK
Success.
The pVal pointer is

NULL, or could not find
the HOLDS collection.
Example
183
184

item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA);
IHolds holds = Item.Holds;
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.
Return value
S_OK
Success.
The pVal pointer is

NULL, or either the Item
Id or Archive Id have not
been set.
Examples
[C++]

185
CComBSTR bstr;
item->put_Id(L"200501051649270000~0~9039eb282e3d4083b79f3298
dc8a1e60")
item->put_ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E11100
00evsite");
item->get_NativeItemURL(&bstr);
[C#]
item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite";
string url = item.NativeItemURL;
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 75.
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.
186

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 210.
Version information
The ability to retrieve deleted items in Enterprise Vault is available from

Enterprise Vault 2007.
Return value
S_OK
Success.
The pVal pointer is

NULL, 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]
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES);
EV_API_DELETION_LEVEL evDL = item.DeletionLevel;

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
187
188

RetentionCategory
CurrentLocation
CurrentFolder
CustomIdentifier
CustomQualifier
CustomProperties
See EV_STG_API_ITEM_COPYOPTIONS enumeration on page 82.
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 selected
Override value set Property value in

on destination item copied 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.

Table 4-28
Item property

(continued)
Option selected

No
No
Set to current
date/time.
Yes
RetentionCategory Yes (Default)
Set to the site default

Retention Category if
override value
specified as a zero
length string value.
No
Yes
As above.
Yes (Default)
No
Copied from source

item.1
No
No
Set to the site default

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

CustomQualifier
CustomProperties
CurrentLocation
CurrentFolderId
Set to zero value if

override specified as
zero value.
No
Yes
As above.
Yes (Default)
No
Copied from source

item.
No
No
Set to zero value.
Yes (Default)
Yes
No
Yes
See
IArchiveMetaData2
:: CurrentLocation
on page 245.
Yes (Default)
No
Copied from source

item.3
189
190

Table 4-28
Item property

(continued)
Option selected

No
No
See
IArchiveMetaData2
:: CurrentLocation
on page 245.
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.
The pVal pointer is

NULL, or an attempt has
been made to set the
CopyOptions of an
existing item, or the
value set is not within
enumeration.
Example
In the following VBScript example, the source item's ArchiveMetaData values are
preserved on the destination item.
Dim ecmAPI
Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")
Dim oItem, oDestItem

IItem :: Insert
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 = 2
oItem.CopyTo (oDestItem)
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
191
192

IItem :: Insert
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:
Outlook messages, which have a file extension of .msg and a MIME format
of application/vnd.ms-outlook.
SMTP messages, which have a file extension of .eml and a MIME format
of 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.
Return value
S_OK
Success.
One of the following situations exists:

One of the required property values has not been
set .
See Remarks above.
Both of IArchiveMetadata2::CurrentLocation and
IArchiveMetadata2::CurrentFolderId have been set
but they refer to different archive folders.
Either IArchiveMetadata2::CurrentLocation and
IArchiveMetadata2::CurrentFolderId have been
set, and the target archive is a flat archive.
This item has previously been used, in which case
this one must be destroyed and a new one created.
The Enterprise Vault Directory or Storage services are

not running.

IItem :: Insert
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.
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.
193
The caller does not have write access to the target

archive or archive folder.
The archive is in a read-only state.
CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID
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 Enterprise Vault
Storage Administrator and Power Administrator
roles include this operation).
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#]
194

IItem :: Get

item.Insert();
See also
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 83.
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 239.
EV_STG_API_ITEM_DETAIL indicates the data to retrieve for an item.
The caller can "bitwise OR" the bit masks together. For example, IItem.Get(255)
returns the item properties and the metadata.

IItem :: Get
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.
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 220.
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
\Wow6432Node
\KVS
\Enterprise Vault
\MaxIndexDataHTMLContentKB
This registry setting is described in the Registry Values guide.
Return values
S_OK
Success.
195
196

IItem :: Get
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.
The Enterprise
Vault Directory or
Storage services
are not running.
Enterprise Vault is
currently busy or
has insufficient
resource to
complete the
request. This error
indicates that the
caller should retry
later.
The target Archive

Id is unknown or
has been deleted,
or the selected
item is not present
or has been
deleted.
The caller does not

have read access to
the target archive
or archive folder.
CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER
More than one

item identified by
combined
CustomIdentifier
and
CustomQualifier
properties.

IItem :: Get
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 42.
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.
SP4 on page 42.
IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier

require Enterprise Vault 8.0.
See Enterprise Vault 8.0 on page 34.
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;
pStorage->CreateStream(\xe3 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);
197
198

IItem :: Delete
//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
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.

IItem :: Delete
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.
A NULL pointer has been passed

in, or either the Archive Id or
Item Id have not been set.
The target Archive Id is

unknown or has been deleted.

running.
Enterprise Vault is currently

busy or has insufficient resource
to complete the request. This
error indicates that the caller
should retry later.
The caller does not have delete

access to the target archive or
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");
199
200

item->Delete();
[C#]
DETAIL_LEVEL_ITEM_PROPERTIES);
object obj = item.CanBeDeleted;
int canBeDeleted = (int)obj;
if (obj == 0)
{
item.Delete();
}
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.
See EV_STG_API_CAN_DELETE enumeration on page 78.
Return value
S_OK
Success.

IItem :: CopyTo
ANULL pointer has been passed

in, or either the Item
IdorArchive Id has not been set.

running.

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

unknown or has been deleted,
or the selected item is not
present or has been deleted.
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
This method is used to copy an item from one archive to another.
201
202

IItem :: CopyTo
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.
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.
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.
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.
For backwards compatibility, the calling application can set suitable override
values on the destination item object.
Important considerations apply when specifying the destination archive folder.

IItem :: CopyTo
Return value
S_OK
Success.

Either the destination archive or Item
Id has not been set.
Both
IArchiveMetadata2::CurrentLocation
and
IArchiveMetadata2::CurrentFolderId
have been set, but they refer to different
archive folders.
Either
and
have been set, and the destination
archive is a flat archive.
The destination site is not the same as
the source site.
The Enterprise Vault Directory or Storage

Enterprise Vault is currently busy or has

insufficient resource to complete the copy,
or Enterprise Vault is currently being
backed up and is not accepting copy
requests. This error indicates that the caller
should retry later.
The source or destination Archive Id is

unknown or has been deleted, or the
selected retention category is not known or
has been deleted, or the source item cannot
be found or has been deleted.
The destination archive is full or exceeds

its quota limit.
203
204

IItem :: CopyTo

No access to the archive or archive
folder.
The target archive is in a read-only
state.
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". (By
default, the Enterprise Vault Storage
Administrator and Power Administrator
roles include this operation).
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"));
pItmDest->put_ArchiveId(CComBSTR(L"1E1FA1405F674644286ADBD247BA780C
B1110000evsite"));
pItemSrc->put_Id(CComBSTR(L"334880000000000~200707251102240000~0~D3
962A35951E4B03AE9CFB68AFE1218"));
IItem* pItemDst = NULL;
pCmAPI->get_Item(&pItemDst);
IArchiveMetaData* pDstAMD = NULL;
pItemDst->get_ArchiveMetaData(&pDstAMD);
pDstAMD->put_RetentionCategory(CComBSTR(L"Business"));
IComplianceData* pDstComp = NULL;
pDstAMD->get_ComplianceData(&pDstComp);
pDstComp->SetBy(SETBY_RETCAT);
pItemSrc->CopyTo(pItemDst);

IItem :: MoveTo
[C#]
IItem itemSrc = cmAPI.Item;
IItem itemDst = cmAPI.Item;
itemSrc.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev
site";
itemDst.ArchiveId = "1E1FA1405F674644286ADBD247BA780CB1110000ev
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
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.
application must be in an Enterprise Vault role that includes the operation, "Can
Use Extended API Features". This operation is included in the default Enterprise
Vault Power Administrator and Storage Administrator roles.
205
206

IItem :: MoveTo
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 201.
The CopyOptions property on the destination item object specifies the item
elements to be copied across to the destination item.
Return value
S_OK
Success.

Either the destination archive or
Item Id has not been set.
Both
and
have been set but they refer to
different archive folders.
Either
and
have been set and the destination
archive is a flat archive.
The destination site is not the same
as the source site.
The Enterprise Vault Directory or

Storage services are not running.
Enterprise Vault is currently busy or has

insufficient resource to complete the
copy, or Enterprise Vault is currently
being backed up and is not accepting
copy requests. This error indicates that
the caller should retry later.
The source or destination Archive Id is

unknown or has been deleted, or the
selected retention category is not known
or has been deleted or the source item
is not found or has been deleted.

IItem :: MoveTo
The destination archive is full or exceeds

its quota limit.
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.

The caller does not have delete access
to the source archive, or archive
folder.
The caller does not have write access
to the destination archive, or archive
folder.
The source or destination archive is
in a read-only state.
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". (By default, the
Enterprise Vault Storage
Administrator and Power
Administrator roles include this
operation).
Attempting to move items to a

structured archive containing multiple
root folders (for example, a public folder
archive).
Example
site";
itemDst.ArchiveId = "1E1FA1405F674644286ADBD247BA780CB1110000ev
site";
itemSrc.Id ="334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218";
207
208

itemSrc.MoveTo(itemDst);
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_3REASON* 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 80.
Return value
S_OK
Success.
S_FALSE
Success. The default value

(NULL) is returned.

The pointer (pVal) passed

in is NULL, or the item's
Archive Id or Id property
have not been set.
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.
Example
[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
209
210

IItem3 :: Undelete
{
delReason = destItem.DeletionReason;
}
finally
{
// Log that the item was not found together with the
// deletion reason
LogItemNotFound(destItem, delReason);
}
}
}
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.
The target Archive Id has

not been found.

IItem3 :: Undelete
The pointer (pVal)

passed in is NULL, or the
item's Archive Id or Item
Id property have not
been set.
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".
The item could not be

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

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
See IItem :: DeletionLevel on page 185.
Examples
[C#]
IItem3 item = (IItem3)cmAPI.Item;
item.ArchiveId =
211
212

Content object
"118F819534E391C43B6854E2DD3A708C61110000EV.example.com";
item.Id =
"201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51
651";
bool UnDeleted = item.Undelete();
[VBScript]
Dim ecmAPI, oItem, oItem3
set oItem = ecmAPI.Item
set oItem3 =
ecmAPI.IDispatchQueryInterface(oItem,"{E5C7F710-36AD-4e24-B00A-E3D7
09FF76CD}")
oItem3.ArchiveId =
"118F819534E391C43B6854E2DD3A708C61110000EV.example.com"
oItem3.ID =
"201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51651"
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
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.

Content object
Syntax
interface IContent : IDispatch
Member summary
Table 4-29
IContent Properties
Property
Description
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
item.Insert();
213
214

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
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.
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
This property holds the original location of the item.

Syntax
HRESULT OriginalLocation([out, retval] BSTR* pVal);
HRESULT OriginalLocation([in] BSTR newVal);
Parameters
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.
S_FALSE

(NULL) is returned.

or this property has
already been set.
Example
item.Insert();
This property holds the file extension describing the format of the item.
215
216

Syntax
HRESULT FileExtension([out, retval] BSTR* pVal);
HRESULT FileExtension([in] BSTR newVal);
Parameters
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.
The pVal pointer is

been made to change an
existing value.
Example

item.Insert();
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

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.
The pVal pointer is

been made to change the
value of this property
after the item has been
archived.
217
218

Example
content.MIMEFormat = "text/plain";
content.OriginalLocation = "C:\\temp";
content.Data = "C:\\temp\\test.txt";
item.Insert();
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
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.

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;
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
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.
219
220

IContent :: Data
Remarks
Once this item has been archived it is not possible to change the value of this
property.
Return value
S_OK
Success.
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
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);

IContent :: Data
221
Parameters
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.
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.
222

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.
The pVal pointer is

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);
This property returns the size of the original item, in bytes, before it was archived.
Syntax
HRESULT OriginalSize([out, retval] VARIANT*
pVal);

IContent :: Author
Parameters

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.
The pVal pointer is

NULL.
Example
object obj = content.OriginalSize;
double size = (double)obj;
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);
223
224

IContent :: Author
Parameters
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.
The pVal pointer is

been made to change the
after the item has been
archived.
Example
[C#]
[in]
item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000EVSite";
content.Author = "Charles Dickens"
item.Insert();
[out]

string author = content.Author;
IArchiveMetaData
IID is {4A0AAD67-882B-4fd6-A76C-4F7B0864F5D6}
IArchiveMetaData2
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
Property
Read/Write
Description
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.
225
226

Table 4-30
IArchiveMetaData properties (continued)
Property
Read/Write
Description
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.
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.

Table 4-30
IArchiveMetaData properties (continued)
Property
Read/Write
Description
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
Property
Read/Write
Description
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.
227
228

Example
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
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 About Retention API on page 562.
Currently it is not possible to modify this property using the Content Management
API after the item has been archived.

Return value
S_OK
Success.
S_FALSE

The pVal pointer is

NULL.

Directory Service is not
running.

not have sufficient
resources to complete
the request. The request
Example
string retCat = amd.RetentionCategory;
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);
229
230

Parameters
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
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
Pointer to an VARIANT_BOOL
which will contain the current
[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.

or an attempt was made to
modify this property after
the item had been stored in
an archive.
Example
[in]
item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000EVSite";
amd.OverrideOnHoldRetCat = true;
item.Insert();
[out]
231
232

bool override = amd. OverrideOnHoldRetCat;
if (override == true)
{
//do something
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

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 255.
Return value
S_OK
Success.
The pVal pointer is

NULL, or the value input
is not a valid date time.

Example
object obj = amd.ArchivedDate;
DateTime dt = (DateTime) obj;
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.
Return value
S_OK
Success.
233
234

Example
IComplianceData compData = amd.ComplianceData;
EV_STG_API_CP_UNITS evUnits = compData.Units;
object obj = compData.Value;
ulong val = (ulong)obj;
This property holds the size of the archived item saveset, rounded to the nearest
KB.
Syntax
HRESULT SavesetSize([out, retval] VARIANT* pVal);
Parameters

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.

or an 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;
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

current value.
Remarks
This property value is populated when the item detail level,
DETAIL_LEVEL_COMPLIANCE_DATA, is set on the item Get method.
235
236


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;
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.
Return value
S_OK
Success.
The pVal pointer is

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
This property indicates that is it safe to delete the original item from the source
store.
237
238

Syntax
HRESULT IsItemSecured([out, retval] VARIANT_BOOL* pVal);
Parameters
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.
The pVal pointer is

NULL.
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

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.
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.
S_FALSE

239
240

The pVal pointer is

NULL, or either an
to modify this property
after it has been stored
in an archive, or the
value exceeds 255
characters.
Example
This VBScript 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
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

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

(0) is returned.

or either an attempt has
been made to modify this
property after it has been
stored in an archive, or the
CustomIdentifier property
has not been set.
Example
const CUSTOM_PROPERTIES = "<?xml version=1.0?><properties><key
= 1 value=some value/></properties>"
Dim oItem
241
242

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
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
S_FALSE

(NULL) is returned.
The pVal pointer is NULL, or

either an attempt has been
made to modify this property
after it has been stored in an
archive, or the value exceeds
2500 characters.
Example

const CUSTOM_PROPERTIES = "<?xml version=1.0?><properties><key =

1 cost=543/></properties>"
Dim oItem
The Update method is used to effect changes made to the ICompliance interface
by the calling application to the item stored in Enterprise Vault. Currently the
Update method cannot be used to update any other archive metadata properties.
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.
243
244

Return value
S_OK
Success.
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
to change it.
CONTENTMANAGEMENTAPI_E_INVALID_DEVICE
The storage device is not

a compliance device.

Enterprise Vault is
currently busy or has
insufficient resource to
complete 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.
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();
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.
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.
245
246

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.
247
248

Table 4-33 summarizes how the archive folder is determined when different
combinations of the following properties are set:
Table 4-33
Determining the target archive folder for insert, move and copy
operations
ArchiveId
Property
CurrentFolderId CurrentLocation OriginalLocation Archived to

Property
Property
Property
folder
Saveset
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 OriginalLocation
or
property
OriginalLocation
property (Folder
created as
necessary - viz
current refile
behaviour)
Archive Id
Not specified
Specified
Not specified
Folder matching
CurrentLocation
property (Folder
created as
necessary)
Value of
CurrentLocation
property
Archive Id
Not specified
Specified
Specified
Folder matching
CurrentLocation
property (Folder
created as
necessary)
Value of
OriginalLocation
property
Archive ID
Specified
Not specified
Not specified
Specified folder.
Path of the
specified
CurrentFolderId
from the
Directory
(It must be a
folder in the
archive)

Table 4-33
operations (continued)
ArchiveId
Property

Property
Property
Property
folder
Saveset
OriginalLocation1
Archive ID
Specified
Not specified
Specified
Specified folder. Value of

(It must be a
OriginalLocation
folder within the property
archive)
Archive ID
Specified
Specified
Irrelevant
Not supported;
error with invalid
arguments2
Archive folder ID
Not specified
Not specified
Not specified
Folder specified
in ArchiveId
property
Path of specified
Archive folder ID
from the
Directory
Archive folder ID
Not specified
Not specified
Specified
Folder specified
in ArchiveId
property
Value of
OriginalLocation
property
Archive folder ID
Not specified
Specified
Not specified
Folder matching
CurrentLocation
property.
Value of
CurrentLocation
property
(Folder created as
necessary)
Archive folder ID
Not specified
Specified
Specified
Folder matching
CurrentLocation
property.
Value of
OriginalLocation
property
(Folder created as
necessary)
Archive folder ID
Specified
Not specified
Not specified
Specified folder.
(It must be a
folder in the
archive)
Archive folder ID
Specified
Not specified
Specified
Specified folder.
(It must be a
folder in the
archive)
Path of the
specified
CurrentFolderId
from the
Directory
Value of
OriginalLocation
property
249
250

operations (continued)
Table 4-33
ArchiveId
Property

Property
Property
Property
folder
Archive folder ID
Specified
Specified
Irrelevant
Saveset
OriginalLocation1
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

(NULL) is returned.

newVal is not a syntactically
valid folder path.

Directory or Storage services
are not running.

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);
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.
The ID of the item's current archive folder.
251
252

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

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

(NULL) is returned.

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);
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 169.
The Items collection object populatesthis property automatically. This is useful
for bulk moving or copying items.
253
254

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
This example shows how to use the IArchiveMetaData2 interface to fetch the
SequenceNUm property.
[C#]
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;

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 time to be set for

this item

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.
255
256

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);
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
Property
Read/Write
Description
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.
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#]
257
258


The following VBScript excerpt gives an example of how metadata can be read
from the instance returned by Content Management API:
[VBScript]
[C#]
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
See SimpleIndexProperty object on page 269.
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.
NULL pointer passed to receive

property value.
259
260

Example
item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) |
(EV_STG_API_ITEM_DETAIL. 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
}
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.
pRetVal is NULL.
Example
Use local system date/times
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.
pRetVal is NULL.
Example
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));
261
262


if (simple.Count> 0)
{
//do something
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
supported types listed in
Table 4-36.

[in] VARIANT_BOOL propertySearchable
Defines whether the property is

added to the item index. Setting
the value of this property to true
means that the property will be
indexed.
The default value is true.
[in] VARIANT_BOOL
propertyRetrievable
Defines whether the property

values can be requested in 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.
Table 4-36
Supported types for propertyValue
Value type
Variant type
Note
String
VT_BSTR
dateTime
VT_DATE
Limited to the UTC date

range 1st January 1970 to 1st
January 2038
Integer
VT_UI1, VT_UI2, VT_UI4,

VT_UI8, VT_I1, VT_I2,
VT_I4, VT_I8, VT_INT,
VT_UINT, or VT_DECIMAL
Limited to the range 0 to

4,294,967,294
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
263
264

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
Hints and tips on adding custom index properties are provided in the introduction
to the Content Management API.
Return value
S_OK
Success.
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
//add some custom index data
simple.Add("My set", "My name", 32, true, true);
item.Insert();

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
item.Get((int)((EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA) | (
EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));
simple.Clear();
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.
265
266

Return value
S_OK
Success.
pRetVal is NULL.
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.
Figure 4-3
ToXML result
See also
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.
267
268

Return value
S_OK
Success.
xmlIndexMetadata supplied
as NULL, or is invalid XML.
Example
//add some custom index data from xml
simple. FromXML(xmlData); //xmlData is a pre-populated string
containing the xml
item.Insert();
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.
pRetVal is NULL,or utcDateTime

is not a syntactically valid UTC
date time value.
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.
pRetVal is NULL,or
localDateTime is not a
syntactically valid local date
time value.
SimpleIndexProperty object
The SimpleIndexProperty object implements the following interface:
ISimpleIndexProperty
269
270

Syntax
interface ISimpleIndexProperty : IDispatch
Member summary
This read-only interface has the following properties defined:
Table 4-37
ISimpleIndexProperty properties
Parameter
Read/Write
Description
Set
Read only
Name of the property set.
Name
Read only
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
{
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.
NULL pointer was passed to

receive property value.
Example
EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));
{
}
271
272

This property returns the property name.
Syntax
HRESULT Name([out,retval] BSTR* value);
Parameters
[out,retval] BSTR* value
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.

Naming format for messages
Figure 4-4
Top-level message
1
Message
Attachments
1.2
1.1
1.1.1
1.1.2
1.3
1.2.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.
273
274

Example values of IndexPropANUM
Figure 4-5
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.
See Note 4 on page 610.
Return value
S_OK
Success.

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 40.
Content missing reasons returned in the index data COMR property is available
in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
6.0 SP5 on page 40.

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.
SP4 on page 42.
Example
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL
_CUSTOM_INDEX_METADATA)));
{
}
See also
This property returns the property value.
Syntax
HRESULT Value([out,retval] VARIANT* value);
275
276

Parameters
[out,retval] VARIANT* value
Table 4-38
Property value. A Variant containing a value of

any of the supported types listed in Table 4-38.
Supported types for Value
Value type
Variant type
String
VT_BSTR
Datetime
VT_DATE

January 2038
Integer


4,294,967,294
SimpleIndexMetadata object VT_UNKNOWN
Note
An ISimpleIndexProperty
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.

Example

{
}
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.

277
278

Example
{
}
See also
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.

Example
(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));
{
}
See also
This property indicates that the property is an Enterprise Vault system property.
279
280

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.

Example
(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA) |
(EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_SYSTEM_INDEXDATA)));
{
bool isSystem = ip.System;
}

281
See also
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-39
IComplianceData properties
Property
Read/Write
Description
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
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA);
282

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 80.
Return value
S_OK
Success.
The pVal pointer is NULL, or the

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

EV_STG_API_CP_UNITS
evUnits = compData.Units;

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
value of the property
[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.

newVal is invalid.
283
284

Example
EV_STG_API_CP_UNITS evUnits = compData.Units;
This property indicates where the retention period was defined.
The property is write only.
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

value of the property
Remarks
EV_STG_API_CP_SETBY indicates where the compliance retention period is set.
See EV_STG_API_CP_SETBY enumeration on page 79.
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.

Holds object
Invalid pointer passed to receive

property value, or the value
passed in does not conform to one
of the enumeration type values.
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.
285
286

Holds object
The list of items that the calling application wants to place on hold.
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-40
IHolds Properties
Property
Description
_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.

IHolds :: _NewEnum
Table 4-40
IHolds Properties (continued)
Property
Description
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-41
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-42
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
IHolds :: _NewEnum
to enumerate the IHolds collection object. This property is hidden in Visual Basic
Scripting Edition (VBScript).
Syntax
287
288

IHolds :: Item
Parameters

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

Example
foreach (IHold hold in holds)
{
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);

IHolds :: Count
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.
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
This read only property returns the number of Holds in the collection.
289
290

IHolds :: GroupId
Syntax
HRESULT Count([out, retval] long* pRetVal);
Parameters
[out, retval] long* pRetVal
Current number of holds in the collection.
Return value
S_OK
Success.
The pRetVal pointer is

NULL.
Example
{
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);

IHolds :: GroupId
Parameters
[in] BSTR newVal
BSTR containing the new group Id.
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.

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";
hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
//add more hold's if necessary
holds.PlaceHolds();
291
292

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.
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.
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

IHolds :: Metadata
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
holds.PlaceHolds();
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.
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.
An attempt was made to

modify this property once the
PlaceHolds had been called.
293
294

IHolds :: Add
Example
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
holds.PlaceHolds();
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.

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();
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.
295
296

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.

running.

later.
Example
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
holds.PlaceHolds();
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.
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.

running.

later.
297
298

Example
cmAPI.DirectoryDNSAlias = "SERVER1";
holds.ReleaseHolds();
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.
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.

running.

busy or has insufficient resource
to complete the request. This
error indicates that the caller
should retry later.
Examples
cmAPI.DirectoryDNSAlias = "SERVER1";
IHolds2 holds = (IHolds2)cmAPI.Holds;
holds2.GroupId = "Group 1";
holds2.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}";
string xml holds2.ReleaseHolds2();
299
300

Hold object
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
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-43
IHold properties
Property
Description
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.

IHold :: ArchiveId
Table 4-43
IHold properties (continued)
Property
Description
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.
Example
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
IHold :: ArchiveId
This property specifies the ArchiveID of the archive where the item that this hold
object refers to is stored.
Syntax
Parameters
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.
301
302

IHold :: ItemId
Remarks
This property must be set before a hold is placed or released.
Return value
S_OK
Success.
The pVal pointer is NULL, or the

value is not a syntactically valid
Archive Id.
Example
[in]
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
[out]
{
I Hold hold = (IHold)holds.Item(i + 1);
string archId = hold.ArchiveId;
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);

IHold :: ItemId
Parameters
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.

value passed in is not a
syntactically valid Saveset Id or
Transaction Id.
Example
[in]
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";
holds.Add(hold);
[out]
{
string itemID
= hold.ItemId;
303
304

IHold :: Id
IHold :: Id
This property identifies the hold object.
Syntax
Parameters
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.

newVal is not a syntactically
valid Hold Id.
Example
[in]

IHold :: Status
hold.Id = 123;
holds.Add(hold);
//add more holds
holds.ReleaseHolds;
[out]
{
string ID
= hold.Id;
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
Pointer to a VARIANT that will contain the current

status value.
Remarks
The VARTYPE of the variant must be vt = VT_I4.
Return value
S_OK
Success.
305
306

IHold :: Metadata
IHold :: Metadata
This property returns the metadata that is stored with the hold.
Syntax
HRESULT Metadata([out, retval] BSTR* pVal);
Parameters
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
This property returns the unique identifier of the calling application that placed
the hold.

IHold :: GroupId
Syntax
HRESULT ConsumerGUID([out, retval] BSTR* pVal);
Parameters
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.
The pVal pointer is NULL, or pVal

is not a valid GUID.
Example
{
string conGUID = hold.ConsumerGUID;
IHold :: GroupId
This property returns the identifier of the group of holds to which the hold belongs.
Syntax
HRESULT GroupId([out, retval] BSTR* pVal);
307
308

Parameters
Pointer to a BSTR that will contain the current group

Id.
Remarks
See IHolds :: GroupId on page 290.
Return value
S_OK
Success.
Example
{
string groupID = hold.GroupId;
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
Table 4-44
Property
Read/Write
Description
Count
Read only
Number of items in the collection.

Table 4-44
ICollectionBase properties (continued)
Property
Read/Write
Description
_NewEnum
Read only

Item
Read only
Instance of the item at the

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

collection.
More
Read only

items than Maximum.
Table 4-45
Method
Description
Get
Clear
Reset
Version information
This interface is available in Enterprise Vault 2007 or later.
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.
309
310

Return value
S_OK
Success.
value is NULL.
Example
[C#]
archives.Get();
for (long i = 0; i < archives.Count; i++)
{
ProcessArchive(archives.Item(i));
to enumerate the collection object. This property is hidden in Visual Basic Scripting
Edition (VBScript).
Syntax
Parameters

Remarks
VBScript.
Return value
S_OK
Success.
enumerator is NULL.

Example
[C#]
archives.Get();
{
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.
item is NULL, or index is invalid.
Example
[C#]
archives.Get();
{
IArchive archive = (IArchive)archives.Item(i);
311
312

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.
Value is NULL, or value is

invalid.

Example
[C#]
archives.Maximum = 6000;
archives.Get();
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

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.
value is NULL.
Example
[C#]
archives.Maximum = 6000;
archives.Get();
if (archives.More == true)
{
//do something,
313
314

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.
The combination of properties

used for the collection selection
criteria are invalid.
See VaultStores object
on page 107.

running.

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();
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
This method resets the collection back to the initial empty state.
315
316

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.
Example
[C#]
archives.Get();
{
}
//now reset archives before doing another get with different filters
set
archives.Reset();
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-46
IExtendedErrorInfo properties
Property
Read/Write
Description
Error
Read only
The Content Management API

return value associated with the
most recent call to a Content
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
This property is not currently

implemented.
Read only
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)
317
318

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.
The following example code shows how the ExtendedErrorInfo object is used.
[C++]
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);
}
}
}
The following example code shows how the ExtendedErrorInfo object is used.
[VBScript]
private Sub ReportCMAPIError(byref ecmAPI)
dim
dim
dim
dim
oExtErr
szErrorDesc, szInnerErrorDesc
vbError, vbExtError
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
319
320

Msg = Msg & " InnerError Description: " & szInnerErrorDesc &
vbCrLf & vbCrLf
Msg = Msg & "***************************"
WScript.Echo Msg
Err.Clear
end sub
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
See Content Management API return values on page 619.
Return value
S_OK
Success.
E_INVALIDARG
pVal is Null.
IExtendedErrorInfo :: Description
This property provides the error description for the Content Management API
return value.

Syntax
Parameters
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
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.
321
322

Return value
S_OK
Success.
E_INVALIDARG pVal is Null
This property provides the error description for the Enterprise Vault internal
return value.
Syntax
HRESULT InnerErrorDescription([out, retval] BSTR* pVal);
Parameters
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 :: 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.
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-47
IDiagnosticsAPI properties
Property
Read/Write
Description
Name
Read/Write
Name of application
Table 4-48
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.
323
324

Remarks
For a description of the Dtrace utility, see the Enterprise Vault Utilities guide.
Version information
This property holds the name of the application.
Syntax
HRESULT Name([in] BSTR pVal);
Parameters
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 the following:
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.
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 76.
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
This method creates an entry in the Enterprise Vault event log.
325
326

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 76.
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.
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 76.
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-49
DTrace setting
Mapping of API trace levels to Dtrace monitoring level settings

TRACE_LEVEL_HIGH TRACE_LEVEL_MEDIUM TRACE_LEVEL_LOW
Off
No
No
No
Brief
Yes
No
No
Medium
Yes
Yes
No
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.
327
328

Chapter
NSF Manager API

About NSF Manager API
NSF Manager API
Enumerations
NSFManager object
INSFManager :: OpenNSF
INSFManager :: CreateNSF
INSFManager :: CloseNSF
INSFManager :: ViewNote
INSFManager :: ImportNote
INSFManager :: ExportNote
INSFManager :: DeleteNote
INSFManager :: InitializeNotes
INSFManager :: TerminateNotes
INSFManager :: SwitchToID
About NSF Manager API

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

NSF Manager API
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.
How Enterprise Vault processes Lotus Notes messages is described in an appendix
to this guide.
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::FileExtension defines the type of the item ("dvns" or

IContent.MIMEFormat = "application/x-evnotestream").
and See IContent :: MIMEFormat on page 217.
IItem::ArchiveId determines the destination archive for the item.

See IItem :: ArchiveId on page 174.
IItem::Insert stores the item in the archive.

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.
NSF Manager API

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 174.
IItem::Get retrieves the item from the archive.

IContent::Data holds the item content (as a file, or an IStream or ILockBytes

object).
IContent::FileExtension specifies the type of the item ("dvns" or

IContent::MIMEFormat = "application/x-evnotestream").
and See IContent :: MIMEFormat on page 217.
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.
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.
331
332
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
};
NSFManager object
The NSFManager object implements the following interface:
INSFManager
Syntax
interface NSFManager : IDispatch
Member summary
Table 5-1
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.
NSF Manager API

Table 5-1
Member summary (continued)
Method
Description
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
.NET Primary
Interop Assembly
(PIA)
.NET PIA
namespace
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.
333
334
NSF Manager API

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(
}
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
NSF Manager API

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
{
}
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
335
336
NSF Manager API

Example
The following example shows how to use CloseNSF to close a database, without
deleting it:
try
{
}
finally
{
}
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:
NSF Manager API


try
{
uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns");
nsfMgr.ViewNote(noteId);
}
finally
{
}
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
337
338
NSF Manager API

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
{
}
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.
NSF Manager API

Return value
Example
The following example shows how to use ExportNote to export a note:
try
{
nsfMgr.ExportNote(0x8f6, @"c:\EVNotes\storedNote.dvns");
}
finally
{
}
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
339
340
NSF Manager API

Example
The following example shows how to use DeleteNote to delete a note:
try
{
nsfMgr.DeleteNote(0x8a6);
}
finally
{
}
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
NSF Manager API

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
{
}
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
341
342
NSF Manager API

Example
The following example shows how to use TerminateNotes to terminate the Notes
runtime:
try
{
}
finally
{
}
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
NSF Manager API

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
{
}
343
344
NSF Manager API

Chapter
Filtering APIs
About the Filtering APIs
Enumerations (Exchange filtering)
IExternalFilter interface
IExternalFilter :: Initialize
IExternalFilter :: ProcessFilter
IExternalFilter :: FilteringComplete
IArchivingControl interface for Exchange filtering
IArchivingControl :: currentVaultId
IArchivingControl :: currentRetentionCategoryId
IArchivingControl :: defaultRetentionCategoryId
IArchivingControl :: deleteOriginalItem
IArchivingControl :: createShortcutToItem
IArchivingControl :: Action
IArchivingControl :: MAPISession
IArchivingControl :: MAPIMessage
IArchivingControl :: AddIndexedProperty
IArchivingControl :: IndexedPropertiesSet
346
Filtering APIs
IArchivingControl :: AddIndexPropertyToSet
IArchivingControl :: AddIndexPropertySet
IArchivingControl :: TransactionID
IArchivingControl :: AgentType
IArchivingControl :: AgentAssignedRetentionCategoryId
IArchivingControl :: AgentAssignedVaultId
IArchivingControl :: GetFilterProperty
IArchivingControl :: PutFilterProperty
IArchivingControl :: AttachmentAction
IArchivingControl :: RetryStatus
IArchivingControl :: ReArchiveStatus
IArchivingControl2 :: BrowserViewURL
IArchivingControl2 :: NativeItemURL
IArchivingControl2 :: MessageClass
IArchivingControl2 :: MAPISaveChanges
IArchivingControl3 :: SenderRecipientXML
IArchivingControl3 :: EnvelopeSenderRecipientXML
IArchivingControl3 :: MessageDirection
IArchivingControl4 :: AddIndexedPropertyEx
Domino Filtering and File System Filtering APIs
Enumerations (Domino filtering)
Enumerations (File System Filtering)
IExternalFilter :: Shutdown
Filtering APIs
IArchivingControl interface
IArchivingControl :: OriginalVaultID
IArchivingControl :: CurrentVaultID
IArchivingControl :: OriginalRetentionCategoryID
IArchivingControl :: CurrentRetentionCategoryID
IArchivingControl :: IndexData
IArchivingControl :: FilterProperties
ILotusArchivingControl interface
ILotusArchivingControl :: Action
ILotusArchivingControl :: NoteHandle
ILotusArchivingControl :: DatabaseHandle
ILotusArchivingControl :: DatabaseName
ILotusArchivingControl :: SenderRecipientXML
ILotusArchivingControl :: StoreIdentifier
ILotusArchivingControl :: Direction
IFileArchivingControl interface
IFileArchivingControl :: Action
IFileArchivingControl :: Name
IFileArchivingControl :: Attributes
IFileArchivingControl :: CreationTimeUtc
IFileArchivingControl :: LastAccessTimeUtc
IFileArchivingControl :: LastWriteTimeUtc
IFileArchivingControl :: GetAccessControl
IFileArchivingControl :: SetAccessControl
IFileArchivingControl :: Length
IFileArchivingControl :: Open
IFileArchivingControl :: StreamNames
347
348
Filtering APIs
IFileArchivingControl :: OpenStream
IFileArchivingControl :: DeleteStream
IFileArchivingControl :: ExtendedAttributes
IIndexMetadata interface
IIndexMetadata :: ToXML
IIndexMetadata :: FromXML
IIndexMetadata :: Add
IIndexMetadata :: Clear
IIndexMetadata :: Count
IIndexMetadata :: DateTimesUTC
IIndexProperty interface
IIndexProperty :: Set
IIndexProperty :: Name
IIndexProperty :: Value
IIndexProperty :: Searchable
IIndexProperty :: Retrievable
IKeyedList interface
IKeyedList :: Insert
IKeyedList :: RemoveAt

This chapter describes the following APIs available for adding proprietary external
filters to Enterprise Vault archiving tasks:
Domino Filtering API
File System Filtering API
Filtering involves selecting specific items according to set criteria, and performing
certain actions on those items. Items may be selected using attributes such as
Filtering APIs
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
No generic filter is currently provided for file system filtering. If you want to
implement File System Filtering then you must create a filter using the File System
Filtering API.
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
Exchange Journaling task
Exchange Public Folder task
Both the Domino Filtering API and the File System Filtering API are presented as
a set of .NET interfaces. The Domino Filtering API can be used to develop
proprietary filters for Domino Journaling tasks. The File System Filtering API can
be used to develop proprietary filters for File System Archiving tasks.
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 323.
349
350
Filtering APIs
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:
See Exchange filtering registry settings on page 352.
See Domino filtering registry settings on page 394.
See File System filtering registry settings on page 395.
Restart the associated archiving tasks.
After you upgrade Enterprise Vault, you must update binding redirections in the
associated .NET application configuration files to use the newer version of the
Enterprise Vault API runtime. For File System filtering, the .NET application
configuration file is EvFSAArchivingTask.exe.config. For Domino filtering, the
.NET application configuration file is EVLotusDominoJournalTask.exe.config.
See Updating binding redirections in configuration files on page 54.
Details of the filtering APIs are given in the following sections:
See Exchange Filtering API on page 350.
See Domino Filtering and File System Filtering APIs on page 389.

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.
Filtering APIs
Figure 6-1
Overview of Exchange filtering
Enterprise Vault Server
Modified contents
Enterprise Vault
Exchange
Journaling
task
Enterprise Vault
Exchange
Mailbox task
Vault
store
Enterprise Vault
Exchange Public
Folder task
External
filter 1
External
filter 1
ProcessFilter()
Modified contents
Task Filter
Controller
External
filter 1
The figure, Figure 6-1, 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 IArchivingControl4 interface, which is implemented

by the task filter controller, to retrieve information about the message.
The filter processes the message synchronously, using the methods and
properties of the IArchivingControl4 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.
351
352
Filtering APIs
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
\Wow6432Node
\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
PublicFolder
Filtering APIs
For example, to add filtering for the Exchange Mailbox archiving tasks, you add
the Mailbox key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\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.
The following example shows three external filters that have been configured for
the Exchange Mailbox archiving tasks.
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\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.
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 (ProjectName.ClassName) of
the COM class implementing IExternalFilter for this particular filter, as defined
in the external filter class registration (.rgs) file. For example:
HKCR
{
EV10FilterVersion.SampleFilterClass.1 = s 'SampleFilterClass Class'
{
353
354
Filtering APIs
CLSID = s '{B5FFF252-D74C-4723-B812-41E15B4C57EF}'
}
EV10FilterVersion.SampleFilterClass = s 'SampleFilterClass Class'
{
CLSID = s '{B5FFF252-D74C-4723-B812-41E15B4C57EF}'
CurVer = s 'EV10FilterVersion.SampleFilterClass.1'
}
NoRemove CLSID
{
ForceRemove {B5FFF252-D74C-4723-B812-41E15B4C57EF} = s
'SampleFilterClass Class'
{
ProgID = s 'EV10FilterVersion.SampleFilterClass.1'
VersionIndependentProgID = s
'EV10FilterVersion.SampleFilterClass'
ForceRemove 'Programmable'
InprocServer32 = s '%MODULE%'
{
val ThreadingModel = s 'Apartment'
}
val AppID = s '%APPID%'
'TypeLib' = s '{24798ABC-A921-462a-9964-536E8C37E0A3}'
}
}
}
In the above example, you would use the following value in the filter registry
setting:
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
1 = EV10FilterVersion.SampleFilterClass.1
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.
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
\Wow6432Node
\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.
355
356
Filtering APIs
You can use Dtrace to trace the Enterprise Vault archiving task that is enabled
for external filtering. The following Dtrace filter options are useful for verifying
that external filtering is working as expected, and for diagnosing problems:
DT>f
Manage trace entry filter....(? for help)
DT Filter>v
Current Filter Settings:
Include strings:
ExternalFiltering
EVFilterController
For a description of the Dtrace utility, see the Enterprise Vault Utilities guide.

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,
Filtering APIs
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
};
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.
357
358
Filtering APIs
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
}
An external filter implements the following interface:
IExternalFilter
Syntax
interface IExternalFilter : IDispatch
Member summary
Table 6-1
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
Filtering APIs
(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.
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.
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.
359
360
Filtering APIs
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
See IArchivingControl :: MAPIMessage on page 369.
See IArchivingControl :: Action on page 368.
See IArchivingControl :: currentVaultId on page 365.
See IArchivingControl :: currentRetentionCategoryId on page 365.
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.

The task filter controller implements the following interfaces:
IArchivingControl
IArchivingControl2
Filtering APIs
IArchivingControl3
IArchivingControl4
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 theIArchivingControl2 interface and

adds properties to retrieve sender and recipient information as XML.
The IArchivingControl4 interface extends the IArchivingControl3 interface and
adds a new method that accepts a VARIANT data structure when specifying string,
integer and date custom index property values. This enables searching on
date-based selection criteria.
Syntax
interface IArchivingControl : IDispatch
interface IArchivingControl2 : IArchivingControl
interface IArchivingControl3 : IArchivingControl2
interface IArchivingControl4 : IArchivingControl3
Member summary
Table 6-2
IArchivingControl properties
Property
Read/Write
Description
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.
361
362
Filtering APIs
Table 6-2
IArchivingControl properties (continued)
Property
Read/Write
Description
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.
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.
Filtering APIs
Table 6-2
Property
Read/Write
Description
ReArchiveStatus
Read only
Indicates if current archiving

action is rearchiving an item
that has been restored from
the archive.
Table 6-3
IArchivingControl2 properties
Property
Read/Write
Description
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 6-4
IArchivingControl methods
Method
Description
AddIndexedProperty
Adds metadata to the item. The metadata will be

indexed.
This method is deprecated, and may not be
supported in a future release. Use
IArchivingControl4::AddIndexedPropertyEx to add
custom index properties.
AddIndexPropertyToSet
Adds custom index properties to a named custom

index property set. The custom index property
value is specified as a string.
363
364
Filtering APIs
Table 6-4
IArchivingControl methods (continued)
Method
Description
AddIndexPropertySet
Adds a named custom index 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 6-5
IArchivingControl2 method
Method
Description
MAPISaveChanges
Enables
changes to
the current
message to
be saved.
Table 6-6
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).
Table 6-7
IArchivingControl4 method
Method
Description
AddIndexedPropertyEx
Adds custom index properties to a named custom

index property set. The custom index property
value can be specified as a string, integer or date.
Filtering APIs
Version information
IArchivingControl2 properties and method are available in Enterprise Vault

7.0 and later. MessageClass and MAPISaveChanges are also available in
Enterprise Vault 6.0 SP5.
IArchivingControl3 properties are available in Enterprise Vault 6.0 SP5,

Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
IArchivingControl4::AddIndexedPropertyEx method is available in Enterprise

Vault 10.0.1 and later.
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
IArchivingControl :: currentRetentionCategoryId
The Enterprise Vault retention category to be assigned to the current item.
365
366
Filtering APIs
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
retention categories.
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.
Filtering APIs
Remarks
The defaultRetentionCategoryId property enables the external filter to get the
default retention category for the Enterprise Vault Site.
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.
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.
367
368
Filtering APIs
[out, retval] BOOL *pVal
Remarks
When the task is running in report mode the action is ignored.
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
See EV_ACTION enumeration on page 356.
The default action is to archive the item (ARCHIVE_ITEM enumeration value).
IArchivingControl :: MAPISession
This property returns a MAPI session for the current message.
Syntax
HRESULT MAPISession([out, retval] IUnknown **pUnkVal);
Filtering APIs
Parameters
[out, retval] IUnknown **pUnkVal
Pointer to MAPI session.
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
See IArchivingControl2 :: MAPISaveChanges on page 381.
IArchivingControl :: AddIndexedProperty
This method enables you to add a property to the custom index metadata for the
item.
Note: This method is deprecated, and may not be supported in a future release.
Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties.
See IArchivingControl4 :: AddIndexedPropertyEx on page 385.
369
370
Filtering APIs
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 add the property to a
named property set. This will also enable you to control whether the property is
searchable and retrievable.
This property lists the custom index properties that have been added to the item.
Syntax
HRESULT IndexedPropertiesSet([out, retval] BSTR *pVal);
Parameters
[out, retval] BSTR *pVal
Pointer to the XML list of properties.
Remarks
The properties are returned as XML which can be loaded into an
ISimpleIndexMetadata object using the FromXML method.
See ISimpleIndexMetadata :: FromXML on page 267.
Filtering APIs
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, 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.
371
372
Filtering APIs
This method adds a named custom property set.
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 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.
Property sets do not need to be created before properties are added to them.
Filtering APIs
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
See IArchivingControl :: RetryStatus on page 377.
See IArchivingControl :: ReArchiveStatus on page 378.
IArchivingControl :: AgentType
This property identifies the type of the current archiving task.
Syntax
HRESULT AgentType([out, retval] BSTR* pVal);
Parameters
Current archiving task type.
Remarks
The value can be one of the following:
373
374
Filtering APIs
IArchivingControl :: AgentAssignedRetentionCategoryId
Mailbox
Journaling
PublicFolder
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
Retention category Id.
Remarks
Use the Retention API to retrieve details of retention categories, and create new
retention categories.
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
Archive Id.
Filtering APIs
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.
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);
375
376
Filtering APIs
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.
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
Caution: This property is not currently supported.
Filtering APIs
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.
See EV_ATTACHMENT_ACTION enumeration on page 356.
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.
See EV_RETRY_STATUS enumeration on page 357.
See also
See IArchivingControl :: TransactionID on page 373.
See IArchivingControl :: ReArchiveStatus on page 378.
377
378
Filtering APIs
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.
See EV_REARCHIVE_STATUS enumeration on page 357.
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)
Filtering APIs
Parameters
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.
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
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);
379
380
Filtering APIs
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.
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
This property returns the MAPI Message Class for the current item.
Syntax
HRESULT MessageClass([out, retval] BSTR *pVal);
Filtering APIs
Parameters
[out, retval] BSTR *pValPointer 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
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.
381
382
Filtering APIs
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>
Filtering APIs
<DN>User1</DN>
</RC>
</DL>
</TO>
<CC/>
<BCC/>
</RECP>
<AUTH>
<FROM>
</FROM>
</AUTH>
</MSG>
</ARCHIVED_ITEM>
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.
383
384
Filtering APIs
Example
<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>
</TO>
<CC/>
<BCC>
<RC>
</RC>
</BCC>
<ENV>
<RC>
</RC>
</ENV>
</RECP>
<AUTH P1="true">
<FROM>
</FROM>
</AUTH>
</MSG>
</ARCHIVED_ITEM>
Filtering APIs
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.
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.
See Message direction enumeration on page 358.
This method lets you add a custom index property to an item before it is archived.
The method also lets you create the named property set to which the custom index
property is added.
You can specify the custom index property value as a string, integer, or date.
Specifying the property value as a date allows you to search on the custom index
property using date-based selection criteria, such as the date that the item was
archived (created) or modified by Enterprise Vault.
Syntax
HRESULT AddIndexedPropertyEx([in] BSTR setname,
[in] BSTR propname,
[in] VARIANT propvalue,
[in] VARIANT_BOOL searchable,
[in] VARIANT_BOOL retrievable)
385
386
Filtering APIs
Parameters
[in] BSTR setname
Name of the property set to which the property

is added. If the specified property set does not
exist, it is created.
[in] BSTR propname
[in] VARIANT propvalue
Value of the property. Table 6-8 lists the

supported variant types.
[in] VARIANT_BOOL searchable
Defines whether the property is added to the item

index. If the value is set to "VARIANT_TRUE", the
property is indexed.
[in] VARIANT_BOOL retrievable Defines whether the property values can be

requested in search results. If the value is set to
"VARIANT_TRUE", the property value can be
returned as part of the search results.
Remarks
Call the method repeatedly to add multiple properties, or add multiple values to
the same property.
Table 6-8 lists the supported variant types for propvalue.
Table 6-8
Supported types for propvalue
Value type
Variant type
Note
String
VT_BSTR
Datetime
VT_DATE

January 2038
Integer


4,294,967,294
to the Content Management API..
Filtering APIs
If you use Dtrace to trace the Enterprise Vault archiving task that is enabled for
external filtering, you can specify the following options to trace custom index
properties added using AddIndexedPropertyEx:
DT>f
Manage trace entry filter....(? for help)
DT Filter>v
Current Filter Settings:
Include strings:
ExternalFiltering
EVFilterController
IndexedPropertiesSet
Details of the custom index properties that are added using AddIndexedPropertyEx
are described using XML. The following is an example of the XML encoded custom
index property data generated using AddIndexedPropertyEx:
<ARCHIVED_ITEM version="1.0">
<MSG>
<PROPSETLIST>
<PROPSET NAME="PS_EX">
<PROP NAME="PV_STR" SEARCH="y" RESULTS="n">
<VALUE>Legal</VALUE>
</PROP>
<PROP NAME="PV_DATE" SEARCH="y">
<VALUE type="VT_DATE">2011-09-27T09:51:55Z</VALUE>
</PROP>
<PROP NAME="PV_INT" SEARCH="y" RESULTS="n">
<VALUE type="VT_I4">10</VALUE>
<VALUE type="VT_UI4">100</VALUE>
</PROP>
</PROPSET>
</PROPSETLIST>
</MSG>
</ARCHIVED_ITEM>
VALUE type attributes are only set for dateTime and integer value types. These
attributes are not set for the default value type, string.
387
388
Filtering APIs
SEARCH and RESULT attributes are set at PROP element level, not PROPSET
level. They are only present if the value is not the default value. The default values
for SEARCH and RESULT attributes are SEARCH = "n", RESULTS = "y".
dateTime values are specified in UTC "yyyy-mm-ddThh:mm:ssZ" format. No time
zone offset value is specified.
Return value
E_INVALIDARG
An unsupported property type has been specified, or the

value specified is not within the supported property value
range.
C++ examples
Adding a new searchable, non-retrievable, string value type custom index property:
HRESULT hr (S_OK);
CComPtr<IArchivingControl4>
spArchControl;
_variant_t varStr (L"Legal");

hr = spIArchControl->AddIndexedPropertyEx(_bstr_t(L"PS_EX"),
_bstr_t(L"PV_STR"),varStr, VARIANT_TRUE, VARIANT_FALSE);
Adding a new searchable, retrievable, date value type custom index property:
DATE dateNow = 0;
SYSTEMTIME stNow = {0};
::GetSystemTime(&stNow);
::SystemTimeToVariantTime(&stNow, &dateNow);
_variant_t varDate = _variant_t(dateNow,VT_DATE);
hr = spIArchControl->AddIndexedPropertyEx(_bstr_t(L"PS_EX"),
_bstr_t(L"PV_DATE"), varDate, VARIANT_TRUE, VARIANT_TRUE);
Adding a new searchable, non-retrievable, multi-valued, integer type custom index

property:
long lValue = 10;
hr = spIArchControl->AddIndexedPropertyEx((_bstr_t(L"PS_EX"),
_bstr_t(L"PV_INT"), _variant_t(lValue), VARIANT_TRUE,
Filtering APIs
VARIANT_FALSE);
ULONG ulValue = 100;
hr = spIArchControl->AddIndexedPropertyEx((_bstr_t(L"PS_EX"),
_bstr_t(L"PV_INT"), _variant_t(ulValue), VARIANT_TRUE,
VARIANT_FALSE);

The Domino Filtering and File System Filtering APIs are both presented as a set
of .NET interfaces. The APIs have the following interfaces in common:
IExternalFilter
IArchivingControl
The IFileArchivingControl and ILotusArchivingControl interfaces are derived
from IArchivingControl, and refine the interface for the different archiving
target stores.
IIndexMetadata
IIndexProperty
IKeyedList
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
389
390
Filtering APIs
Figure 6-2
Overview of Domino filtering
Enterprise Vault
Domino Journaling
task
Vault
store
Modified contents
External
filter 1
ProcessFilter()
Task Filter
Controller
Modified contents
The figure, Figure 6-2, 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.
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.
Filtering APIs
About the File System Filtering API

The File System Filtering API enables you to create external custom filters for
File System Archiving tasks. A filter defines how the File System Archiving task
selects and processes files. Files can be selected by matching one or more attributes,
such as file name or file type. Additional properties can be added to the Enterprise
Vault index for the file.
The action defined for the selected files can be one of the following:
Apply the policy that is associated with the volume or folder in which the file
is located.
Archive the file with or without creating a shortcut.
Archive the file and delete the original, without creating a shortcut.
Delete the file without archiving it.
Do not archive the file.
A filter can also request the archiving task to shut down.

Filtering can be used for a variety of reasons, such as being able to select which
files to archive, providing additional statistics on files, and adding proprietary
information to files that are archived by Enterprise Vault.
Filters can pass the selected file to a third-party application for additional
processing. For example, files can be passed to file classification or file decryption
applications. The filter can pass additional information to Enterprise Vault for
indexing, or alter the way the file is processed based on its classification.
Classification information added to files is then available to Enterprise Vault
search applications, such as Discovery Accelerator.
If a file that has already been archived is processed by a filter, the following actions
are not applied:
Modifying file properties, index properties or retention category.
File stream operations.
Only the following subset of filter actions can be applied when processing such
files:
Create a shortcut.
Delete the original file on the file server.
Stop the archiving task.
The File System Filtering API requires Enterprise Vault 10.0 or later.
391
392
Filtering APIs
Figure 6-3
Overview of file system filtering
File
C
I
F
S
Enterprise Vault
File System Archiving
task
File
Vault
store
Modified contents
cache
External
filter 1
ProcessFilter()
Task Filter
Controller
Modified contents
The figure, Figure 6-3, illustrates how Enterprise Vault implements file system
filters:
If the registry settings are configured to enable filtering for the File System
Archiving task, the archiving task calls the task filter controller when
processing a file in the file system archiving target.
The filter uses the methods and properties on the IFileArchivingControl

interface to retrieve information about the file. Methods and properties provide
the filter with access to the file contents or datastream.
The filter then processes the file. Methods and properties on the
IFileArchivingControl interface enable you to define how the archiving task
is to process the file.
If the filter makes any modifications to the file, the task filter controller ensures
that the modifications are saved back to the file on the file server using CIFS.
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 File System Archiving task then processes the file according to the
properties set by the external filters.
Filtering APIs
About file system filter reports

When external filters are configured for File System Archiving, information is
added to the File System Archiving task report file. The report files are located
in the Reports\FSA subfolder of the Enterprise Vault installation folder.
In the detailed information for each file processed, the Filter Modifications
column shows the filter actions that have been performed on the file. This
information is shown in the form:
[ filter_name - action, action, ... ] [ filter_name - action, action, ... ] ...
where filter_name is the name of the external filter, and action identifies the type
of filter action that the archiving task has performed. action can be one of the
following:
Applied filtering action The archiving task has performed the action defined
by the FSAAction enumeration value.
Modified file properties File attributes have been modified.
Modified index properties Index properties have been added or removed.
Performed file stream operation A file or alternate data stream has been
opened to read or write.
Applied retention category The retention category has been changed.
Summary information for each external filter is displayed in the report section,
External Filter Summary. The information shows the number of files or alternate
data streams on which the archiving task has performed each filter action. Failure
to load a filter is also reported in this section.
If files that have already been archived are processed by a filter, only the filtering
action can be applied. Therefore only Applied filtering action is reported for
these files.
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 and File System Filtering APIs must
reference the .NET assembly:
Symantec.EnterpriseVault.FilterInterfaces.dll
The API interfaces are loaded within the namespace:
393
394
Filtering APIs
Symantec.EnterpriseVault.FilterInterfaces
You can develop external filters in the programming language of your choice. For
clarity, definitions are given using C#.NET syntax.
An example file system filter in managed C# is provided in the SDK.
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.
To develop an external filter for File System Archiving, you need to obtain and
install an Enterprise Vault File System Archiving license.
Domino filtering registry settings

Filtering for Enterprise Vault Domino Journaling tasks is enabled on the Enterprise
Vault server using registry settings under the External Filtering key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\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 fully qualified filter class name for the new external filter:
PathToFilterAssembly!FilterClassName
A fully-qualified class name includes the namespace. For example, if the class
name is CustomFilter, the namespace is Symantec.EnterpriseVault.Domino,
and the filter is implemented in
Symantec.EnterpriseVault.DominoCustomFilter.dll assembly, then the value
of the registry setting should be as follows:
Symantec.EnterpriseVault.DominoCustomFilter.dll!
Symantec.EnterpriseVault.Domino.CustomFilter
Filtering APIs
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.
File System filtering registry settings

Filtering for Enterprise Vault File System Archiving tasks is enabled on the
Enterprise Vault server using registry settings under the External Filtering key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\KVS
\Enterprise Vault
\External Filtering
\File System
If either External Filtering or File Systemkeys do not exist, then you can create
them.
You create a new string entry for each filter under the File System 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 fully-qualified filter class name for the new external filter:
PathToFilterAssembly!FilterClassName
A fully-qualified class name includes the namespace. For example, if the class
name is CustomFilter, the namespace is Symantec.EnterpriseVault.FileSystem,
and the filter is implemented in
395
396
Filtering APIs
Symantec.EnterpriseVault.FileSystemCustomFilter.dll assembly, then the value

of the registry setting should be as follows:
Symantec.EnterpriseVault.FileSystemCustomFilter.dll!
Symantec.EnterpriseVault.FileSystem.CustomFilter
Note that the class name is case sensitive.

If the associated File System Archiving task is currently processing archiving
targets, you need to restart the task to implement changes to the registry settings.
You can use the XML configuration file, EVFSAArchivingTask.exe.config, to
control the behavior of the archiving task in the event of filter errors. The
configuration file is located in the Enterprise Vault installation folder.
You can add the following settings for file system filtering:
MoveOnFilterFailure. This setting controls the action taken by the archiving

task if it cannot load a filter. If the setting value is "0", then the archiving task
stops. If the setting value is "1", then the archiving task loads the next filter,
or continues to archive.
If the setting is not present in the configuration file, then the default value is
"0"; the archiving task stops if it cannot load the filter.
MaxFilterError. During archiving, the archiving task keeps a count of the

number of filtering errors reported. The MaxFilterError setting lets you
configure the maximum number of errors permitted before the archiving task
stops.
If the setting is not present in the configuration file, the default value is 100.
You need to edit the file and add a section called <FSAFilter> to hold the settings.
This section must also be declared in the <configSections> element. The settings
are added as key/value pairs.
The following example shows the file with the settings added:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSections>
<section name="FSAFilter"
type="System.Configuration.DictionarySectionHandler"/>
</configSections>
<FSAFilter>
Filtering APIs
<add key="MaxFilterError" value = "150"/>

<add key="MoveOnfilterFailure" value = "1"/>
</FSAFilter>
<runtime>
<generatePublisherEvidence enabled="false"/>
</runtime>
</configuration>
The settings in this example file have the following effect:
key="MaxFilterError" value = "150" The archiving task will stop if more

than 150 filtering errors are reported.
key="MoveOnfilterFailure" value = "1" If the archiving task cannot load a

filter, it will try to load the next filter, or continue to archive.

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,
397
398
Filtering APIs
MARK_DO_NOT_ARCHIVE = 2,
HARD_DELETE = 4,
REQUEST_SHUTDOWN = 5
}
Table 6-9
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 394.
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.

This section lists the enumerations for the File System Filtering API.
File System Archiving action enumeration

The following actions are supported by the filter controller. These actions can be
set by the external filter.
public enum FSAAction
{
DEFAULT_POLICYACTION
ARCHIVE_CREATESHORTCUT
ARCHIVE_DONOTCREATESHORTCUT
DONOTARCHIVE
DELETE
REQUEST_SHUTDOWN
=
=
=
=
=
=
0,
1,
2,
3,
4,
5,
Filtering APIs
ARCHIVE_DELETE
= 6
Table 6-10
FSAAction enumeration values
Value
Action
DEFAULT_POLICYACTION
(Default) Perform the action

specified in the policy that is applied
to the volume or folder in which the
file is located.
ARCHIVE_CREATESHORTCUT
Archive the file and create a

shortcut.
(Vault store backup properties are
honored).
ARCHIVE_DONOTCREATESHORTCUT
Archive the file and do not create a

shortcut.
DONOTARCHIVE
Do not archive the file. The file is

left in its original location.
DELETE
Delete the file without archiving it.
REQUEST_SHUTDOWN
Shut down the archiving task.
ARCHIVE_DELETE
Archive the file and delete the

original. No shortcut is created.
The external filter must implement the IExternalFilter interface, which is called
by the archiving task filter controller:
Namespace: Symantec.EnterpriseVault.FilterInterfaces
Assembly: Symantec.EnterpriseVault.FilterInterfaces.dll
Syntax
public interface IExternalFilter
399
400
Filtering APIs
Member summary
Table 6-11
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
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.
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);
Filtering APIs
Parameters
IArchivingControl archivingControl
Reference to the ILotusArchivingControl

or IFileArchivingControl 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
See ILotusArchivingControl interface on page 406.
See IFileArchivingControl interface on page 410.
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.
IExternalFilter :: Shutdown
This method is called during archiving task shutdown.
Syntax
void Shutdown();
401
402
Filtering APIs
Remarks
The filter should perform any necessary clean-up tasks.
This task filter controller implements the following interfaces:
IArchivingControl
ILotusArchivingControl
IFileArchivingControl
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 406.
The IFileArchivingControl interface is implemented by the File System archiving
task filter controller, and is passed to the filter on a per-item basis during the
ProcessFilter call. It extends the IArchivingControl interface to provide access to
file system archiving targets from file system archiving filters.
See IFileArchivingControl interface on page 410.
Syntax
public interface ILotusArchivingControl : IArchivingControl
public interface IFileArchivingControl : IArchivingControl
Member summary
Table 6-12
IArchivingControl properties
Property
Read/Write Description
OriginalVaultID
Read only
Original archive for the current item.
CurrentVaultID
Read/Write
Target archive for the current item.
Filtering APIs
Table 6-12
Property

Read/Write Description
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.
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.
In file system filtering, the value returned is the archive folder Id for the file.
IArchivingControl :: CurrentVaultID
This property retrieves or sets the ID of the archive in which the current item will
be stored.
In file system filtering, the value returned is the archive folder Id for the file.
In Domino filtering, this property is read/write.
In file system filtering, this property is read only. Attempts to set a value will
throw the exception, NotSupportedException.
Syntax
string CurrentVaultID {get; set;}
403
404
Filtering APIs
Exception
NotSupportedException
Setting this property is not supported by

File System Filtering.
Example
An example value for this property is:
190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1
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.
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
Filtering APIs
Exceptions
ArgumentNullException
Value specified is null.
ArgumentException
Value specified is empty, or does not

exist.
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
See IIndexMetadata interface on page 424.
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.
405
406
Filtering APIs
See also
See IKeyedList interface on page 431.
ILotusArchivingControl is derived from the IArchivingControl interface, and
extends the interface to enable filters to access Domino messages.
Member summary
Table 6-13
ILotusArchivingControl properties
Property
Read/Write
Description
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).
ILotusArchivingControl :: Action
This property defines the filtering action for the current message.
Syntax
DominoAction Action {get; set;}
Filtering APIs
Remarks
The filtering action is defined by the DominoAction enumeration.
See Domino action enumeration on page 397.
The default action is to archive the item (ARCHIVE_ITEM enumeration value).
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.
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.
ILotusArchivingControl :: DatabaseName
This property retrieves the current Domino journal database path.
407
408
Filtering APIs
Syntax
string DatabaseName {get;}
Remarks
This path is relative to the Data folder.
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>
Filtering APIs
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>
<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>
This property uniquely identifies the message.
409
410
Filtering APIs
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.
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.
See Message direction enumeration on page 397.
IFileArchivingControl interface
The IFileArchivingControl interface is derived from IArchivingControl, and refines
the interface for file system archiving targets.
Filtering APIs
Member summary
Table 6-14
IFileArchivingControl properties
Property
Read/Write
Description
Action
Read/Write
Retrieves or modifies the action

for the current item.
Name
Read/Write
Retrieves or modifies the file name

only.
Attributes
Read/Write
Retrieves or modifies the file

attributes.
LastWriteTimeUtc Read/Write
Retrieves or modifies the last

modified date (UTC) of the file.
LastAccessTimeUtc Read/Write
Retrieves or modifies the last

accessed date (UTC) of the file.
CreationTimeUtc
Read/Write
Retrieves or modifies the creation

date (UTC) of the file.
Length
Read only
Retrieves the size of the file.
ExtendedAttributes Read only
Retrieves the extended attributes

of the file.
StreamNames
Lists all alternate data streams.
Table 6-15
Method
Read only
IFileArchivingControl methods
Description
GetAccessControl Retrieves the access control of the file.

SetAccessControl
Modifies the access control of the file.
Open
Reads, writes and searches for the file contents (default stream).
OpenStream
Reads, writes and searches for the alternate data streams.
DeleteStream
Deletes an alternate data stream.
This property defines the filtering action for the current item.
411
412
Filtering APIs
Syntax
FSAAction Action {get; set;}
Value
Action
FSAAction enumeration value.
Remarks
The filtering action is defined by the FSAAction enumeration.
See File System Archiving action enumeration on page 398.
By default the action taken is the one defined in the policy for the folder or volume
in which the file is located.
Exception
ArgumentOutOfRangeException
Value specified is an invalid value for

FSAAction.
This property holds the file name of the current item, and can be used to rename
the file.
Syntax
string Name {get; set;}
Value
string FileName
File name of the current item.
Remarks
The value does not include the path to the file.
Filtering APIs
Exceptions
Value specified is null.
ArgumentException
A file with the specified name already

exists, or the filename specified includes
invalid characters. Filenames cannot
include any of the following characters:
/\:?<>|
PathTooLongException
The specified path, filename, or both

exceed the system-defined maximum
length. Filename cannot be more than
255 characters.
UnathorizedAccessException
The caller does not have the required

permission, or the path specified is
read-only.
FilterControllerException
For any other errors during the operation

(for example, an IO error). Inner
exception will provide information about
the actual error.
Example
string fileName = archivingControl.Name;
// rename file as fileName.txt
archivingControl.Name = fileName + ".txt";
This property provides the file attributes of the current item.
Syntax
System.IO.FileAttributes Attributes {get; set;}
Value
System.IO.FileAttributes Attributes
System.IO.FileAttributes
enumeration value.
413
414
Filtering APIs
Remarks
Setting the following file attributes is not supported:
Directory
Device
Offline
Temporary
Exceptions

read-only.
NoteSupportedException
One or more unsupported file attribute

has been specified: Device, Directory,
Offline, Temporary.

the actual error.
Example
This property provides the date and time (UTC) when the current item was created.
Syntax
System.DateTime CreationTimeUtc {get; set;}
Value
System.DateTime CreationTimeUtc
UTC datetime.
Filtering APIs
Exceptions
The value specified is outside the range

of dates, or times, or both, that are
permitted for this operation.

read-only, and the access is other than
read.

the actual error.
Example
This property provides the date and time (UTC) when the current item was last
accessed.
Syntax
System.DateTime LastAccessTimeUtc {get; set;}
Value
System.DateTime LastAccessTimeUtc UTC datetime
Exceptions


read.
415
416
Filtering APIs

the actual error.
Example
This property provides the date and time (UTC) when the current item was last
modified.
Syntax
System.DateTime LastWriteTimeUtc {get; set;}
Value
System.DateTime LastWriteTimeUtc
UTC datetime
Exceptions


read-only.

the actual error.
Filtering APIs
Example
This method returns the access control that is set on the current file. The method
uses the .NET Framework AccessControlSections enumeration in the
System.Security.AccessControl namespace.
Syntax
System.Security.AccessControl.FileSecurity GetAccessControl(
AccessControlSections includeSections);
Parameter
AccessControlSections includeSections
AccessControlSections
enumeration value.
Exception
NotImplementedException
Example
IFileArchivingControl :: SetAccessControl
This method sets the access control on the current file. The method uses the .NET
Framework AccessControlSections enumeration in the
System.Security.AccessControl namespace.
Syntax
void SetAccessControl(
System.Security.AccessControl.FileSecurity fileSecurity);
Parameter
System.Security.AccessControl.
FileSecurity fileSecurity
AccessControlSections
enumeration value.
417
418
Filtering APIs
Exceptions
NotImplementedException
Example
This property provides the size of the current file.
Syntax
System.UInt64 Length {get;}
Value
System.UInt64 Length
Size of file in bytes.
Example
This method is used to open the default stream for reading or writing. The method
uses the following .NET Framework enumerations in the System.IO namespace:
FileMode
enumeration
Defines constants for read, write, or read/write access to a file.
FileAccess
enumeration
Specifies how the operating system should open a file.
FileShare
enumeration
Contains constants for controlling the kind of access other FileStream

objects can have to the same file.
Syntax
System.IO.Stream Open(FileMode mode, FileAccess access,
FileShare share);
Filtering APIs
Parameters
FileMode mode
FileMode enumeration value.
FileAccess access
FileAccess enumeration value.
FileShare share
FileShare enumeration value.
Remarks
The following FileMode values are not supported:
FileMode.Create
FileMode.CreateNew
FileMode.OpenOrCreate
FileMode.Append
The FileShare value, FileShare.Inheritable, is not supported.
Exceptions
The value specified for FileMode,

FileAccess, or FileShare is invalid.
ArgumentException

read.

the actual error.
FileMode specified is one of Create,

CreateNew, OpenOrCreate, or
Append.
The FileAccess specified is read, and
the FileMode specified is Truncate or
Append.
419
420
Filtering APIs
Example
This property lists the names of alternate data streams.
Syntax
String[] StreamNames {get;}
Value
String[] StreamNames
Names of alternate data stream.
Exception
For any errors during the operation (for

example, an IO error). Inner exception
will provide information about the actual
error.
Example
string [] alternateDataStreams = archivingControl.StreamNames;
foreach (var v in alternateDataStreams)
{
// add code
}
This method is used to open an alternate data stream for reading or writing.
The method uses the following .NET Framework enumerations in the System.IO
namespace:
FileMode
enumeration
Defines constants for read, write, or read/write access to the stream.
Filtering APIs
FileAccess
enumeration
Specifies how the operating system should open the stream.
FileShare
enumeration
Contains constants for controlling the kind of access other filestream

objects can have to the same stream.
Syntax
System.IO.Stream OpenStream(FileMode mode,
FileAccess access,
FileShare share,
String streamName);
Parameters
FileMode mode
System.IO.FileMode enumeration value
FileAccess access
System.IO.FileAccess enumeration value
FileShare share
System.IO.FileShare enumeration value
string streamName
Name of alternate data stream
Remarks
The FileShare value, FileShare.Inheritable, is not supported.
Exceptions
The stream name specified is null.
The value specified for FileMode,

FileAccess or FileShare is invalid.
ArgumentException
The FileAccess value specified is read,

and the FileMode specified is Truncate
or Append.

read.
421
422
Filtering APIs

the actual error.
Example
string [] alternateDataStreams = archivingControl.StreamNames;
foreach (var v in alternateDataStreams)
{
using(Stream ads = archivingControl.Open(FileMode.Open,
FileAccess.Read, FileShare.Read, v))
{
long bytesInAds = ads.Length;
}
}
This method is used to delete an alternate data stream.
Syntax
bool DeleteStream(string streamName);
Parameters
string streamName
Name of alternate data stream
Exceptions
The stream name specified is null.
ArgumentException
The stream name is empty, or has invalid

characters.

read-only.
Filtering APIs

the actual error.
Example
bool deleted = archivingControl.DeleteStream("adsName");
This property returns a name/value pair for the extended attributes that exist on
the file.
Syntax
System.Collections.Generic.Dictionary<String, String>
ExtendedAttributes {get;}
Parameters
ExtendedAttributes
Name/value list.
Exception
For any errors during the operation (for

example, an IO error). Inner exception
will provide information about the actual
error.
Example
Dictionary<string, string> extendedAttribs =
archivingControl.ExtendedAttributes;
foreach (var v in extendedAttribs)
Console.WriteLine("EA Name:" + v.Key + "EA Value:" + v.Value);
423
424
Filtering APIs
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 6-16
IIndexMetadata properties
Property
Read/Write
Description
DateTimeUTC
Read/Write
Whether date and time properties

are UTC or local system time.
Table 6-17
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 428.
Filtering APIs
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
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.
425
426
Filtering APIs
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
string propertyName
string propertyValue
DateTime propertyValue
long propertyValue
ulong propertyValue
Property value.
bool propertySearchable
Whether property can be searched for using Search

API.
bool propertyRetrievable
Whether property can be retrieved and displayed in

search results.
Filtering APIs
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.
Table 6-18 lists the supported variant types for propertyValue.
Table 6-18
Supported types for propertyValue
Value type
Variant type
Note
String
VT_BSTR
Datetime
VT_DATE

range of 1st January 1970 to
1st January 2038
Integer


4,294,967,294
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.
427
428
Filtering APIs
This method clears all properties from the IIndexMetadata object for the current
item.
Syntax
void Clear();
IIndexMetadata :: Count
This method retrieves the number of properties in the IndexMetadata object for
the current item.
Syntax
int Count();
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.
The IIndexProperty interface details a a custom index metadata property within
an IIndexMetadata collection.
Filtering APIs
Syntax
public interface IIndexProperty
Member summary
Table 6-19
IIndexProperty properties
Property
Read/Write
Description
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);
}
}
429
430
Filtering APIs
This property holds the name of the property set.
Syntax
string Set {get;}
IIndexProperty :: Name
This property holds the name of the custom index property.
Syntax
string Name
{get;}
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() ==
Filtering APIs
typeof(DateTime)))
{
searchableDateProps.Add(prop.Set, prop.Name,
(DateTime)prop.Value);
}
}
This property indicates whether the property can be returned in search results
when using the Search API.
Syntax
bool Searchable {get;}
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;}
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
431
432
Filtering APIs
Member summary
Table 6-20
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
See IArchivingControl :: FilterProperties on page 405.
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
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.
433
434
Filtering APIs
Chapter
Search API
About Search API
About storing data in Enterprise Vault
Introduction to Enterprise Vault indexing
Using the Search API
Constants and enumerations
SearchQuery object
ISearchQuery :: Query
ISearchQuery :: Clear
ISearchQuery :: SetTerm
ISearchQuery :: AddTerm
ISearchQuery :: SetRange
ISearchQuery :: AddRange
ISearchQuery :: SetProperty
ISearchQuery :: AddProperty
ISearchQuery :: AddOp
ISearchQuery :: Combine
ISearchQuery :: AddQuery
ISearchQuery2 :: SetPropertyRange
436
Search API
ISearchQuery2 :: AddPropertyRange
IndexSearch object
IIndexSearch2 :: IndexVolumeSets
IIndexSearch2 :: Options
IIndexSearch2 :: SortBy
IIndexSearch2 :: ResultsPropertySet
IIndexSearch2 :: AdditionalResultsProperties
IIndexSearch2 :: Timeout
IIndexSearch2 :: ArchiveEntryId
IIndexSearch2 :: ArchiveName
IIndexSearch2 :: HasFolders
IIndexSearch2 :: IndexVolumeSetIdentity
IIndexSearch2 :: IndexVolumeIdentity
IIndexSearch2 :: IndexVolumeSetCount
IIndexSearch2 :: MaxSearchIndexVolumeSets
IIndexSearch2 :: MaxSearchResultsPerVolumeSet
IIndexSearch2 :: SelectArchive
IIndexSearch2 :: ListIndexVolumeSets
IIndexSearch2 :: SelectIndexVolumeSet
IIndexSearch2 :: SelectIndexVolume
IIndexSearch2 :: Search
IIndexSearch2 :: SearchToXML
IIndexSearch2 :: AddAdditionalResultsProperty
IIndexSearch2 :: AddAdditionalResultsCustomProperty
IIndexSearch2 :: Reset
IndexVolumeSets object
IIndexVolumeSets :: ArchiveEntryId
Search API
IIndexVolumeSets :: ArchiveName
IIndexVolumeSets :: HasFolders
IIndexVolumeSets :: Count
IIndexVolumeSets :: _NewEnum
IIndexVolumeSets :: Item
IndexVolumeSet object
IIndexVolumeSet :: Identity
IIndexVolumeSet :: ArchiveEntryID
IIndexVolumeSet :: ArchiveName
IIndexVolumeSet :: FirstItemIndexSequenceNumber
IIndexVolumeSet :: OldestArchivedDate
IIndexVolumeSet :: YoungestArchivedDate
IIndexVolumeSet :: OldestItemDate
IIndexVolumeSet :: YoungestItemDate
IIndexVolumeSet :: DateTimesUTC
SearchResults object
ISearchResults :: Results
ISearchResults :: Count
ISearchResults :: Total
ISearchResults :: Start
ISearchResults :: Options
ISearchResults :: SortBy
ISearchResults :: _NewEnum
ISearchResults :: Item
ISearchResults2 :: InSync
ISearchResults2 :: TruncationReason
ISearchResults2 :: DateTimesUTC
437
438
Search API
About Search API
ISearchResults2 :: LoadResults
SearchResult object
ISearchResult :: Result
ISearchResult :: Number
ISearchResult :: Prop
ISearchResult :: Prop2
ISearchResult2 :: Count
ISearchResult2 :: Item
ISearchResult2 :: DateTimesUTC
About Search API

This chapter describes the Search API, which enables third-party applications to
search the indexes of Enterprise Vault archives.
About storing data in Enterprise Vault

The Enterprise Vault Storage service accepts items for archiving from the archiving
tasks. If a suitable converter is available for the file type, a text or HTML version
of each item is generated. The text or HTML version is used for indexing, and to
provide a version of the item that can be viewed in a browser, if required. The
Storage service compresses and stores the items (and the converted content) as
savesets in the appropriate archives. Archives are grouped in vault stores.
Information about each item that is archived is stored in the vault store database.
The Storage service interoperates with the Index Servers to manage the indexes
of archived data, and also responds to requests from the archiving tasks to retrieve
items.
The content and attachments are indexed provided there is a content converter
available for the file type, and the converted content for the item as a whole
(including attachments) does not exceed 100 MB.
If the content cannot be indexed, a "content missing" reason is indexed using the
"comr" property.
See ETruncationReason enumeration on page 461.
Search API

Index Servers create and manage the indexes for archived data. This section
provides an introduction to Index Servers, archive indexes, and the indexing
configuration options.
Index Servers and Index Server groups

The role of the Index Server can be summarized as follows:
On instruction from the Storage service, the Index Server indexes items. This
can be as the items are archived, or later, depending on how the administrator
has configured indexing.
In response to search requests from the Enterprise Vault Web Server, or

third-party search applications using the Search API, the Index Server searches
the indexes and returns information about the archived items that match the
search criteria.
The Index Server ensures that indexes are complete, and automatically updates
the index every hour.
Index Servers can be standalone, or in Index Server groups. Figure 7-1 shows a
standalone Index Server configuration. An Index Server can only be standalone
if the Storage service and Index Server are collocated on an Enterprise Vault
server.
Figure 7-1
Standalone Index Server
Enterprise Vault server 1

Storage service
Index Server
Server 1 index
locations
Vault
stores
Index Server groups provide load-balanced indexing services for large or

distributed Enterprise Vault environments. In a distributed environment, some
Enterprise Vault servers may host Storage services, while others host Index
Servers. Figure 7-2 shows an example of this environment.
439
440
Search API
Figure 7-2
Enterprise Vault
server 1
(storage only)
Journal
vault
stores
Enterprise Vault
server 2
(storage only)
Journal
vault
stores
Enterprise Vault
server 3
(storage only)
Mailbox
vault
stores
Index Server groups in a distributed environment

Journal index
group
Enterprise Vault
server 5
(Indexing only)
Server 5 index
locations
Index Server
Enterprise Vault
server 6
(Indexing only)
Server 6 index
locations
Index Server
Mailbox index
group
Enterprise Vault
server 7
(Indexing only)
Server 7 index
locations
Index Server
Enterprise Vault
server 4
(storage only)
Mailbox
vault
stores
Enterprise Vault
server 8
(Indexing only)
Server 8 index
locations
Index Server
Using the Enterprise Vault Administration Console, the administrator performs

the following tasks:
Creates Index Server groups, and add to each group Index Servers on different
Enterprise Vault servers.
Assigns physical index locations to each Index Server.
Assigns each vault store to either a standalone Index Server, or an Index Server
group. The Index Servers in a group share the task of indexing the items stored
in the archives in the vault stores assigned to the group.
Search API
About index volumes

The index for an archive comprises one or more sequential index volumes. Each
index volume contains index entries for the items stored in the archive. Each
index volume is contained within an index volume set. An index volume set
contains only one index volume.
Typically, a user mailbox index requires only one or two volumes. Indexes for
larger archives, such as file system archives and journal archives, are likely to
have multiple volumes.
When an index volume is full, the Index Server automatically creates a new index
volume (in a new index volume set). The location selected for new index volumes
depends on whether the vault store is managed by a single Index Server or an
Index Server group.
If the vault store is indexed by an Index Server group, the index volumes for an
archive may be distributed across multiple Index Servers and locations, as shown
in Figure 7-3. In general, when the index for a mailbox rolls over, the existing
Index Server is used, if possible. The index location is selected using a round robin
algorithm, to balance the load across all index locations. For larger archives, such
as journal archives, new volumes are distributed evenly across the Index Servers
and index locations.
When a user or application performs a search on an archive, the search is
performed on index volumes associated with the archive, not on the archive itself.
441
442
Search API
Figure 7-3
Spread of index volumes in an Index Server group

Journal index group
Server 5 index locations
containing index volumes
Enterprise Vault
server 1
Journal
vault
stores
Archive A Archive A
index
index
volume 1 volume 2
Journal
archive A
Archive A Archive B
index
index
volume 3 volume 1
Enterprise Vault
server 2
Journal
vault
stores
Server 6 index locations

containing index volumes
Journal
archive B
Archive A
index
volume 4
Archive B
index
volume 2
Archive A
index
volume 5
Archive B
index
volume 3
About indexing options

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 two levels of indexing:
brief and full:
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.
Full indexing. This enables users to search as for brief indexing, and also
provides content searching.
Search API
Obviously, the more information that is indexed, the more disk space is required
for the index.
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 142.
See IArchive :: IndexUrgency on page 140.
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.
How Enterprise Vault processes sender and recipient details in different types of
messages is described in an appendix to this guide.
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 using the Content Management API or the Filtering
APIs.
In the Content Management API, use the methods on the ISimpleIndexMetadata

interface.
See IArchiveMetaData :: IndexData on page 236.
In the Exchange Filtering API, use the method IArchivingControl4 ::

AddIndexedPropertyEx. Custom filtering is available for Exchange Mailbox
Archiving Tasks, Exchange Public Folder Tasks and Exchange Journaling Tasks.
In the Domino Filtering API and File System Filtering API, use the Add method
in the IndexMetadata class.
Granularity of search results

In Enterprise Vault 10 and later, searches are performed using item granularity.
When an item is indexed, there is a single index document for the top-level item
443
444
Search API
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 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.
In releases before Enterprise Vault 10 the default indexing schema implemented
was attachment granularity. With attachment granularity, an index document
was created for the top-level item (such as a message), and separate index
documents were created for each attachment; each nested message and attachment
was stored in a separate index document. Searches returned both top-level items
and individual attachments.
In Enterprise Vault 9 and earlier releases, you could configure Enterprise Vault
to use the item granularity schema by configuring the registry setting,
SchemaType, in the following location:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\Indexing
However, this only tended to be configured on large systems that performed very
complex searching, such as those performed by Symantec Compliance and
Discovery Accelerator products.
Searches on index volumes that use different schemas may behave differently.
The differences can be summarized as follows:
Attachment granularity searches (32-bit indexes only). Results may contain

both top-level items and attachments. 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.
Item granularity searches (64-bit indexes, and 32-bit indexes where

SchemaType registry setting was configured). Only the top level item is
returned when an attachment matches the criteria. No indication is given as
to which attachment matches the criteria.
Searches for terms that are combined using AND may return more results
than were returned with the attachment granularity schema. This is because
index data for an item and any attachments are stored in the same index
document. A search for for "John Doe" AND "Widgets Corp" may return an
Search API
item which has "John Doe" in attachment 1, and "Widgets Corp" in attachment
3.
Searching across indexes that have been created using different granularity
schemas is supported on Enterprise Vault 10 and later.

For programming notes on using Enterprise Vault APIs with .NET managed code,
and information about code samples in this manual, see the "Programming notes"
section.
All the components required for using the Search API are contained in
IndexClient.dll.
SearchQuery object is used to construct search queries.
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).
Briefly, the process of using the Search API is 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 446.
Get an instance of the IndexSearch2 object and submit the search by calling
the Search method of IndexSearch2 interface.
This returns a SearchResults object, which in turn is used get SearchResult

object instances for each of the search hits returned in the SearchResults
445
446
Search API
object. (You do not have to obtain or create the SearchResults or SearchResult

objects).
See Processing the search results on page 452.
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
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 1970 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 1970 and 17th May 2001")
The property name, for example, Author, would normally be one of the Enterprise
Vault system index property names.
In addition to system property names, custom properties defined by the user can
also be used.
Search API
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.
The search query flag determines how to process individual terms added to a
search query.
See ESearchQueryFlags enumeration on page 458.
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 478.
The operator itself can be obtained from the ESearchQueryOperators enumeration.
447
448
Search API
See ESearchQueryOperators enumeration on page 459.

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 1970, 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 448.
ESQfilter searches
ESQfilter is similar to ESQ but more powerful. The following summarizes how
this operator works:
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.
Search API
This type of search is particularly efficient for compliance or discovery type

searches.
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.
When searching indexes created before Enterprise Vault 10, 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.
449
450
Search API
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 451.
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 448.
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.
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.
Search API
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.
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.
451
452
Search API
See IndexSearch object on page 485.
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.
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.
When searching indexes created by Enterprise Vault 10.0 or later, results include
top level items only.
When searching indexes created before Enterprise Vault 10.0, results may include
attachments and top-level items. However, only top-level items are returned in
results for these indexes if any of the following are configured:
Searching is limited to top-level items using roItemGranularity option in the

Search method.
The search query includes the ESQfilter operator. Attachments are searched
but the associated top-level item is returned in results.
The ItemGranularityOnly index schema was enabled when the index was
created. 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.
Search API
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

When using the Search API, Enterprise Vault property names are defined as
constants in the form IndexPropXXXX.
See Index Property constants on page 457.
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.
When searching using date search criteria, the date range values that can be
returned in search results are limited to the UTC date range 1st January 1970 to
1st January 2038. Items that are indexed with dateTime properties earlier than 1
Jan 1970 are returned in the index search results, but the retrieved date values
defaults to 1 Jan 1970. Items that are indexed with dateTime properties later than
1 Jan 2038 are also returned in the index search results, but the retrieved date
values defaults to 1 Jan 2038.
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.
453
454
Search API
The second method, DoSearch, is then called. DoSearch takes two parameters:
the IndexSearch2 object created in SearchArchive, and the maximum number of
search results. If the search is not a federated search, 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.
Search API
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.
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
455
456
Search API
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;
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;
Search API
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;
start += 500;
}
while (count != 0);
Marshal.FinalReleaseCOMObject(query);
}

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.
457
458
Search API
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.0, 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.0 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)
ESQexact
= 7, // Field exactly matches all the words, in order
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
ESQutcdate
=128, //Datetime should be interpreted as UTC rather

than local
Search API
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
459
460
Search API
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.
See IIndexSearch2 :: AddAdditionalResultsProperty on page 517.
See IIndexSearch2 :: AddAdditionalResultsCustomProperty on page 518.
enum EPropertySets
{
psEmpty = 0,
psWABrief = 1, default
psWAMedium = 2,
psWAFull = 3,
psAEMailbox = 4,
psAEFSA = 5,
psAESPS = 6,
Search API
psAEMultiFolders = 7,
psCompliance = 8,
psItemIds = 9,// Min set of ids needed to retrieve the item.
psAEShared = 10,
psAEJournal = 11,
psAEPublicFolder = 12,
psAESharePoint = 13
};
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://www.symantec.com/docs/TECH52355.
EXMLResultsFormatOptions enumeration
EXMLResultsFormatOptions enumerates the XML format option values. Currently
there is only one value:
enum EXMLResultsFormatOptions
{
461
462
Search API
SearchQuery object
xoNone = 0x00000000// default

};
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
Table 7-1
SearchQuery properties
Property
Read/Write
Description
ISearchQuery ::
Query
Read/Write
The search query string.
Table 7-2
SearchQuery methods
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.
Search API
SearchQuery object
Table 7-2
SearchQuery methods (continued)
Method
Description
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.
ISearchQuery2 :: Equivalent of SetRange method. Enables use of date and integer ranges
SetPropertyRange for custom properties in queries.
ISearchQuery2 :: Custom property equivalent of AddRange method. Enables use of date
AddPropertyRange 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.
There are restrictions on the date range that can be returned in search results.
See Enterprise Vault index properties on page 453.
Requirements
463
464
Search API
CLSID
B94D399B-B815-11D1-90D2-0000F87A3B5E
Prog ID
EnterpriseVault.IndexSearch
Type Library
EVIndexClient
DLL
IndexClient.dll
.NET Primary
Interop Assembly
(PIA)
KVS.EnterpriseVault.Interop.Indexclient.dll
.NET PIA
namespace
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.
[C#]
public class SampleSearchClass
{
private ISearchQuery2 query = (ISearchQuery2)
new SearchQuery();
//rest of the class
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.
Search API
[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, "");
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
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.
465
466
Search API
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();
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
Search API
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.
The parameter lFlags must contain one ESearchQueryFlags enumeration value.
This value may be bitwise OR'd (C++ operator "|") with one or more values from
the extended values.
bsProp can be a custom index property that has been added using the Content
Management API, or one of the Filtering APIs. 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.
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);
467
468
Search API
//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
See ISearchQuery :: AddTerm on page 468.
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 7-3
AddTerm method parameters
Parameter
Description
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.

terms added to the search
query.
Search API
Table 7-3
AddTerm method parameters (continued)
Parameter
Description
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, all indexed properties are searched for the
value. This is really only useful for string values.
This value may be bitwise or'd (C++ operator "|") with one or more values from
the extended values.
format:
Return value
rvS_OK
Success.
Example
In this example, a query is constructed that finds all items where the subject
contains the phrase "some subject" and the number of attachments is 1. The return
value is not used.
[C#]
469
470
Search API
//search for an item where the subject contains the phrase "some subject"
//now we AND the two terms so that both terms must be satisfied before returning a result
See also
See ISearchQuery :: SetTerm on page 466.
See ISearchQuery :: AddProperty on page 476.
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.
Search API
Search Query Flags that define

how to process the range
added to the search query.

Remarks
vVal1 and vVal2 must be the same type.
Currently, however, none of the Search Query Flags has any effect on range
searches.
This method can only be used with date or integer values.
When specifying dateTime values, it is strongly recommended that you set
ESearchQueryFlags.ESQutcdate and supply UTC dateTime values.
If ESearchQueryFlags.ESQutcdate is not set, dateTime values are treated as local
system dateTime.
format:
Return value
rvS_OK
Success.
471
472
Search API
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.
//search for all items archived between 01/01/2008 and 31/10/2008 inclusive
DateTime from = new DateTime(2008, 1, 1, 0, 0, 0, DateTimeKind.Utc);
DateTime to = new DateTime(2008, 10, 31, 23, 59, 59, DateTimeKind.Utc);
query.SetRange("adat",
from,
to, (
int)(ESearchQueryFlags.ESQany | ESearchQueryFlags.ESQutcdate));
//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
See ISearchQuery :: AddRange on page 472.
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.
Search API
[in] VARIANT vVal2
The upper or lower boundary

of the range. This can be date
or integer.

how to process the range added
to the search query.

Remarks
This method can only be used with date/time or integer values.
searches.
When specifying dateTime values, it is strongly recommended that you set
ESearchQueryFlags.ESQutcdate and supply UTC dateTime values.
If ESearchQueryFlags.ESQutcdate is not set, dateTime values are treated as local
system dateTime.
format:
473
474
Search API
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
See ISearchQuery :: SetRange on page 470.
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,
Search API
Parameters
[in, string] const BSTR bsPropSet
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.

range added to the search
query.
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.
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.
475
476
Search API
[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
See ISearchQuery :: SetTerm on page 466.
See ISearchQuery :: AddProperty on page 476.
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
The name of the custom

property to search for.
Search API
[in] VARIANT vVal
VARIANT containing value for

which for which to search. This
can be a string, date or integer.

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.
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)(
477
478
Search API
//the custom property Instrument.Type and "red" in Instrument.Colour"
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQand);
See also
See ISearchQuery :: AddTerm on page 468.
See ISearchQuery :: SetProperty on page 474.
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
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.
Search API
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.
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 example the
return value is not used.
[C#]
//search for an item where the subject contains the phrase "some subject"
//now we AND the 2 terms so that both terms must be satisfied before returning a result
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.
479
480
Search API
Second query to add.
[in] const long lOp

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.
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
Search API
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);
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
String containing the query to combine

with the one in the current object.
[in] const long lOp

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.
481
482
Search API
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.
[C#]
string qry = query.SetTerm("cont", "-white blue.red",
(int)ESearchQueryFlags.ESQany);
query2.AddQuery(qry, (int)ESearchQueryOperators.ESQand);
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 Content
Management API, or one of the Filtering APIs.
Syntax
HRESULT SetPropertyRange([in, string] const BSTR bsPropSet,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
Parameters
String containing the name of

the property set.
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.
Search API

Pointer to a string that will

contain the query string
formed by this method.
Remarks
Currently, none of the Search Query Flags has any effect on range searches.
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
See ISearchQuery2 :: AddPropertyRange on page 484.
483
484
Search API
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 Content
Management API, or one of the Filtering APIs.
Syntax
HRESULT AddPropertyRange([in, string] const BSTR bsPropSet,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
Parameters
String containing the name of

the property set.
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.

how to process the range
added to the search query.
Pointer to a string that will

contain the query string
formed by this method.
Search API
IndexSearch object
Remarks
searches.
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
See ISearchQuery2 :: SetPropertyRange on page 482.
IndexSearch object
IndexSearch object implements the following interface:
IIndexSearch2
485
486
Search API
IndexSearch object
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
Table 7-4
IndexSearch properties
Property
Read/Write
Description
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 460.
See Remarks below.
AdditionalResultsProperties
Read/Write
A space separated list of properties

returned in the search results in
addition to those in the selected
results property set.
Timeout
Read/Write
Gets or sets the timeout period, in

seconds, applied to search requests.
ArchiveEntryId
Read only
Gets the Id of the currently selected

archive.
Search API
IndexSearch object
Table 7-4
IndexSearch properties (continued)
Property
Read/Write
Description
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 IIndexSearch2 ::
SelectIndexVolumeSet on page 508.
MaxSearchResultsPerVolumeSet Read/Write
Table 7-5
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.
IndexSearch methods
Method
Description
SelectArchive
Sets the Id of the archive to be searched.
ListIndexVolumeSets
Returns as an XML document the index volume

set collection for the selected archive.
487
488
Search API
IndexSearch object
Table 7-5
IndexSearch methods (continued)
Method
Description
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.
See Remarks below.
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
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.
See IIndexSearch2 :: IndexVolumeIdentity on page 500.
Example
The object, "search", constructed in this example will be used in 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
See IndexVolumeSets object on page 519.
See IndexVolumeSet object on page 527.
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);
489
490
Search API
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.
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");
{
DoSearch(search);
}
This property sets or returns search option flags that define the granularity of
search results.
Search API
Syntax
HRESULT Options([in] long options,
[out,retval] long* options);
Parameters
[in] long options
EOptionsFlags value defining required granularity of

search results.
See EOptionsFlags enumeration on page 460.
[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.
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;
if (eof == EOptionsFlags.roAttachmentGranularity)
{
//do something
}
else //do something else
This property is used to order the returned search results.
491
492
Search API
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

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
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 460.
[out,retval] long* propertySet
Pointer to a long integer that will receive

the current value.
Remarks
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.
Example
As this property is no longer the recommended way of setting the returned
properties, it is set to "empty".
493
494
Search API
[C#]
[in]
search.ResultPropertySet = (int)EPropertySets.psEmpty;
[out]
if (search.ResultPropertySet != 0)
{
search.ResultPropertySet = 0; // (psEmpty)
}
See also
See IIndexSearch2 :: AdditionalResultsProperties on page 494.
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.
Search API
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.
See EPropertySets enumeration on page 460.
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.
[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
See IIndexSearch2 :: ResultsPropertySet on page 493.
This property defines the timeout period applied to search requests.
495
496
Search API
Syntax
HRESULT Timeout([in] long seconds,
[out,retval] long* seconds);
Parameters
Long integer containing number of seconds to wait
before the search times out. The default value is 120
seconds.
[in] long seconds
[out,retval] long* seconds Pointer to a long integer that will receive the current
value.
Remarks
For searches on indexes created using Enterprise Vault 9.0 or earlier, the timeout
period is only applied to federated search requests (that is, searches across multiple
index volume sets).
For searches on indexes created using Enterprise Vault 10.0 or later, the timeout
period is applied to all search requests.
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 < 120)
{
search.Timeout = 120;
}
Search API
This property returns the ID of the archive that is currently selected for searching.
Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value)
Parameters
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;
IIndexSearch2 :: ArchiveName
This property returns the name of the archive that is currently selected for
searching.
497
498
Search API
Syntax
HRESULT ArchiveName([out,retval] BSTR* value);
Parameters
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;
This property indicates whether the currently selected archive contains a folder
structure.
Search API
Syntax
HRESULT HasFolders([out,retval] VARIANT_BOOL* value);
Parameters
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
This property identifies the volume set of the index volume to search.
Syntax
HRESULT IndexVolumeSetIdentity([out,retval] long* value);
499
500
Search API
Parameters
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

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);
This property should not be used: it is currently available for Enterprise Vault
internal purposes only.
Syntax
HRESULT IndexVolumeIdentity([out,retval] long* value);
Search API
Parameters
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).
rvE_POINTER
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.
501
502
Search API
Return value
rvS_OK
Success.
rvS_FALSE
SelectArchive has not been called.
rvE_POINTER

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
{
}
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);
Search API
503
Parameters
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.
rvE_POINTER
Example
[C#]
if (count <= 10)
{
}
else
504
Search API
{
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
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.
rvE_POINTER
Search API
505
Example
[C#]
if (count <= 10)
{
search.MaxsearchResultsPerVolumeSet = 500;
}
else
{
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.
You can find out the ID of an archive by performing a search.
506
Search API
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
Assume that there is a populated IArchives object, "archives".
[C#]
{
search.SelectArchive(archive.Id);
}
See also
See IIndexSearch2 :: Search on page 511.
See IIndexSearch2 :: SearchToXML on page 514.
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);
Search API
Parameters
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:
[in] BSTR processingInstruction
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.
The archive Id has not been set.
Example
[C#]
e1");
string volSetsXML = search.ListIndexVolumeSets("xml-stylesheet
507
508
Search API
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
See IIndexSearch2 :: IndexVolumeSets on page 489.
This method selects an index volume set when searching an index with multiple
index volume sets.
Search API
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
federated search will be carried out across all index volume sets in the archive.
However, if the number of index volume sets exceeds the number set by
MaxSearchIndexVolumeSets (default is 5), this property must be set to determine
which index volume set to search, otherwise the Search API will return an error,
rvINDEXING_E_TOO_MANY_VOLUMES.
See IIndexSearch2 :: MaxSearchIndexVolumeSets on page 502.
Index volume set Ids can be obtained using the ListIndexVolumeSets method.
See IIndexSearch2 :: ListIndexVolumeSets on page 506.
Return value
rvS_OK
Success.
rvE_INVALIDARG
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.
509
510
Search API
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, "");
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.
Search API
Return value
rvS_OK
Success.
rvE_INVALIDARG
rvINDEXING_W_UNKNOWN_INDEX_VOLUME
This method submits the search request and returns a search results object.
See SearchResults object on page 536.
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 "".
511
512
Search API
[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 462.
Each search starts a new search in the Indexing server.
The startResult 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.
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
Search API
rvINDEXING_E_SERVICE_STOPPING
rvINDEXING_E_ARCHIVE_NOT_SET
INDEXING_W_CANT_ACCESS_DIRECTORY
rvINDEXING_W_ARCHIVE_BEING_DELETED
The selected index volume is not

known.
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
//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 "".
513
514
Search API
See also
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"
Search API
[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
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.
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.
Return value
rvS_OK
Success.
rvE_POINTER
The pointer to the IUnknown

pointer passed is the fifth
parameter is invalid.
rvE_ACCESSDENIED
515
516
Search API
rvE_NOINTERFACE
rvINDEXING_SERVER_STOPPING
rvINDEXING_E_SERVICE_STOPPING
rvINDEXING_E_ARCHIVE_NOT_SET
INDEXING_W_CANT_ACCESS_DIRECTORY
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
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
517
518
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
See also
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();
}
IIndexVolumeSets
This interface provides a set of properties than can used to manage a collection
of index volume sets.
Syntax
interface IIndexVolumeSets : IDispatch
519
520
Search API
Member summary
Table 7-6
IndexVolumeSets properties
Property
Description
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.
Example
Note that IIndexSearch2::SelectArchive must be called before using
IIndexSearch2::IndexVolumeSets.
[C#]
See also
See IIndexSearch2 :: IndexVolumeSets on page 489.
Search API
See IIndexSearch2 :: ListIndexVolumeSets on page 506.
See IIndexVolumeSet :: FirstItemIndexSequenceNumber on page 531.
See IIndexVolumeSet :: OldestArchivedDate on page 531.
See IIndexVolumeSet :: YoungestArchivedDate on page 532.
See IIndexVolumeSets :: Item on page 525.
See IIndexVolumeSets :: _NewEnum on page 524.
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* valuePointer 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");
521
522
Search API
IIndexVolumeSets volSets =
(IIndexVolumeSets)search.IndexVolumeSets;
string aeid = volSets.ArchiveEntryId;
This property returns the name of the archive to which the index volume set
belongs.
Syntax
HRESULT ArchiveName([out,retval] BSTR* value);
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;
IIndexVolumeSets :: HasFolders
This property indicates whether the archive contains a folder structure.
Search API
523
Syntax
HRESULT HasFolders([out,retval] VARIANT_BOOL* value);
Parameters

contain 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
This property returns the number of index volume sets associated with the
currently selected archive.
Syntax
HRESULT Count([out,retval] long* value);
524
Search API
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
to enumerate the collection. This property is hidden in VBScript.
Syntax
Parameters

Search API
Remarks
is automatically used internally when you use the For Eachconstruct 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
See also
See IIndexVolumeSets :: Item on page 525.
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);
525
526
Search API
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.
rvE_POINTER
The pointer to the IUnknown pointer passed to the property is

invalid.
rvE_INVALIDARG
Example
[C#]
e1");
for (int i = 1;
{
i <= volSets.Count;
i++)
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i);

//do something
See also
Search API
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
Table 7-7
IndexVolumeSet properties
Property
Read/Write
Description
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.
527
528
Search API
Table 7-7
IndexVolumeSet properties (continued)
Property
Read/Write
Description
YoungestItemDate
Read only
The youngest date property of the

items indexed in the index volume
set.
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.
Examples
The following C# 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
This property returns the Id of the current index volume set.
Search API
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;
{
}
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
Pointer to a string that will contain the current Id.
529
530
Search API
Return value
rvS_OK
Success.
rvE_POINTER
The string pointer passed into the property is invalid.
Example
[C#]
string archId = volSet.ArchiveEntryId;
This property returns the name of the archive to which the index volume set
collection belongs.
Syntax
HRESULT ArchiveName([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
Pointer to a string that will contain the current Id.
Example
[C#]
string archId = volSet.ArchiveName;
Search API
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
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;
IIndexVolumeSet :: OldestArchivedDate
This property returns the oldest archived date of the items indexed in the index
volume set.
531
532
Search API
Syntax
HRESULT OldestArchivedDate([out,retval] VARIANT* value);
Parameters
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;
This property returns the youngest archived date of the items indexed in the index
volume set.
Syntax
HRESULT YoungestArchivedDate([out,retval] VARIANT* value);
Parameters
Pointer to a VARIANT that will receive the

youngest archived date in the index volume set.
Search API
Remarks
Return value
rvS_OK
Success.
rvE_POINTER
The VARIANT pointer passed in to the property is invalid.
Example
[C#]
object obj = volSet.YoungestArchivedDate;
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.
rvE_POINTER
533
534
Search API
Example
[C#]
object obj = volSet.OldestItemDate;
This property returns the youngest item in the index.
Syntax
HRESULT YoungestItemDate([out,retval] VARIANT* value);
Parameters
Youngest date of items in the index volume set.
Remarks
Return value
rvS_OK
Success.
rvE_POINTER
Example
[C#]
object obj = volSet.YoungestItemDate;
This property indicates whether property values of type VT_DATE are returned
as UTC or local system time.
Search API
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.

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
}
}
[out]
535
536
Search API
{
bool utc = volSet.DateTimeUTC;
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
Table 7-8
SearchResults properties
Property
Read/Write
Description
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.
Search API
Table 7-8
SearchResults properties (continued)
Property
Read/Write
Description
ISearchResults::SortBy
Read only
Name of the properties used to

order the search results.
ISearchResults::_NewEnum
Read only
Enumeration for iterating through

the results.
Table 7-9
SearchResults methods
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
537
538
Search API
ISearchResults2 results = (ISearchResults2) new SearchResults();

//assume we have a set of results in xml, held in the string
xmlResults
results.Results = xmlResults;
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#]
Search API
[out]
//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;
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.
rvE_POINTER
Example
The following example gives an alternative approach to using "foreach" to
enumerate the results returned.
539
540
Search API
[C#]
int num = results.Count;
for (int i = 1; i <= num; i++)
{
ISearchResult2 res = (ISearchResult2)results.Item(i);
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.
rvE_POINTER
Example
[C#]
long num = results.Count;
long total = results.Total;
Search API
if (total < num)

{
//an error has ooccured as the total should be at least equal to
the number results returned
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#]
541
542
Search API

long start = results.Start;
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 490.
Return value
rvS_OK
Success.
rvE_POINTER
Example
[C#]
EOptionsFlags eof = (EOptionsFlags )results.Options;
if (eof == EOptionsFlags.roAttachmentGranularity)
{
//do something
Search API
}
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 491.
Return value
rvS_OK
Success.
rvE_POINTER
The string pointer passed into the property is invalid.
Example
[C#]
string sortBy = results.SortBy;
to enumerate the SearchResults collection. This property is hidden in VBScript.
543
544
Search API
Syntax
Parameters

Remarks
is automatically used internally when you use the foreachconstruct in C# or
VBScript.
This property provides an alternative to Item for iterating through the collection.
See ISearchResults :: Item on page 545.
Return value
rvS_OK
Success.
rvE_POINTER
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)
{
//do something
Search API
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.
See ISearchResults :: _NewEnum on page 543.
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++)
545
546
Search API
{
ISearchResult2 res = (ISearchResult2)results.Item(i);
See also
See SearchResult object on page 550.
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

contain 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)
{
Search API
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
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
enumeration value which
contains the reason for
truncation.
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
}
547
548
Search API
else
{
switch (tr)
{
case ETruncationReason.trAdminResultLimitExceeded:
//handle the problem
break;
case ETruncationReason.trAdminTimeoutExpired:
//handle the problem
break;
//and so on for the other reasons
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
VARIANT_BOOL that will set a new 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.
Search API
Example
[C#]
[in]
//make sure date/time values are returned in local system time
results.DateTimesUTC = false;
[out]
if (results.DateTimesUTC == true)
{
//do something
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.
549
550
Search API
SearchResult object
rvE_INVALIDARG The VT TYPE of the VARIANT is incorrect.

rvS_FALSE
The XML is empty or the VT TYPE is VT_EMPTY.
Example
In this example, it is assumed that there is a string holding a set of XML results
from a previous search, called xmlResults.
[C#]
ISearchResults2 results = (ISearchResults2) new SearchResults();
results.LoadResults(xmlResults);
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
Table 7-10
SearchResult properties
Property
Read/Write
Description
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.
Search API
Table 7-11
SearchResult methods
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.
Examples
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.
[C#]
ISearchResult2 res = (ISearchResult2)results.Item(index);
//index is a 1 based index into the collection of ISearchResult's.
or
{
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);
551
552
Search API
Parameters
[out, retval] BSTR *pbsResult

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
This property returns the unique identifier for this result.
Syntax
HRESULT Number([out, retval] long *plNumber);
Search API
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;
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

property value.
553
554
Search API
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 propertySet.propertyName
format.
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#]
{
object obj = res.Prop("ssid");
string ssid = (string)obj;
RetrieveItem(ssid);
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);
Search API
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.
Example
This example assumes there is a custom property set, "CustomTags", which has
an integer property, "Importance".
[C#]
{
int tag = 0;
//the prop we want should be an int but make sure
555
556
Search API
object obj = res.Prop2("CustomTags", "Importance");

Type type = obj.GetType();
if (type.Name == "Int32")
{
tag = (int)obj;
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")
Search API
{
string ssid = (string)objVal;
//do something
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

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 propertySet.propertyName
format.
Return value
rvS_OK
Success.
557
558
Search API
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.
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
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
VARIANT_BOOL containing the new

value to set.

Search API
Remarks
By default, items are always archived using UTC time.
Return value
rvS_OK
Success.
rvE_POINTER
Example
[C#]
[in]
{
//make sure date/times are returned in local system time
res.DateTimesUTC = false;
//do something
[out]
{
bool isUTC = res.DateTimesUTC;
//do something
559
560
Search API
Chapter
Retention API
About Retention API
Retention API
Enumerations
RetentionCategories object
IRetentionCategories :: Count
IRetentionCategories :: _NewEnum
IRetentionCategories :: Item
IRetentionCategories :: DirectoryDNSAlias
IRetentionCategories :: Lookup
IRetentionCategories :: Create
IRetentionCategories :: Add
IRetentionCategories :: Update
IRetentionCategories2 :: Get
RetentionCategory object
IRetentionCategory :: Period
IRetentionCategory :: Units
IRetentionCategory :: IsVisible
IRetentionCategory :: Identifier
562
Retention API
About Retention API
IRetentionCategory :: Name
IRetentionCategory :: Description
IRetentionCategory :: OnHold
IRetentionCategory :: Locked
IRetentionCategory2 :: ExpiryBasis
About 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
interfaces. The methods and properties enable the calling application to view
and change the various attributes of a retention category.
Retention API
Enumerations
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".
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.
563
564
Retention API
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 8-1
IRetentionCategories properties
Property
Read/Write
Description
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.
Table 8-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.
Retention API
Table 8-2
IRetentionCategories methods (continued)
Method
Description
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 8-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.
Requirements
CLSID
744FC7D7-6933-4696-AC3F-9EFC1E00C96B
Prog ID
EnterpriseVault.RententionCategories
Type Library
RetentionAPILib
DLL
EVRetentionAPI.dll
.NET Primary Interop Assembly (PIA)
KVS.EnterpriseVault.Interop.RetentionAPI.dll
.NET PIA namespace
This property returns the number of retention categories in the collection.
565
566
Retention API
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.
Example
The following Visual Basic script example enumerates the available retention
categories.
Dim
Dim
Dim
Dim
oRCs
oRC
sNames
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
Retention API
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 Eachconstruct in .NET
managed code or VBScript.
This property returns a collection of RetentionCategory objects.
Return value
S_OK
Success.
E_POINTER
Example
Dim
Dim
Dim
Dim
oRCs
oRC
sNames
sMsg

else
oRCs.DirectoryDNSAlias = "EVSite"
567
568
Retention API

oRC.IsVisible & " ;
OnHold=" & oRC.OnHold & " ; Locked=" & oRC.Locked
MsgBox(sMsg)
Next
set oRCS = Nothing
end if
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.
Retention API
Example
IRetentionCategories retCats = (IRetentionCategories) new
RetentionCategoriesClass();
retCats.DirectoryDNSAlias = "SERVER1";
for (int i = 0; i < retCats.Count; i++)
{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
1);
This property is used to identify a computer running an Enterprise Vault Directory
Service, in order to retrieve information from the Enterprise Vault Directory.
The property is write only.
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
HKEY_LOCAL_MACHINE
\SOFTWARE
\Wow6432Node
\KVS
569
570
Retention API
\Enterprise Vault
\SiteID

If you do not set DirectoryDNSAlias, then connection to the local computer is
assumed.
Return value
S_OK
Success.
E_UNEXPECTED
SiteIdNotFound
bstrValue does not identify an existing site.
Example
The following example sets a value for DirectoryDNSAlias in order to list retention
categories on a remote Enterprise Vault server.
Dim
Dim
Dim
Dim
oRCs
oRC
sNames
sMsg

else
oRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"
oRC.IsVisible & " ; OnHold=" & oRC.OnHold & ";
Locked=" & oRC.Locked
MsgBox(sMsg)
Next
set oRCS = Nothing
Retention API

end if
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]
[out]
[out]
[out]
[out]
[out]
[out,
BSTR NameOrId,
VARIANT *Period,
VARIANT *Units,
VARIANT *IsVisible,
VARIANT* Id,
VARIANT* RCName,
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.
571
572
Retention API
[out, retval] VARIANT* RCFound A boolean return value that indicates whether
or not the lookup was successful.
Return value
S_OK
Success.
E_UNEXPECTED
Example
The following Visual Basic script example 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
msg
msg
msg
=
=
=
=
=
msg
msg
msg
msg
msg
&
&
&
&
&
"
"
"
"
"
name = " & name

period = " & period
units = " & units
isvisible = " & isvisible
id = " & id
Msgbox(msg)
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,
Retention API
[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 563.
[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
Administration Console.
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.
Return value
S_OK
Success.
E_UNEXPECTED
E_INVALIDARG
One of the parameters is incorrect.
RetentionCategoryAlreadyExists A retention category with the same name already exists
573
574
Retention API
Example
retCats.Create("New business",10, RetentionUnits.Months, false,
"New business correspondence");
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_UNEXPECTED
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
Retention API
Example
The following Visual Basic script example adds two new retention categories:
Finance and Legal.
Dim oRCS
Dim oRC
Set oRCS = CreateObject("EnterpriseVault.RetentionCategories")
'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)
575
576
Retention API
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_UNEXPECTED
E_INVALIDARG
One of the properties of the IRetentionCategory pointer

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

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
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 supersedes 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.
E_UNEXPECTED
577
578
Retention API
A Retention Category with the given NameOrId value does

not exist.
Example
IRetentionCategories2 retCats2 = (IRetentionCategories2) new
IRetentionCategory retcat =
(IRetentionCategory)retCats2.Get("Business");
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 8-4
IRetentionCategory properties
Property
Read/Write
Description
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.
Retention API
IRetentionCategory properties (continued)
Table 8-4
Property
Read/Write
Description
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.
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.
IRetentionCategory2 property
Table 8-5
Property
Read/Write
Description
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
This property describes the number of retention units (days, weeks, months, years)
an item is to be retained.
579
580
Retention API
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_POINTER
E_INVALIDARG
newVal is outside the bounds of the permitted range (1 - 999999)
Example
[in]
IRetentionCategories retcats = (IRetentionCategories) new
IRetentionCategory retcat = (IRetentionCategory) new
RetentionCategoryClass();
retcat.Name = "Finance";
retcat.Description = "For finance depts";
retcat.Identifier = "xyz";
retcat.Units = RetentionUnits.Months;
retcat.Period = 10;
retcat.IsVisible = true;
Retention API
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;
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);
581
582
Retention API
Parameters
[out, retval] RetentionUnits* pVal
Enumerated value for type of retention

units (days, weeks, months, years).
See Retention Units enumeration
on page 563.
[in] RetentionUnits newVal
RetentionUnits enumerated value.
Remarks
Return value
S_OK
Success.
E_POINTER
E_INVALIDARG
Example
[in]
retcat.Period = 10;
Retention API
[out]
{
1);

long
bool
bool
bool
period = retCat.Period;
isVis = retCat.IsVisible;
onHold = retCat.OnHold;
locked = retCat. Locked;
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.
New value.
583
584
Retention API
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.
E_POINTER
E_INVALIDARG
Example
[in]
retcat.Period = 10;
[out]
Retention API

{
1);
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.
String containing retention category Id (up to 250
Unicode characters).
[in] BSTR newVal
Return value
S_OK
Success.
E_POINTER
Example
[in]
585
586
Retention API
retcat.Period = 10;
[out]
{
1);
Retention API
This parameter identifies the retention category to end users and the
administrator.
Syntax
HRESULT Name([in] BSTR newVal);
Parameters
The current retention category name.
[in] BSTR newVal
New retention category name.

Maximum length is 32 unicode characters.
Return value
S_OK
Success.
E_POINTER
Example
[in]
retcat.Period = 10;
587
588
Retention API
[out]
{
1);
This property describes the retention category to the administrator.
Syntax
HRESULT Description([in] BSTR newVal);
Parameters
Pointer to description of retention category.
Retention API
New description of retention category.
[in] BSTR newVal
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_POINTER
E_INVALIDARG
newVal is either an empty string or is greater than 127 characters

in length.
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
Pointer to a VARIANT_BOOL containing

the current value.
New value.
Remarks
This retention category hold is different from the Legal Hold feature.
589
590
Retention API
Return value
S_OK
Success.
E_POINTER
Example
[in]
retcat.Period = 10;
[out]
{
1);
Retention API

bool locked = retCat.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
New 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.
E_POINTER
591
592
Retention API
Example
[in]
retcat.Period = 10;
[out]
{
1);
Retention API
bool locked = retCat.Locked;
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_POINTER
E_INVALIDARG
newVal is outside the bounds of the permitted range.
Example
[in]
593
594
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;
Appendix
Enterprise Vault properties

This appendix includes the following topics:
About Enterprise Vault properties
System properties
Defined custom properties
Defined custom FSA properties
Defined custom SharePoint properties
Defined properties for Compliance Accelerator
About Enterprise Vault properties

This section lists the properties that are defined by Enterprise Vault:
System 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.
A detailed description of how Enterprise Vault processes message items is provided
in an appendix to this guide. The appendix includes information about how
Enterprise Vault processes sender and recipient details when archiving and
retrieving messages, and copying or moving archived messages.
596

System properties

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.
Sortable properties are those that can be used to order search results. Properties
marked as Yes 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 A-1
System properties
Description
Name
Type
Search- Retriev- Multi- Fast

able
able
Valued Sortable
Subject/Title
subj
String
Yes
Yes
No
No
Message Priority
prio
String
Yes
Yes
No
No
Notes
Although indexed as a string,

usually a numeric value.
Technically no limit,
practically limited to 32-bit
integer maximum.

System properties
Table A-1
System properties (continued)
Description
Name
Type

able
able
Valued Sortable
Notes
Message Importance
impo
String
Yes

Yes
No
No
integer maximum.
Message Sensitivity
sens
String
Yes
Yes
No
No

integer maximum.
Message Security
secu
String
Yes
Yes
No
No
Currently not populated with

any value.
Message Originator
orgn
String
Yes
No
No
No

any value.
Original identifier for

the item. (e.g.
SubmissionId for a
sent message)
iden
String
Yes
Yes
No
No
Last Modified date of

the item
mdat
Date
Yes
Yes
No
Yes
Original identifier for coid

this component of the
item
String
Yes
Yes
No
No
Data type of the item
dtyp
String
Yes
Yes
No
No
E.g. DOC, XLS, MSG
De-duplication
fingerprint of item
fpdd
String
Yes
Yes
No
No
Can be used to find an exact

match of a message or a
document.
Range 1 Jan 1970 to 1 Jan

2038
Wildcard searches on this

property are not supported.
Content fingerprint of fpcn
item
String
Yes
Yes
No
No
Can be used to find a match

on an attachment or
document content.
597
598

System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
Notes
Archived Date
adat
Date
Yes
Yes
No
Yes

2038
Original location of the locn

item
String
Yes
Yes
No
No
A sequence of folders.
Current location of the clcn

item
String
No
Yes
No
No
A sequence of folders.
The last or leaf folder

of original location
lolf
String
No
Yes
No
No
The last or leaf folder

of current location
cllf
String
No
Yes
No
No
Original location
lofn
folder names (ordered)
String
No
Yes
Yes
No
Current location folder clfn

names (ordered)
String
No
Yes
Yes
No
The item's Saveset

identifier
String
Yes
Yes
No
No
ssid

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
No
Yes
No
No
Not supported from

Enterprise Vault 10.0.
User who archived the user

item.
String
No
Yes
No
No
Currently not populated.
Original retention
category Id
String
Yes
Yes
No
No
Max 112 chars.
rcat


System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
Notes
Current retention
category Id
crct
String
Yes
Max 112 chars.
Original retention
category name
rcnm
String
No
Yes
No
No
Max 32 chars
Current retention
category name
crcn
String
No
Yes
No
No
Max 32 chars
Index Sequence
Number
snum
Integer
Yes
Yes
No
Yes
64-bit integer
VaultEntryId of index vlid

containing the item
String
No
Yes
No
No
Max 112 chars.
Created, sent/received date

or archivedDate
Date
Yes
Yes
No
Yes

2038
Yes
No
No


Content
cont
String
Yes
Yes
No
No
Search API: If item indexed by

Enterprise Vault 9 or earlier,
only the first 120 significant
characters can be retrieved.
If item indexed by Enterprise
Vault 10.0 or later, by default
the first 128 significant
characters are retrieved, but
this value can be configured.
Content Management API:
HTML representation to a
max of 5 MB.
Languages
lang
String
Yes
No
No
No
Categories/Keywords
keys
String
Yes
Yes
Yes
No
Integer
Yes
Yes
No
Yes
The size of the item in size

KB
Currently not populated.
32-bit integer
599
600

System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
Notes
The number of
attachments
natc
Integer
Yes
Yes
No
Yes
32-bit integer
Permission VaultIds
pvid
for the item. (Known as
Archive Folder
VaultIds)
String
Yes
Yes
Yes
No
Max 112 chars.
Attachment Number
Integer
Yes
No
No
Yes
32-bit integer
anum
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
item (based on crct)
edat
Date
Yes
Yes
No
No

2038
Number of days to
expiry for the item
(based on crct)
ndte
Integer
Yes
Yes
No
No
32-bit integer
Rank value of the item rank

when sorted by
relevance (0 to 10,000)
Integer
No
Yes
No
No
32-bit integer
The item's original

MAPI Message Class
(e.g. IPM.Note)
msgc
String
Yes
Yes
No
No
Message Flag Status
flag
Integer
No
Yes
No
No
32-bit integer
Reason for missing

content
comr
String
Yes
Yes
No
No

integer max.

System properties
Table A-1
Name
Type

able
able
Valued Sortable
Notes
Attachments only. The taut

author of the top-level
item
String
No
Yes
No
No
Not applicable to items

indexed using
ItemGranularity schema.
Attachments only. The tsub

subject/title of the
top-level item
String
No
Yes
No
No

indexed using
Attachments only. The tsiz

size of the top-level
item in KB
Integer
No
Yes
No
No
32-bit integer
Conversation tracking cnid

ID
String
Description

indexed using
Yes
Yes
No
No
For MAPI items, a 32

hexadecimal character
representing a 128-bit GUID.
Currently not populated for
other items.
Conversation tracking cnhv

index
String
No
Yes
No
No
For MAPI items, 12

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 tracking cntp

topic
String
No
Yes
No
No
Currently only populated for

MAPI items.
Index Volume. Identity ivid

of the volume
containing the item
Integer
No
Yes
No
No
32-bit integer.
601
602

System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
Notes
Index Volume Set.
vsid
Integer
No
Yes
No
No
32-bit integer.
menv
String
No
No
No
No
Only present for Exchange

journal messages.
Identity of the volume

set containing the item
Message Envelope
recipient and sender
information

Retrievable using the Content
Management API.
See IArchiveMetaData ::
IndexData on page 236.
Message Envelope
Recipient.
jrcp
String
Yes
No
Yes
No

journal messages. The
property values include both
email addresses and display
names (where present).
Message Envelope TO: jrto

Recipient
String
Yes
No
Yes
No

journal messages.
Union of jrto, jrcc, jrbc

& jren
See Notes for jrcp.

Message Envelope CC: jrcc
Recipient
String
Yes
No
Yes
No

journal messages.
See Notes for jrcp.
Message Envelope
BCC: Recipient
jrbc
String
Yes
No
Yes
No

journal messages.
See Notes for jrcp.
Message Envelope
Other Recipient
jren
String
Yes
No
Yes
No

journal messages.
See Notes for jrcp.
Used when the recipient
details are not explicitly
identified as a TO, CC, or BCC
recipient.

System properties
Table A-1
Name
Type

able
able
Valued Sortable
Notes
Message Envelope
jrau
Author Union of jrfm,
jrpp & jaen
String
Yes

journal messages.
Message Envelope
FROM: Recipient
String
Description
jrfm
No
Yes
No
See Notes for jrcp.

Yes
No
Yes
No

journal messages.
See Notes for jrcp.
Message Envelope PP: jrpp

Recipient Per
Procurationem (by
delegation to): person
on whose behalf
document has been
written or message has
been sent
String
Message Envelope
Other Author
String
jaen
Yes
No
Yes
No

journal messages.
See Notes for jrcp.
Yes
No
Yes
No

journal messages.
See Notes for jrcp.
Used when the author details
are not explicitly identified as
FROM or PP.
Message Sender and

Recipient
sere
String
No
No
No
No

Retrievable using the Content
Management API.
See IArchiveMetaData ::
IndexData on page 236.
Message Recipient.
Union of redn, reea,
resm, reot & jrcp
recp
String
Yes
No
Yes
No
Message Recipient.
redn
Display/friendly name.
Union of rtdn, rcdn,
rbdn & rndn
String
Yes
No
Yes
No
603
604

System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
Message Recipient.
Email address. Union
of rtea, rcea, rbea &
rnea
reea
String
Yes
No
Yes
No
Message Recipient.
SMTP email address.
Union of rtsm, rcsm,
rbsm & rnsm
resm
String
Yes
No
Yes
No
Message Recipient.
Other email address.
Union of rtot, rcot,
rbot & rnot
reot
String
Yes
No
Yes
No
TO: Recipient
reto
String
Yes
Yes
No
No
Notes
Max 256 chars.

The retrievable value is the
first few RTDN (or RTSM)
values, up to a maximum of
256 characters.
TO: Recipient.
rtdn
Display/friendly name
String
Yes
No
Yes
No
TO: Recipient. Email

address. Union of
RTSM & RTOT
rtea
String
Yes
No
Yes
No
TO: Recipient. SMTP

email address
rtsm
String
Yes
No
Yes
No
TO: Recipient. Other

email address
rtot
String
Yes
No
Yes
No
CC: Recipient
recc
String
Yes
Yes
No
No
Max 256 chars.

256 characters.
CC: Recipient.
rcdn
String
Yes
No
Yes
No

System properties
Table A-1
Name
Type

able
able
Valued Sortable
CC: Recipient. Email

rcea
address. Union of rcsm
& rcot
String
Yes
No
Yes
No
CC: Recipient. SMTP

email address
rcsm
String
Yes
No
Yes
No
CC: Recipient. Other

email address
rcot
String
Yes
No
Yes
No
BCC: Recipient
rbcc
String
Yes
Yes
No
No
Description
Notes
Max 256 chars.

256 characters.
BCC: Recipient.
rbdn
String
Yes
No
Yes
No
BCC: Recipient. Email rbea

address. Union of rbsm
& rbot
String
Yes
No
Yes
No
BCC: Recipient. SMTP rbsm

email address
String
Yes
No
Yes
No
BCC: Recipient. Other

email address
rbot
String
Yes
No
Yes
No
Other Envelope
Recipient
renv
String
No
Yes
No
No
Max 256 chars.

256 characters.
Other Envelope
rndn
Recipient.
String
Yes
No
Yes
No
Other Envelope
rnea
Recipient. Email
address. Union of rnsm
& rnot
String
Yes
No
Yes
No
605
606

System properties
Table A-1
Name
Type

able
able
Valued Sortable
Other Envelope
rnsm
Recipient. SMTP email
address
String
Yes
No
Yes
No
Other Envelope
rnot
Recipient. Other email
address
String
Yes
No
Yes
No
Number of Recipients
nrcp
Integer
Yes
Yes
No
Yes
32-bit integer
Number of TO:
Recipients
nrto
Integer
No
Yes
No
No
32-bit integer
Number of CC:
Recipients
nrcc
Integer
No
Yes
No
No
32-bit integer
Number of BCC:
Recipients
nrbc
Integer
No
Yes
No
No
32-bit integer
Number of Other
Envelope Recipients
nren
Integer
No
Yes
No
No
32-bit integer
Author. Union of audn, auth

auea, ausm, auot, writ,
from, ppgn & jrau
String
Yes
Yes
Yes
No
Author.
audn
Display/friendly name.
Union of wrdn, frdn,
ppdn
String
Yes
No
Yes
No
Author. Email address. auea

Union of ausm, auot
and wrea
String
Yes
No
Yes
No
Author. SMTP email

address. Union of
wrsm, frsm ppsm
String
Yes
No
Yes
No
String
Yes
No
Yes
No
Description
ausm
Author. Other email

auot
address. Union of wrot,
frot, ppot
Notes

System properties
Table A-1
Name
Type

able
able
Valued Sortable
Notes
Writer. Union of wrdn, writ

wrea, wrsm, wrot
String
Yes
No
Yes
No

any value.
Writer.
wrdn
String
Yes
No
Yes
No

any value.
Writer. Email address. wrea

Union of wrsm & wrot
String
Yes
No
Yes
No

any value.
Writer. SMTP email

address
wrsm
String
Yes
No
Yes
No

any value.
Writer. Other email

address
wrot
String
Yes
No
Yes
No

any value.
FROM: Union of frdn,

frea, frsm, frot
from
String
Yes
No
Yes
No
FROM:
frdn
String
Yes
No
Yes
No
FROM: Email address. frea

Union of frsm & frot
String
Yes
No
Yes
No
FROM: SMTP e-mail

address
frsm
String
Yes
No
Yes
No
FROM: Other email

address
frot
String
Yes
No
Yes
No
PP Union of ppdn,
ppgn
ppea, ppsm & ppot. Per
Procurationem (by
delegation to) person
on whose behalf
document has been
written or message has
been sent
String
Yes
No
Yes
No
PP Display/friendly
name
String
Yes
Yes
Yes
No
Description
ppdn
607
608

System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
PP Exchange email
address. Union of
ppsm, ppot
ppea
String
Yes
No
Yes
No
PP SMTP email
address
ppsm
String
Yes
No
Yes
No
PP Other email address ppot
String
Yes
No
Yes
No
Name Union of recp,

auth
name
String
Yes
No
Yes
No
Name Display/friendly nadn

name. Union of redn &
audn
String
Yes
No
Yes
No
Name Exchange email naea

address. Union of reea
& auea
String
Yes
No
Yes
No
Name SMTP email

nasm
address. Union of resm
& ausm
String
Yes
No
Yes
No
Name Other email

naot
address. Union of reot
& auot
String
Yes
No
Yes
No
Text Union of cont &

subj
String
Yes
No
Yes
No
Event start date E.g.

csrt
Calendar meeting start
date
Date
No
Yes
No
No

2038
Event end date E.g.

cend
Calendar meeting end
date
Date
No
Yes
No
No

2038
Event location E.g.

Calendar meeting
location
String
No
Yes
No
No
text
clon
Notes

System properties
Table A-1
Description
Name
Type

able
able
Valued Sortable
Notes
Task due date
tddt
Date
No
Yes
No
No

2038
Task completed date
tcdt
Date
No
Yes
No
No

2038
Task status
tsts
Integer
No
Yes
No
No
Property value can be one of

the following:
609
0 = Not started
1 = In progress
2 = Completed
3 = Paused
4 = Deferred
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~2F0993C0D5BD4D0087E592D043C22B0.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~2F0993C0D5BD4D0087E592D043C22B0
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)
610

System properties
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, if the item index is 32-bit, only the first 120 characters of the
textual representation of the content can be retrieved.
If the item index is 64-bit, by default the first 128 characters of the textual
representation of the content are retrieved, but this value can be configured.
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
\Wow6432Node
\KVS
\Enterprise Vault
\MaxIndexDataHTMLContentKB
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

System properties
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>
<EA>theboss@ourcompany.com</EA>
</RC>
</DL>
</TO>
<CC />
<BCC>
611
612

System properties
<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>
<DL>

System properties
<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.
6.0 SP5 on page 40.
<AUTH> element of the menv property is available in Enterprise Vault 6.0

SP5, Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
6.0 SP5 on page 40.
Missing content reasons returned in the missing content property, comr, are
available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
6.0 SP5 on page 40.
613
614

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.0.

The following list of custom properties are also defined in Enterprise Vault.
Custom property sets and names can only contain the following characters:
A-Z 0-1 . _ Names should not start with a number.
Any non-supported character will be replaced with an underscore.
Properties containing GUIDs and hashes (up to 256 characters) will be indexed
as literal and non-wildcarded, in order to optimize memory utilization.
Table A-2
Description
Name

Type
For an item copied by Move

Vault.CopiedFrom String
Archive, provides the following
details:
Time the item was copied
The source item archive
Saveset ID
If message is a journal
message, the type of journal
message
Vault.JournalType String
Search- Retriev- Notes

able
able
Yes
Yes

If an archive has been moved
several times, there will be a
value for each move.
Yes
Yes
Currently defined values:
E2007
E2003
E2007ClearText
E2007RMS

Table A-2
Defined custom properties (continued)
Description
Name
Type
Message direction
Vault.MsgDirection String
Search- Retriev- Notes

able
able
Yes
Yes
32-bit integer as a string.

0 - undefined
1 - internal (all recipients are

internal)
2 - external-in (sender is
internal)
3 - external-out (one or more
recipients are external)
Type of the message.
Vault.MsgType
String
Yes
Yes
EXCH
SMTP
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:012,16B3597E77206FB4690FB46573DA6D7081110000
EVServer.domain.local,200811140000000~200811141011170000~Z~
B082EF701FF8FB47509D5228C99D2B51
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
615
616

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.

The following list of custom properties are defined in Enterprise Vault for FSA
items.
Table A-3
Description
Name
Type
Searchable Retrievable Notes
Original Name of file at the EVFSA.OriginalFileName String

point of archival
Yes
Yes
Indicator that item was

imported from DLM
Yes
Yes
EVFSADLMImport.DLM String
Currently only
populated with the
string "Imported"

The following list of custom properties are defined in Enterprise Vault for
SharePoint items.
Table A-4
Description
Name
Type
Document title
EVSP.Title
String
Yes
Yes
SharePoint documentId
EVSP.DocId
String
Yes
Yes
Document version
EVSP.Version
String
No
Yes
Check in comment
EVSP.Comment
String
No
Yes
Display name of document

editor
EVSP.Editor
String
Yes
Yes
Domain name (Windows

account name) of document
author
EVSP.CreatedBy
String
Yes
Yes

Table A-4
Defined custom SharePoint properties (continued)
Description
Name
Type
Domain name (Windows

account name) of document
editor
EVSP.ModifiedBy
String
Yes
Yes
SharePoint Site Id
EVSP.SiteId
String
Yes
Yes
SharePoint Site name
EVSP.Site
String
No
Yes
SharePoint Site Url
EVSP.SiteUrl
String
Yes
Yes
Customer configurable
properties - any SharePoint
property
EVSPP.<Sharepoint
property name>
String
Yes
Yes

The following list of custom properties are defined in Enterprise Vault for items
processed by the Compliance Accelerator Journaling Connector.
Table A-5
Description
Type
Searchable Retrievable Multi- Notes

Valued
The set of CA
KVSCA.DeptAuthor
Department Ids that
the item's author is
a member of
String
Yes
Yes
Yes
CA Dept IDs
The set of CA
KVSCA.DeptRecips
Department Ids that
the item's recipients
are members of
String
Yes
Yes
Yes
CA Dept IDs
KVSCA.Department String
Yes
Yes
Yes
CA Dept IDs
The union of
KVSCA.DeptAuthor
and
KVSCA.DeptRecips
Name
Defined custom properties for Journaling Connector
617
618

Table A-5
Description
Name
Defined custom properties for Journaling Connector (continued)

Type
Searchable Retrievable Multi- Notes

Valued
Policies, defined in evtag.category

the policy
management
software, which do
not affect capture
either way; they only
categorize emails.
String
Yes
Yes
Yes
Policy names
Policies, defined in evtag.exclusion

the policy
management
software, which
either preclude
capture or advocate
non-capture.
String
Yes
Yes
Yes
Policy names
Policies, defined in
the policy
management
software, which
either demand or
suggest capture.
String
Yes
Yes
Yes
Policy names
String
Yes
Yes
Yes
Defined values are:
evtag.inclusion
The policy action is Vault.PolicyAction

the overall action
that should be taken
on an item; the sum
result of all the
applied policies.
NOACTION
EXCLUDE
INCLUDE
Appendix
API return values

About API return values
Content Management API return values
Retention API return values
Search API return values
External Filter API Event log messages
About API return values

This appendix lists the Enterprise Vault API return values.

Table B-1
Return value
Value
Description
0x80040300
Enterpise Vault is not running
0x80040301
Time to create a new archive
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.
620
API return values

Table B-1
Content Management API return values (continued)
Return value
Value
Description
0x80040303
Caller has insufficient

permissions to access the
vault store, archive, or item,
or archive is in a read-only
state.
0x80040304
Problem with input

parameters
0x80040305
An input parameter identifies

more than one object
CONTENTMANAGEMENTAPI_E_INTERNAL_FAILURE
0x80040306
An internal failure occurred
0x80040307
Item not found
0x80040308
Archive, Vault Store or

Retention Category does not
exist
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.

The following return values are defined for the Retention API:
API return values

Table B-2
Return value
Value
Description
RetentionCategoryAlreadyExists
0x800700b7
Returned when attempting to add a retention

category, and one already exists with the same
name.
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.

The following return values are defined for the Search API:
Table B-3
Return value
Value
Description
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
0x800706BA
The index server is not currently

available
0x80041C6B
An archive has not been selected
0x80041C11
The Enterprise Vault Directory is not

available
0xc0041C5C
The archive does not exist
rvINDEXING_W_INDEXDISABLED
0x80041C84
The archive's index is current disabled
621
622
API return values

Table B-3
Search API return values (continued)
Return value
Value
Description
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
0x80041C6D
The index volume identity does not

belong to the currently selected archive
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
0xc0041C83
The search request was rejected because

too many search results were requested.
The maximum is defined by the
MaxSearchResultsPerVolumeSet
property.
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

index is being unloaded to allow another
index to be searched
rvINDEXING_W_SERVICE_STOPPING
0x80041C47

index service is being shutdown
0x80041C70

index is currently overloaded with
search requests
0x80041C71
The search failed because it took too

long to complete. The timeout is defined
by the Timeout property.
0xC0041C53
The search was rejected since the search

query was invalid.
API return values

Search API return values (continued)
Table B-3
Return value
Value
Description
0xC0041C5E
The search was rejected since the search

query contained invalid wildcard terms.
0xC0041C67
The search failed due to an internal

error. Check the Enterprise Vault event
log on the Enterprise Vault server.
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.
Exchange Server filtering

The following messages are written to the Enterprise Vault event log by the
Exchange Task Filter Controller.
Table B-4
Exchange Task Filter Controller log messages
Event
Type
Description
Example
3144
Error
Logged by the filter controller Failed whilst initializing the Filter

if one or more of the registered Controller. The agent will now shut down
external filters fails to load, or as it cannot reliably continue.
fails to initialize.
Error: error information
3263
Error
Logged by the filter controller

when an external filter returns
an error when processing a
message. (The filter's
ProcessFilter method returns
a non-zero return value). The
filter controller stops
processing the message.
An error occurred processing the external

filter filter prog id. No more filters will be
processed.
Mailbox: mailbox DN
Message Folder: folder name
Message Title: message title
623
624
API return values

Table B-4
Exchange Task Filter Controller log messages (continued)
Event
Type
Description
Example
3146
Error
Logged by the filter controller Failed to initialize the external filter with
when attempting to create an ProgId filter prog id. Either the ProgId is
instance of an external filter. incorrect or 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

when an external filter returns external filter filter prog id.
an error when initializing. (The
filter's Initialize method
returns a non-zero return
value).
3150
Error
Logged by the filter controller Whilst processing external filters too

when a stream of consecutive many consecutive errors have occurred.
errors are encountered.
This Task will 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.
Table B-5
Domino Journaling task filter controller log messages
Event
Type
Description
Example
41086
Informational
Logged by the filter controller The Domino external filter filter_name

at the point of initializing each has started.
installed filter.
41087
Informational
Logged by the filter controller The Domino external filter filter_name

at the point of de-initializing has stopped.
each installed filter.
API return values

Table B-5
Domino Journaling task filter controller log messages (continued)
Event
Type
Description
Example
41088
Error

if a filter raises an error during
processing. The reason for the
error is contained in the
message text.
The Domino external filter filter_name

failed to process an item.Reason: An
applicable RuleSet has not been defined
for database Symantec\db_name.nsf and
a default Content Category has not been
specified.
41036
Error

if a filter raises an error during
initialization. The reason for
the error is contained in the
message text.
Unable to start the FilterController The

following error occurred:
Unable to initialize() filter filter_name.
Reason: ...
File System filtering

The following messages are written to the Enterprise Vault event log by the File
System Archiving task filter controller.
Table B-6
File System Archiving task filter controller log messages
Event
Type
Description
Example
41294
Informational
Logged by the filter controller The file system external filter filter_name
when the filter starts.
has started.
41295
Informational
when the filter stops.
has stopped.
41296
Warning
when the filter fails to process failed to process a file.
a file.
File: FileUNCPath
Error: error_message
41338
Error
Logged by the filter controller The File System Archiving task has
when the error count reaches stopped because th external filter error
the threshold level.
count has reached the threshold.
41339
Warning
Logged by the filter controller Error in external filter method

if it encounters an error in the FilteringComplete.
method FilteringComplete.
625
626
API return values

Table B-6
File System Archiving task filter controller log messages (continued)
Event
Type
Description
Example
41340
Warning
Logged by the filter controller Error in external filter method Shutdown.

if it encounters an error in the
method Shutdown.
41336
Warning
Logged by the filter controller Failed to load the file system external filter
if it fails to load the filter.
filter_name.
41337
Warning
Logged by the filter controller Failed to initialize the file system external
if it fails to initialize the filter. filter filter_name.
41361
Error
Logged by the File System

The File System Archiving Task
Archiving task when it fails to archiving_task_name has stopped because
load or initialize the filter.
it failed to load or initialize a file system
external filter.
41362
Warning
Logged by the File System

The file system external filter filter_name
Archiving task when it receives has requested to stop the File System
a shutdown request from the Archiving task: archiving_task_name
filter.
Appendix
Understanding how
Enterprise Vault archives
and indexes messages
About storing and retrieving message items
Exchange (MAPI) messages
Lotus Notes messages
SMTP messages
Copying message items
Why a retrieved item is not a binary copy of the original item
About storing and retrieving message items

Enterprise Vault recognizes and supports the insertion of Exchange (MAPI), Lotus
Notes, and SMTP messages. The Content Management API processing of messages
has been enhanced over several Enterprise Vault releases, especially in the
handling of sender and recipient details when indexing the archived items. In
particular, improvements have been made to the way that address details in
Exchange messages are resolved to users SMTP addresses. As a result, Enterprise
Vault now indexes SMTP addresses in preference to Exchange email addresses.
This is important for Enterprise Vault Discovery Accelerator searches, which are
typically based on users SMTP addresses, rather than the more unwieldy Exchange
X.500 Directory Name style address.
628
Understanding how Enterprise Vault archives and indexes messages

The Enterprise Vault archiving agents for Exchange (MAPI), Lotus Notes, and
SMTP messages augment the sender and recipient details from the message with
additional values sourced from the domain directory of mail users. The primary
aim is to ensure that Enterprise Vault index searches on a users primary email
address also find messages in which the user was addressed using a secondary or
alternative email address. The archiving agent processes the message sender and
recipients to generate a structured collection of enhanced sender and recipient
details. These details are stored as the Message Sender and Recipients (sere)
property in the archived item. The details are used when indexing the archived
item. The sere property can be retrieved using the Content Management API.
The Enterprise Vault Exchange and Domino journal archiving agents also augment
the sender and recipient details for a journal message with additional values
sourced from both the message envelope and the domain directory of mail users.
The message envelope typically provides further details of the message routing,
including Distribution List expansion, BCC recipients and alternate recipient
delivery. These properties are processed to generate another structured collection
of enhanced sender and recipient details. These details are stored as the Message
Envelope Sender and Recipients (menv) property in the archived item, and are
also used when indexing the archived item. The menv property can also be
retrieved using the Content Management API.
Details of the properties that are defined in Enterprise Vault, including the Message
Sender and Recipients (sere) and Message Envelope Sender and Recipients (menv)
properties, are included in this manual.
This appendix describes how Enterprise Vault processes different message types,
and includes information about key changes over recent releases of Enterprise
Vault.

This section describes how the Enterprise Vault Exchange archiving agents and
Content Management API process sender and recipient information when archiving
Exchange mailbox and journal messages.
How the Enterprise Vault archiving agent processes Exchange mailbox

messages
The Enterprise Vault Exchange archiving agent archives all mailbox messages in
the same manner. This includes interpersonal messages, delivery reports, read

receipts, tasks, calendar items, and so on. The message is stored as the primary
content of the archived item. The message sender and recipients are processed
in conjunction with the Exchange Global Address List (GAL) to generate the
Message Sender and Recipients (sere) property.
The sender, sent representing, and each recipient listed in the message are
recorded in the sere property with an entry containing a friendly name, and an
email address. In all cases, if a current Exchange GAL entry is identified by the
appropriate MAPI entry id property in the message, then the display name and
default SMTP address are used from that GAL entry. Otherwise the best values
from the available message properties are used, with precedence given to an SMTP
address value over an Exchange address value. Furthermore if a recipient maps
to a Distribution List entry in the Exchange GAL, and the advanced setting Expand
Distribution List in the Enterprise Vault Exchange archiving policy is enabled,
the sere property is augmented with the display name and default SMTP addresses
of the members of the Distribution List.
Figure C-1 details the workflow for generating the sender element of the sere
property from the message sender properties.
629
630

Figure C-1
Read message sender

properties
Does Exchange
GAL entry exist for
sender entry id?
Exchange archiving agent workflow for generating the sender entry

of the sere property
MAPI properties
Display name: PR_SENDER_NAME (ID:0x0C1A)
Address Book Entry Id: PR_SENDER_ENTRYID (ID:0x0C19)
Email address: PR_SENDER_EMAIL_ADDRESS (ID:0x0C1F)
Email address type: PR_SENDER_ADDRTYPE (ID:0x0C1D)
yes
no
Read Exchange
GAL entry
Does Exchange
GAL entry contain
default SMTP
address?
no
Is sender
email address an
SMTP address?
MAPI properties
Alternate email addresses:
PR_EMS_AB_PROXY_ADDRESSES
(ID:0x800F)
Default SMTP address:
PR_SMTP_ADDRESS (ID:0x39FE)
Add sender display
name and GAL default
SMTP address to
Message Sender and
Recipient property
yes
Add sender display name and

sender email address to
Message Sender and Recipient
property
yes
no
Is sender
email address
an Exchange
address?
yes
Search Active
Directory for user
object containing
Exchange address
SMTP address
found in Active
Directory?
no
LDAP properties
Legacy Exchange address:
legacyExchangeDN
Email-Addresses: mail
yes
Add sender display

name and Active
Directory SMTP
address to Message
Sender and Recipient
property

sender email address to
Message Sender and
Recipient property

The same workflow is used to generate the sent representing element of the sere
property, but the logic is based on the sent representing MAPI properties in the
message:
Display name: PR_SENT_REPRESENTING_NAME (ID:0x0042)
Exchange Address Book Entry Id: PR_SENT_REPRESENTING _ENTRYID (ID:0x0041)
Email address: PR_SENT_REPRESENTING _EMAIL_ADDRESS (ID:0x0065)
Email address type: PR_SENT_REPRESENTING _ADDRTYPE (ID:0x0064)
Figure C-2 details the workflow for generating each of the recipient elements of
the sere property from the message recipient properties.
631
632

Exchange archiving agent workflow for generating the recipient

entry of the sere property
Figure C-2
MAPI properties
Recipient Type: PR_RECIPIENT_TYPE (ID:0x0C15)
Display name: PR_DISPLAY_NAME (ID:0x3001)
Exchange Address Book Entry Id: PR_ENTRYID (ID:0x0FFF)
Email address: PR_EMAIL_ADDRESS (ID:0x3003)
Email address type: PR_ADDRTYPE (ID:0x3002)
Default SMTP Address: PR_SMTP_ADDRESS (ID:0x39FE)
Original email address: PR_OrgEmailAddr (ID:0x403E )
Original email address type: PR_OrgAddrType (ID:0x403D)
Read message recipient

properties
Does Exchange GAL

entry exist for recipient
entry id?
no
MAPI properties
Display Name: PR_DISPLAY_NAME (ID:0x3001)
PR_EMS_AB_PROXY_ADDRESSES (ID:0x800F)
Default SMTP address: PR_SMTP_ADDRESS
(ID:0x39FE)
Read Exchange
Global Address
List entry
yes
Is entry a DL and
is DL expansion archiving
policy enabled?
yes
Expand DL members and add each

members display name and default SMTP
address to Message Sender and Recipient
property
no
no
Is recipient default
SMTP address
present?
Add GAL display name and default SMTP

property
Does Exchange
GAL entry contain default
SMTP address?
yes
Add GAL or recipient display name and

GAL default SMTP address to Message
Sender and Recipient property
yes
Add GAL or recipient display name and recipient default SMTP

address to Message Sender and Recipient property
yes
Add GAL or recipient display name and recipient email address

to Message Sender and Recipient property
yes
Add GAL or recipient display name and recipient original email

no
Add GAL or recipient display name and recipient email address

no
Is recipient
email address an
SMTP address?
no
Is recipient
original email
address an SMTP
address?

How the Content Management API processes Exchange mailbox

messages
The Content Management API supports MAPI messages inserted in Outlook
Message Format (.msg), and supports both Unicode and non-Unicode items.
The message is stored as the primary content of the archived item. The message
sender and recipients are processed to generate the Message Sender and Recipients
(sere) property at various points in the handling of the archived item, dependent
on the version of Enterprise Vault. Later versions of Enterprise Vault aim to
replicate the behavior of the Enterprise Vault Exchange archiving agent, such
that the sere property is generated on ingest, and stored in the archived item.
Table C-1
Content Management API support for the sere property for MAPI
messages
Enterprise Vault
8.x
Enterprise Vault
9.x a
Enterprise Vault
10.x
Message Sender and No

Recipients (sere)
property is generated
on insertion, and
stored in the
archived item
Yes
Yes
If the Message
Sender and
Recipients (sere)
property is not
present in the
archived item, it is
generated
dynamically when
the item is indexed
Yes
Yes
Yes
Yes
Yes
Sender/Recipient
No
details are generated
dynamically when
the item is retrieved
(if not stored in
archived item)
a. Enterprise Vault 9.0 SP1 included a performance improvement and a fix for an
issue introduced in Enterprise Vault 9.0. The issue prevented Enterprise Vault
from indexing the sender/recipient details correctly for some items (Ref 901-5786).
633
634

The Content Management API uses the display name and SMTP email address
values from the message in preference to attempting Exchange address resolution.
From Enterprise Vault 9.0 Exchange address resolution uses Active Directory. In
releases prior to Enterprise Vault 9.0, the Exchange GAL is used. There is no
expansion of distribution lists, regardless of the advanced setting Expand
Distribution Lists in the Exchange archiving policy.

Content Management API workflow for generating sender entry of

sere property
Figure C-3
Read message sender

properties
MAPI properties
Display name: PR_SENDER_NAME (ID:0x0C1A)
Exchange Address Book Entry Id: PR_SENDER_ENTRYID (ID:0x0C19)
Email address: PR_SENDER_EMAIL_ADDRESS (ID:0x0C1F)
Email address type: PR_SENDER_ADDRTYPE (ID:0x0C1D)
Is sender
email address an
SMTP address?
Add sender display name and sender email

property
yes
no
Is
Enterprise Vault
release 9.0 or
later?
yes
Search Active
Directory for user
object containing
sender email
address
SMTP address found

in Active Directory?
LDAP properties
legacyExchangeDN
yes

Active Directory SMTP
address to Message Sender
and Recipient property
no
no
Does Exchange GAL

entry exist for sender
entry id?
no
yes
Read Exchange
GAL entry
Does Exchange GAL

entry contain default
SMTP address?
no
Add sender display name and sender

email address to Message Sender and
Recipient property
MAPI properties
PR_EMS_AB_PROXY_ADDRESSES
(ID:0x800F)
Default SMTP address:
PR_SMTP_ADDRESS (ID:0x39FE)
yes

GAL default SMTP address to
property
Add sender display name and sender email

property
635
636

The same workflow is used to generate the sent representing element of the sere
property, but the logic is based on the message sent representing MAPI properties:
Display name: PR_SENT_REPRESENTING_NAME (ID:0x0042)
Exchange Address Book Entry Id: PR_SENT_REPRESENTING _ENTRYID (ID:0x0041)
Email address: PR_SENT_REPRESENTING _EMAIL_ADDRESS (ID:0x0065)
Email address type: PR_SENT_REPRESENTING _ADDRTYPE (ID:0x0064)
Figure C-4 and Figure C-5 detail the workflow for generating each of the recipient
elements of the sere property from the message recipient properties.

Figure C-4
Read message recipient

properties
Is recipient default
SMTP address
present?
Content Management API workflow for generating the recipient

entry of the sere property
MAPI properties
Recipient Type: PR_RECIPIENT_TYPE (ID:0x0C15)
Display name: PR_DISPLAY_NAME (ID:0x3001)
Exchange Address Book Entry Id: PR_ENTRYID (ID:0x0FFF)
Email address: PR_EMAIL_ADDRESS (ID:0x3003)
Email address type: PR_ADDRTYPE (ID:0x3002)
Default SMTP Address: PR_SMTP_ADDRESS (ID:0x39FE)
Original email address: PR_OrgEmailAddr (ID:0x403E )
Original email address type: PR_OrgAddrType (ID:0x403D)
yes
Add recipient display name and recipient default

SMTP address to Message Sender and Recipient
property
yes
Add recipient display name and recipient email

yes
Add recipient display name and recipient original

email address to Message Sender and Recipient
property
no
Is recipient
email address an
SMTP address?
no
Is recipient
original email address
an SMTP address?
no
637
638


entry of the sere property (continued)
Figure C-5
no
Is
Enterprise Vault
release 9.0 or later?
yes
SMTP address
found in Active
Directory?
no
no
yes
Read Exchange
Global Address
List entry
Add recipient display name and recipient

Recipient property
MAPI properties
PR_EMS_AB_PROXY_ADDRESSES (ID:0x800F)
Default SMTP address: PR_SMTP_ADDRESS
(ID:0x39FE)
Does Exchange GAL

entry contain default
SMTP address?
no
no
Add recipient display name and Active

Directory SMTP address to Message
yes
no
Does Exchange GAL

entry exist for
recipient entry id?
LDAP properties
legacyExchangeDN
Search Active Directory

for user object
containing recipient
email address
yes
Add recipient display name and

GAL default SMTP address to
property
Add recipient display name and recipient

Recipient property
As indicated in Table C-1, prior to Enterprise Vault 9.0 the Message Sender and
Recipients property may not be available when retrieving MAPI messages using
the Content Management API. This is particularly relevant to items that were
originally inserted using the Content Management API. In such cases the basic
sender and recipient properties are available:

FROM: Display/friendly name (frdn)

FROM: SMTP address (frsm)
FROM: Other email address (frot)
PP: Display/friendly name (ppdn)
PP: SMTP address (ppsm)
PP: Other email address (ppot)
TO: Recipient display/friendly name (rtdn)
TO: Recipient SMTP address (rtsm)
TO: Recipient Other email address (rtot)
CC: Recipient display/friendly name (rcdn)
CC: Recipient SMTP address (rcsm)
CC: Recipient other email address (rcot)
BCC: Recipient display/friendly name (rbdn)
BCC: Recipient SMTP address (rbsm)
BCC: Recipient Other email address (rbot)
The property values are completed with the message sender and recipient email
address values, in accordance with the email address type from the following
MAPI properties:
Sender display name: PR_SENDER_NAME (ID:0x0C1A)
Sender email address type: PR_SENDER_ADDRTYPE (ID:0x0C1D)
Sender email address: PR_SENDER_EMAIL_ADDRESS (ID:0x0C1F)
Sent representing display name: PR_SENT_REPRESENTING_NAME (ID:0x0042)
Sent representing email address type: PR_SENT_REPRESENTING _ADDRTYPE
(ID:0x0064)
Sent representing email address: PR_SENT_REPRESENTING _EMAIL_ADDRESS
(ID:0x0065)
Recipient type: PR_RECIPIENT_TYPE (ID:0x0C15)
Recipient display name: PR_DISPLAY_NAME (ID:0x3001)
Recipient email address type: PR_ADDRTYPE (ID:0x3002)
Recipient email address: PR_EMAIL_ADDRESS (ID:0x3003)
639
640

Typically the SMTP address properties are only populated for non-Exchange
senders and recipients. BCC recipient information is only available for messages
that are archived from the mailbox Sent Items folder. Note also that you cannot
correlate display names and corresponding email address values using these
properties.
How the Enterprise Vault archiving agent processes Exchange envelope

journal messages
The Enterprise Vault Exchange archiving agent handles all MAPI messages exactly
the same, with the exception of the envelope journal report messages that are
delivered to an Exchange journal mailbox. The envelope journal message body is
a journal report; formatted text that reports recipient routing actions, and includes
BCC recipients, recipient redirections and distribution list expansions. The
envelope journal message contains the original message as an attachment.
When the Enterprise Vault Exchange archiving agent archives envelope journal
messages, it attempts to collate all journal reports for a given original message,
and archives them all in a single archived item. The original message is stored as
the primary content of the archived item, and the envelope journal reports are
stored separately within the archived item. The primary content of the archived
item is returned when the Content Management API is used to retrieve the archived
item. The envelope journal reports are not currently accessible using the Content
Management API.
The original message sender and recipient details are processed as described for
Exchange mailbox messages.
See How the Enterprise Vault archiving agent processes Exchange mailbox
messages on page 628.
In addition, the journal reports and the textual content of the envelope message
body are parsed to build the Message Envelope Sender and Recipients (menv)
property.
How the Content Management API processes Exchange envelope

journal messages
Unlike the Enterprise Vault Exchange archiving agent, there is no special
processing for envelope journal messages that are stored using the Content
Management API; an envelope journal message is archived as a MAPI message.
The envelope journal message is stored as the primary content of the archived
item. The envelope journal report is not parsed, and hence the Message Envelope
Sender and Recipient (menv) property is neither indexed nor is it available when
the archived item is retrieved using the Content Management API.


This section describes how the Enterprise Vault Domino archiving agents and the
Content Management API process sender and recipient information for Lotus
Notes mailbox and journal messages.
From Enterprise Vault 8.0 the Content Management API supports Notes messages
inserted in Enterprise Vault Note Stream (.dvns) format. Since Lotus Notes
messages have no native standalone file format, Lotus Notes messages have to
be extracted from an NSF database into an Enterprise Vault Note Stream file using
the Enterprise Vault NSF Manager API. The resulting Enterprise Vault Note Stream
file is inserted using the Content Management API.
See NSF Manager API on page 330.

mailbox messages
The Enterprise Vault Domino archiving agent archives all Lotus Notes messages
in the same manner. The message is stored as the primary content of the archived
item. The message sender and recipients are processed in conjunction with the
Domino Directory to generate the Message Sender and Recipients (sere) property.
recorded in the sere property, together with an entry containing a friendly name
and one or more email addresses. The email address from the message is always
used. If the advanced setting Lookup email addresses is enabled in the Domino
archiving policy, the Domino Directory is used to look up the email address. From
the Domino Directory, the users primary SMTP and Notes email addresses are
added to the sere property, if not already present. Additionally the sere property
is augmented if the advanced setting Expand distribution lists is enabled in the
Domino archiving policy, and a recipient address is listed in the Domino Directory
as a distribution list. In this case, the sere property is augmented with the following
information for the members of the distribution list, as resolved from the Domino
Directory:
Display name
Primary SMTP address
Primary Notes address
When Lotus Notes names are processed, the canonical, hierarchical form names
are translated to their abbreviated format. The abbreviated hierarchical name
format is used as the display name, and the same value is used as the email address.
For example, the canonical name CN=John Smith/OU=Sales/O=Acme results
in a display name and an email address of John Smith/Sales/Acme. When the
641
642

Lotus Notes name is sourced from the Domino Directory, the abbreviated
hierarchical name is appended with the entrys mail domain name. For example,
the canonical name CN=John Smith/OU=Sales/O=Acme in the mail domain
ACMEInc results in the display name and email address values of John
Smith/Sales/Acme@ACMEInc. For SMTP addresses without a display name
element, the local part of the address is used as the display name. For example,
the address JSmith@acme.com results in a display name of JSmith and an
email address JSmith@acme.com.
Domino archiving agent workflow for generating the sender entry
Figure C-6
Notes fields
Read message sender Email address: From
properties
Domain name: FromDomain
Is archiving
policy Lookup
email addresses
enabled?
yes
Search Domino
Directory for user or
group in sender
domain containing
sender
email address
Domino Directory fields

Users view: $Users
Person mail domain name:
MailDomain
Person full name: Fullname
Person SMTP address: InternetAddress
Group name: ListName
Group type: GroupType
Group SMTP address: InternetAddress
Group members: Members
no
User or group entry

found?
yes
Add Domino Directory entry

display name, primary Notes
address, primary SMTP address
and sender
email address to Message
no
sender email address to Message

The same workflow is used for generating the sent representing element of the
sere property, but the logic is based on the message sent representing field; that
is, the Principal field.
643
644

Domino archiving agent workflow for generating the recipient entry

Figure C-7
Read message
recipient properties
and process each
recipient
Is archiving
policy Lookup
email addresses
enabled?
no
Notes fields
TO recipients: SendTo
CC recipients: CopyTo
BCC recipients: BlindCopyTo
yes

Users view: $Users
Person mail domain name: MailDomain
Search Domino
Directory for user
or group in sender
domain containing
sender email address
Group entry found

and DL expansion
archiving policy
enabled?
yes
no
User or group entry

found?
Add Domino Directory entry display

name, primary Notes address,
primary SMTP address and sender
email address to Message Sender
Expand DL members and add each

members display name and
primary Notes and SMTP email
addresses to Message Sender and
Recipient property
yes
Add Domino Directory entry

display name, primary Notes
address, primary SMTP address
and sender
email address to Message Sender
no
sender email address to Message

How the Content Management API processes Lotus Notes mailbox

messages
sender and recipients are processed to generate the Message Sender and Recipients
(sere) property, which is stored in the archived item.
recorded in the sere property, together with an entry containing a display name,
and the email address as listed in the message. The Domino Directory is not used
to lookup additional information. The values parsed from the addresses, and used
for the display name and email address, are the same as used by the Domino
archiving agent.
Figure C-8
Content Management API workflow for generating the sender entry

Read message sender

properties
Notes field
Email address: From
Add sender display name and sender email address

The same workflow is used for generating the sent representing element of the
sere property, but the logic is based on the message sent representing field; that
is, the Principal field.
645
646

Figure C-9

entry of sere property
Read message
recipient properties
and process each
recipient
Notes fields
TO recipients: SendTo
CC recipients: CopyTo
BCC recipients: BlindCopyTo
Add sender display name and sender email address to

Message Sender and Recipient property
How the Enterprise Vault archiving agent processes Lotus Notes journal
messages
The Enterprise Vault Domino archiving agent handles all Lotus Notes messages
exactly the same, with the exception of journal messages that are delivered to a
Domino journaling database. The journal message contains additional Notes fields
detailing the journal recipients, including distribution list expansions.
When the Enterprise Vault Domino archiving agent archives journal messages,
the journal message is stored as the primary content of the archived item.
recorded in the Message Sender and Recipients (sere) property as described for
Lotus Notes mailbox messages.
See How the Enterprise Vault archiving agent processes Lotus Notes mailbox
messages on page 641.
Additionally the journal recipients Notes fields are processed to generate the
Message Envelope Sender and Recipients (menv) property, together with an entry
containing a friendly name and one or more email addresses. The display name
and email address from the Notes field are always used. The Domino Directory is
used to look up the email address. From the Domino Directory, the users primary
SMTP and Notes email addresses are added to the menv property, if not already
present.
the menv property from the message journal recipient properties.

Figure C-10
Read message
envelope recipient
properties and process
each recipient
Search Domino Directory for

user
or group containing sender
email address
User or group entry

found?
Notes fields
Journal recipients: $JournalRecipients
Journal expanded group recipients:
$JournalRecipientsExpanded_<n>
or
Envelope recipients: Recipients

Users view: $Users
Person mail domain name: MailDomain
yes
no
Domino archiving agent workflow for generating recipient entry of

menv property
Add Domino Directory entry display name, primary

Notes address, primary SMTP address and sender
email address to Message Envelope Sender and
Recipient property
Add sender display name and sender email address

to Message Envelope Sender and Recipient property
How the Content Management API processes Lotus Notes journal

messages
Unlike the Enterprise Vault Domino archiving agent, there is no special processing
for journal messages. The journal recipient Notes fields are not processed. This
means that the Message Envelope Sender and Recipient (menv) property is neither
647
648

SMTP messages
indexed, nor is it available when the archived item is retrieved using the Content
Management API.
SMTP messages
The Content Management API supports SMTP messages inserted in MIME format
(.eml). There is no difference in behavior between SMTP messages archived using
the Content Management API and those archived by the Enterprise Vault SMTP
Archiving feature.
How the Content Management API processes SMTP messages

This section describes how the Content Management API processes sender and
recipient information when archiving SMTP messages.
sender and recipients are processed to generate sere property at various points
in the handling of an archived item, dependent on the version of Enterprise Vault.
See Table C-2 on page 648.
Since the generation of the sere property does not add any additional information
to that available in the message, there is no difference in search capabilities for
SMTP messages that are indexed prior to Enterprise Vault 10.0.
Table C-2
Content Management API support for the sere property for SMTP
messages
Enterprise Vault
8.x
Message Sender and No

Recipients (sere)
property is generated
on insertion and
stored in the
archived item
Enterprise Vault
9.x
Enterprise Vault
10.x
No
Yes

SMTP messages
Table C-2
Content Management API support for the sere property for SMTP
messages (continued)
Enterprise Vault
8.x
Enterprise Vault
9.x
Enterprise Vault
10.x
No
No
Yes
Sender/Recipient
No
details are generated
dynamically when
the item is retrieved
(if not stored in
archived item)
No
Yes
If the Message
Sender and
Recipients (sere)
property is not
present in the
archived item, it is
generated
dynamically when
the item is indexed
Prior to Enterprise Vault 10.0, the sere property may not be available when
retrieving SMTP messages using the Content Management API. In such cases the
basic sender and recipient properties are available:
649
650

FROM: Display/friendly name (frdn)

FROM: SMTP address (frsm)
FROM: Other email address (frot)
PP: Display/friendly name (ppdn)
PP: SMTP address (ppsm)
PP: Other email address (ppot)
TO: Recipient display/friendly name (rtdn)
TO: Recipient SMTP address (rtsm)
TO: Recipient Other email address (rtot)
CC: Recipient display/friendly name (rcdn)
CC: Recipient SMTP address (rcsm)
CC: Recipient other email address (rcot)
BCC: Recipient display/friendly name (rbdn)
BCC: Recipient SMTP address (rbsm)
BCC: Recipient Other email address (rbot)
The property values are completed with the message sender and recipient email
address values, in accordance with the email address type from the following
SMTP header fields:
Sender: From
Sent representing: Sender
Primary recipients: To
Carbon copy recipients: Cc
Blind carbon copy recipients: Bcc

The Content Management API can be used to copy or move archived items either
within an Enterprise Vault site or between sites, using the Item object.
Intra-site copying of archived items

For intra-site copies, the CopyTo method provides support of full fidelity copying
of archived items.

See IItem :: CopyTo on page 201.

The best practice for moving archived items within a site is as follows:
Copy the items.
Wait for the destination items to be secured (as indicated by the IsItemSecured
property of the ArchiveMetadata object).
See IArchiveMetaData :: IsItemSecured on page 237.
Delete the source item.
Using the MoveTo method for intra-site moves is not recommended, as this deletes
the source item before the destination item has been secured. The archived item
could be lost in a disaster recovery scenario.
Inter-site copying of archived items

For inter-site copies, the Get and Insert methods provide basic support for copying
archived items. However, the copy is not a full fidelity copy because of the
differences highlighted earlier in this appendix.
The primary difference relates to the handling of sender and recipient details
when indexing the archived items. The default behavior is that the Message Sender
and Recipients (sere) property and the Message Envelope Sender and Recipients
(menv) property are not preserved. They may potentially be regenerated at the
destination site based on the destination site's environment and configuration,
and the domain directory for the destination site may not be the same as that for
the source site. From Enterprise Vault 8.0 SP4 the properties are preserved if the
account used to perform the copy is an Enterprise Vault role that includes the
operation, {API} Can Use Extended API Features in both the source and
destination sites. This operation is included in the Enterprise Vault Power
Administrator and Storage Administrator roles.
The second difference relates to copying Exchange envelope journal messages
from Exchange journal archives. The journal reports are not preserved when
copying using the Get and Insert methods.
The best practice for moving archived items between sites is as follows:
Copy the items.
Wait for the destination items to be secured, (as indicated by the IsItemSecured
property of the ArchiveMetadata object).
See IArchiveMetaData :: IsItemSecured on page 237.
Delete the source item.
651
652

Why a retrieved item is not a binary copy of the original item
Why a retrieved item is not a binary copy of the

original item
Enterprise Vault preserves the set of properties of message items that are archived
and retrieved using the Content Management API. When the archived item is
retrieved the same set of properties are present in the retrieved message, but it
is not a binary copy of the original item. The main reason for this is that when
the archived item is copied to a new instance of the message's external format,
Enterprise Vault cannot control how the message properties are persisted to a
stream of bytes. Also, Enterprise Vault may add Enterprise Vault specific properties
to the retrieved item, for example the archived item's Archive Id and Item Id.
For MAPI items, the Outlook Message Format is used as the persisted format of
the message. This format is based on the Microsoft Structured Storage format.
When Enterprise Vault copies the properties of the archived message back to a
new instance of a Structured Storage, it is the Microsoft Structured Storage API
that determines how the properties are persisted to a stream of bytes. Additional
differences may be apparent, as the Microsoft MAPI API that is used to copy the
properties adds or updates a number of "computed" properties, such as modified
date, which cannot be managed by Enterprise Vault.
For Lotus Notes messages there is no native standalone file format, so Lotus Notes
messages have to be retrieved in Enterprise Vault Note Stream format, and then
inserted into an NSF database. As the Enterprise Vault Note Stream format is
based on the Microsoft Structured Storage format, the behavior is the same as
that already described for MAPI items .
For SMTP messages, the properties of a message may be persisted using a variety
of encoding schemes, such as quoted printable, base64, 7bit, and binary. In
addition, different character sets may be used, for example utf-8, iso-8859-1,
Windows-1252. Enterprise Vault may return SMTP items using an encoding
scheme that differs from the original item, but the character set(s) typically remain
unchanged.
Index
AddProperty method
ISearchQuery interface methods
SearchQuery object 476
AddQuery method
Indexes
updating 439
Indexing items 438
Indexing levels 442
IndexSearch2 object
Search API
SelectArchive method 505
interface methods
AddProperty
AddQuery
SelectArchive
IndexSearch2 object 505
SetProperty
AddProperty method 476
AddQuery method 481
SetProperty method 474
items
compressing 438
converting 438
C
compressing items 438
constants
ESearchQueryFlags constant
Search API 458
Converting items 438
Custom Filtering API
get_defaultRetentionCategoryId methods
IArchivingControl interface 366
ProcessFilter method
IExternalFilter interface 359
E
Enterprise Vault documentation 19
Search API 458
F
File system filter reports 393
flags
Search API 458
G
get_defaultRetentionCategoryId methods
Custom Filtering API 366
granularity of search results
attachment 444
item 444
M
methods
SelectArchive
IndexSearch2 object 505
P
ProcessFilter method
Custom Filtering API 359
S
Search API
ESearchQueryFlags constant 458
searches
overview of performing a search 449
654
Index
searches (continued)
results, processing 452
SearchQuery object
SearchQuery interface methods
AddProperty 476
AddQuery 481
SetProperty 474
SelectArchive method
IndexSearch2 object
Search API 505
SetProperty method

EV10 API Reference

Uploaded by

EV10 API Reference

Uploaded by

Symantec Enterprise Vault

Application Programmer's Guide

Symantec Enterprise Vault: Application Programmer's

Technical Support ............................................................................................... 3

About this guide .................................................................. 19

About API updates .......................................................................

Enterprise Vault API overview .......................................... 47

Content Management API ................................................. 59

EV_STG_API_CP_SETBY enumeration ....................................... 79

IArchive :: Description .................................................................

IContent :: Title ..........................................................................

ISimpleIndexProperty :: System ....................................................

IDiagnosticsAPI : Trace ............................................................... 326

NSF Manager API ............................................................... 329

About the Filtering APIs ..............................................................

IArchivingControl :: Action ..........................................................

IArchivingControl :: OriginalRetentionCategoryID ............................

Search API ........................................................................... 435

IIndexSearch2 :: Options ..............................................................

ISearchResults :: Start .................................................................

Retention API ...................................................................... 561

IRetentionCategory :: Description ..................................................

Enterprise Vault properties ............................................. 595

API return values ............................................................... 619

Understanding how Enterprise Vault archives and

How the Enterprise Vault archiving agent processes Exchange

Index ................................................................................................................... 653

About this guide

Introducing this guide

Enterprise Vault documentation

Comment on the documentation

Introducing this guide

Enterprise Vault documentation

Comment on the documentation

About this guide

The topic (if relevant) you are commenting on

Email your comment to evdocs@symantec.com. Please only use this address to

About API updates

Enterprise Vault 10.0.1

Enterprise Vault 10.0

Enterprise Vault 9.0 SP3

Enterprise Vault 9.0

Enterprise Vault 8.0 SP5

Enterprise Vault 8.0 SP4

Enterprise Vault 8.0 SP3

Enterprise Vault 8.0 SP2

Enterprise Vault 8.0 SP1

Enterprise Vault 8.0

Enterprise Vault 7.0 SP4

Enterprise Vault 7.0

About API updates

Enterprise Vault 10.0.1

Changes and corrections

Note the following information about dates in Enterprise Vault index

Exchange Filtering API

Changes and corrections (continued)

Content Management API

Content Management API

Enterprise Vault 10.0

Changes to Filtering APIs

Changes to Filtering APIs (continued)

Changes to Search API

Changes to Search API (continued)

The default timeout value for search requests (IIndexSearch2 ::

Changes to Content Management API

The Enterprise Vault system property, shct, is no longer supported.

In the EV_STG_API_INDEX_LEVEL enumeration,

If you used the IArchiveMetaData::CustomIdentifier and

The sender and recipient indexing metadata and the Vault

When attempting to retrieve items from slow devices, Enterprise Vault

Changes to Content Management API (continued)

A new ReadMe file is included with the Content Management API

Using the Content Management API to migrate Enterprise Vault

See About storing and retrieving message items on page 627.

Enterprise Vault 9.0 SP3

Changes to Content Management API