Symantec Enterprise Vault: Application Programmer's Guide

Download as pdf or txt
Download as pdf or txt
You are on page 1of 692

Symantec Enterprise Vault™

Application Programmer’s Guide

Enterprise Vault 9.0 SP1


Symantec Enterprise Vault: Application
Programmer’s Guide
The software described in this book is furnished under a license agreement and may be
used only in accordance with the terms of the agreement.

Last updated: November 19, 2010.

Legal Notice
Copyright © 2010 Symantec Corporation. All rights reserved.

Symantec, the Symantec Logo, Veritas, Enterprise Vault, Compliance Accelerator, and
Discovery Accelerator are trademarks or registered trademarks of Symantec Corporation
or its affiliates in the U.S. and other countries. Other names may be trademarks of their
respective owners.

This Symantec product may contain third party software for which Symantec is required
to provide attribution to the third party (“Third Party Programs”). Some of the Third Party
Programs are available under open source or free software licenses. The License
Agreement accompanying the Software does not alter any rights or obligations you may
have under those open source or free software licenses. Please see the Third Party
Software file accompanying this Symantec product for more information on the Third
Party Programs.

The product described in this document is distributed under licenses restricting its use,
copying, distribution, and decompilation/reverse engineering. No part of this document
may be reproduced in any form by any means without prior written authorization of
Symantec Corporation and its licensors, if any.

THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED


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

The Licensed Software and Documentation are deemed to be commercial computer


software as defined in FAR 12.212 and subject to restricted rights as defined in FAR
Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS
227.7202, "Rights in Commercial Computer Software or Commercial Computer Software
Documentation", as applicable, and any successor regulations. Any use, modification,
reproduction release, performance, display or disclosure of the Licensed Software and
Documentation by the U.S. Government shall be solely in accordance with the terms of
this Agreement.

Symantec Corporation
350 Ellis Street
Mountain View, CA 94043

http://www.symantec.com
Technical Support
In order to develop software using Enterprise Vault APIs, your company must be
a member of Symantec Technology Enabled Program (STEP).
For details of the technical support available to you, refer to your STEP
membership documentation, or contact the STEP office at
[email protected].
Further information about STEP is available at the following address:
http://go.symantec.com/step
Contents

Technical Support .................................................................................................. 3

Chapter 1 About this guide


Introducing this guide .........................................................................................15
Enterprise Vault documentation .......................................................................15
Comment on the documentation .......................................................................15

Chapter 2 API updates


Notice of future changes .....................................................................................17
Enterprise Vault 9.0 .............................................................................................18
Enterprise Vault 8.0 SP5 .....................................................................................18
Enterprise Vault 8.0 SP4 .....................................................................................20
Enterprise Vault 8.0 SP3 .....................................................................................21
Enterprise Vault 8.0 SP2 .....................................................................................23
Enterprise Vault 8.0 SP1 .....................................................................................24
Enterprise Vault 8.0 .............................................................................................25
Enterprise Vault 7.0 SP4 .....................................................................................30
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0
SP5 ..................................................................................................................31
Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4
33
Enterprise Vault 7.0 .............................................................................................34

Chapter 3 Enterprise Vault


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

Chapter 4 Content Management API


About the Content Management API ................................................................49
6 Contents

General guidelines for using the API ................................................................ 52


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

IArchive :: ItemCount ........................................................................................144


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

IContent :: Author .............................................................................................. 235


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

IHolds :: Count ....................................................................................................318


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

Chapter 5 NSF Manager API


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

INSFManager :: CloseNSF ................................................................................. 379


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

Chapter 6 Retention API


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

Chapter 7 Filtering APIs


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

IArchivingControl :: currentVaultId ...............................................................443


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

ILotusArchivingControl :: Action .................................................................... 491


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

Chapter 8 Search API


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

IIndexSearch2 :: IndexVolumeSets .................................................................568


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

ISearchResults :: Total ...................................................................................... 632


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

Appendix A About Enterprise Vault indexes


About index volume sets and volumes ........................................................... 659
About index schemas ........................................................................................ 660

Appendix B Enterprise Vault Properties


System properties .............................................................................................. 664
Defined custom properties ............................................................................... 680
Defined custom FSA properties ....................................................................... 681
Defined custom SharePoint properties .......................................................... 681
Defined properties for Compliance Accelerator ........................................... 682

Appendix C API return values


Content Management API return values ....................................................... 685
Retention API return values ............................................................................ 686
Search API return values .................................................................................. 687
External Filter API Event log messages ......................................................... 688

Index ......................................................................................................691
Chapter 1
About this guide
This chapter includes the following topics:
■ “Introducing this guide”
■ “Enterprise Vault documentation”
■ “Comment on the documentation”

Introducing this guide


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

Enterprise Vault documentation


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

Comment on the documentation


Let us know what you like and dislike about the documentation. Were you able
to find the information you needed quickly? Was the information clearly
16 About this guide
Comment on the documentation

presented? Report errors and omissions, or tell us what you would find useful in
future versions of our guides and online help.
Please include the following information with your comment:
■ The title and product version of the guide you are commenting on
■ The topic (if relevant) you are commenting on
■ Your name
Email your comment to [email protected]. Please only use this address to
comment on product documentation.
We appreciate your feedback.
Chapter 2
API updates
This chapter lists changes made to the APIs, SDK, or this API manual, and
advance notice of future changes to Enterprise Vault APIs.

Notice of future changes


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

Enterprise Vault Properties


From Enterprise Vault 10, the Enterprise Vault system property, shct, will no
longer be supported.

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

Enterprise Vault 9.0


This section lists the changes and corrections made for Enterprise Vault 9.0.

Content Management API

Ref Change details

MSXML 6.0 or later is now required on the computer where you


install the Enterprise Vault API runtime.

900-1652 Guidance on thread priority has been added.


See “General guidelines for using the API” on page 52

900-2524 The sender and recipient index properties, and the Vault.MsgDirection and
Vault.MsgType custom index properties are now stored on item insert
operations. These properties are also preserved during copy and move item
operations.

900-2677 Added the method IItem3::Undelete.


If an item has been moved to the Enterprise Vault "dumpster" area (soft
deleted), this method can be used to recover the item.
See “IItem3 :: Undelete” on page 217

2050482 When inserting Outlook messages, either the FileExtension property must
have the value “.msg”, or the MIMEFormat property must have the value
“application/vnd.ms-outlook”, to provide full Enterprise Vault indexing and
storage optimization functionality. If you assign any other MIME type value
to an item, Enterprise Vault archives and indexes the item as a file.
See “IItem :: Insert” on page 196
See “IContent :: FileExtension” on page 224
See “IContent :: MIMEFormat” on page 226

Enterprise Vault 8.0 SP5


This section lists the changes and corrections made for
Enterprise Vault 8.0 SP5.
API updates 19
Enterprise Vault 8.0 SP5

Content Management API

Ref Change details

8053386, The property type for IArchive::Size was incorrectly shown as ULONGLONG
E2030385 instead of VT_UI8. This has been corrected.
See “IArchive :: Size” on page 138

E2133959 ISimpleIndexProperty :: Value now has a fuller description of possible values


for the property.
See “ISimpleIndexProperty :: Value” on page 299

Filtering APIs

Ref Change details

8054561, HARD_DELETE is now available as an option in the Domino action


E2096343 enumeration.
See “EV_ACTION enumeration” on page 433

E1980890 The following sections have been expanded to provide more information on
the filtering registry settings:
See “Exchange filtering registry settings” on page 430
See “Domino filtering registry settings” on page 474

E2095734 The remarks in the section, IArchivingControl2 :: MAPISaveChanges, now


clarify that changes made to messages are saved in the Exchange Server
store. The changes are saved in the archive when the message is
subsequently archived.
See “IArchivingControl2 :: MAPISaveChanges” on page 467

Enterprise Vault properties

Ref Change details

E2027779 Added the property, Vault.CopiedFrom, to the list of custom properties


defined in Enterprise Vault. This property provides details for items that
have been copied by Move Archive.
See “Defined custom properties” on page 680
20 API updates
Enterprise Vault 8.0 SP4

Ref Change details

E2139819 The following index properties have been added to the list of Enterprise
Vault system properties:
■ Calendar start date (csrt)
■ Calendar end date (cend)
■ Calendar location (clon)
■ Task due date (tddt)
■ Task date completed (tcdt)
■ Task status (tsts)
See “System properties” on page 664

Enterprise Vault 8.0 SP4


This section lists the changes and corrections made for
Enterprise Vault 8.0 SP4.

Content Management API


Enterprise Vault 8.0 SP4 includes the following changes and corrections to the
Content Management API documentation:

Ref Change details

E1927661 Updated IContent :: FileExtension section in the manual to clarify the when
a preceding period is included in file extensions.
See “IContent :: FileExtension” on page 224

E1533874 The manual indicated that the Vault Store ID must be set before Archive::Get
is called. This is incorrect. The manual has been updated.

E1669297 The description of the EV_STG_API_ITEM_DETAIL enumeration has been


expanded to show the properties that are returned for the different
enumeration values.
See “EV_STG_API_ITEM_DETAIL enumeration” on page 65

804-1613, When using the CopyTo function, the source item's Sender/Recipients P1
E1948433 data was not retained and merged with any specified custom index
properties for adding to the destination/copied item.
This has been fixed.
API updates 21
Enterprise Vault 8.0 SP3

Ref Change details

8041728, If the converted content for an item or attachment is larger than 5MB, then
E1950563 it is not returned in the 'cont' property when a call to Item.Get requests
DETAIL_LEVEL__SYSTEM_INDEXDATA.
If required, you can override this limit using the registry setting,
HKLM\Software\KVS\Enterprise Vault\MaxIndexDataHTMLContentKB
The registry setting is documented in the Enterprise Vault Registry Values
manual.
See “IItem :: Get” on page 200

Search API
Enterprise Vault 8.0 SP4 includes the following changes and corrections to the
Search API documentation:

Ref Change details

E1448964 Information has been added to the Search API chapter on how to create
multiple index volume sets for testing search applications.
See “Performing a search” on page 524

Enterprise Vault 8.0 SP3


This section lists the changes and corrections made for
Enterprise Vault 8.0 SP3.

Content Management API


Enterprise Vault 8.0 SP3 includes the following changes and corrections to the
Content Management API documentation:

Ref Change details

803151 A new interface, IItem2, has been added to the Content Management API.
This interface inherits from IItem, and provides the property,
DeletionReason, which enables calling applications to find out why an item
was deleted from the archive.
See “IItem2 :: DeletionReason” on page 215
22 API updates
Enterprise Vault 8.0 SP3

Ref Change details

803137 Soft deleted items are no longer included when populating the Items
collection object.
See “Items object” on page 162

803069, When using the Archive object to retrieve details for an archive that was
E1630338 created prior to Enterprise Vault 7.0, the ConvertedContent and
IndexUrgency properties could contain misleading values, as these
properties were introduced at Enterprise Vault 7.0.
When retrieving details for pre-Enterprise Vault 7.0 archives, these
properties are now given the following default values:
IndexUrgency = INDEX_ITEMS_IMMEDIATELY
ConvertedContent = CONVERTED_CONTENT_STORED

E1810317 The S_FALSE return value has been documented for the following object
properties.
■ IItem::Id
■ IContent::OriginalLocation
■ IArchiveMetaData::RetentionCategory
■ IArchiveMetaData::CustomIdentifier
■ IArchiveMetaData::CustomQualifier
■ ArchiveMetaData::CustomProperties
■ IArchiveMetaData2::CurrentLocation
■ IArchiveMetaData2::CurrentFolderId
■ IArchiveMetaData2::ArchivedDate
These properties can return the default property value and an S_FALSE
return value when reading the property before it has been written. This is a
success return value. When coding in C++ the S_FALSE return value should
be handled using the Windows SUCCEEDED or FAILED macros.

803587, When populating very large Archives collection objects, the value of the
E1737966 Maximum property (the maximum number of records that can be returned)
was not honored. As a result, the operation failed, and insufficient resource
errors were reported.
This has been fixed.

803125, Sometimes files of between 5 MB and 50 MB were truncated when retrieved


E1726196, using the Content Management API .
E1739537 This has been fixed.
API updates 23
Enterprise Vault 8.0 SP2

Ref Change details

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

Enterprise Vault 8.0 SP2


This section lists the changes and corrections made for
Enterprise Vault 8.0 SP2.

Content Management API


Enterprise Vault 8.0 SP2 includes the following additions and changes to the
Content Management API documentation:

Ref Change details

802168 A new interface, IExtendedErrorInfo, has been added. This interface


provides extended error information if an error is encountered when using
the Content Management API methods.
See “ExtendedErrorInfo object” on page 355.

802077 EV_STG_API_AUTHENTICATE_USING enumeration has new value added:


AUTHENTICATE_USING_MOST_APPROPRIATE_MODE
See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 60.

802559, IContent::Title no longer needs to be populated before calling Insert.


E1703228,
See “IItem :: Insert” on page 196.
E1639951

802577, IArchive::Name and IArchive::Description can contain printable, Unicode


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

Enterprise Vault 8.0 SP1


This section lists the changes and corrections made for
Enterprise Vault 8.0 SP1.

Content Management API


Enterprise Vault 8.0 SP1 includes the following additions and changes to the
Content Management API documentation:

Ref Change details

8010032 The new value, ITEM_COPYOPTIONS_MERGE_INDEXMETADATA, has been


added to the EV_STG_API_ITEM_COPYOPTIONS enumeration. This enables
additional custom index metadata properties on the source item to be added
to existing custom index metadata properties on the destination item.
See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 64

8010141 The new interface, IHolds2, has been added. This provides the method,
ReleaseHolds2, which can be used to release a hold on each item in a
collection, and also returns a summary status report, in XML, for each vault
store in which items were processed.
See “IHolds2 :: ReleaseHolds2” on page 330

8010204, If the source archive was in a read-only state, CopyTo failed and returned the
E1422959 error CONTENTMANAGEMENTAPI_E_BUSY.
This has been fixed.
Further changes have been made to support situations where an archive is in
a read-only state. The error
CONTENTMANAGEMENTAPI_E_NO_ACCESS
(Status code = 0x80040303)
is now returned when the following actions are attempted:
■ Copying an item when the destination archive is in a read-only state.
■ Moving an item when the source or destination archive is in a read-only
state.
■ Inserting, deleting, or changing the retention period for an item when
the archive is in a read-only state.
In addition, the IItem::CanBeDeleted property value will indicate
DELETE_ACCESS_DENIED for items located in an archive which is in a
read-only state.
API updates 25
Enterprise Vault 8.0

Ref Change details

8010139 If a hold with the same ConsumerGUID or GroupId was reapplied to an item,
a new hold was created instead of returning the existing hold ID.
This has been fixed.

Enterprise Vault 8.0


This section lists the changes and corrections made for Enterprise Vault 8.0.

Minimum supported OS version


The Content Management API features introduced at Enterprise Vault 8.0
require Windows Server 2003 or later.

Changes to programming language support

Visual Basic 6.0


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

Visual Basic Script


The ContentManagement API interfaces, IArchive3 and IArchiveMetaData2, are
not directly accessible by Visual Basic Script applications. To access properties
on these interfaces, the Visual Basic Script application can perform a
QueryInterface using the new IDispatchQueryInterface method and specifying
the required Interface Identifier (IID) string.

General changes
Audit logging can now be enabled for item operations.
See “Audit logging” on page 56.
The name of the Enterprise Vault SDK kit has changed to
Symantec Enterprise Vault Software Development Kit.msi
26 API updates
Enterprise Vault 8.0

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.

Content Management API


Enterprise Vault 8.0 includes the following additions and changes to the Content
Management API documentation:

Ref Change details

■ The following new interfaces have been added to the Content


Management API:
IContentManagementAPI3
IArchive3
IItems
IArchiveMetaData2

BAU0819 ■ IContentManagementAPI3::
IDispatchQueryInterface method has been added to enable calling
applications written in Visual Basic Script to access IArchive3 and
IArchiveMataData2 properties.
See “IContentManagementAPI3 :: IDispatchQueryInterface” on
page 91.

BAU0819 ■ IArchive3 interface adds new read/write Type, SecurityDescriptor and


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

BAU0819 ■ The EV_STG_API_PERMISSIONS_TYPE enumerator is now used in


BAU2464 place of the DV_DS_E_PERMISSION enumerator when creating the
security descriptor for use with IArchive::SecurityDescriptor.

BAU0225 ■ A new interface, IItems, has been added to facilitate the enumeration of
items in an archive.
“Enumerating vault stores, archives and items” on page 53.
API updates 27
Enterprise Vault 8.0

Ref Change details

BAU0778 ■ Significant changes have been made to facilitate copying and moving
BAU0795 items from one archive to another :
BAU1179 ■ The default action has changed; the item content and its
associated ArchiveMetaData and IndexData elements are copied
from the source item to the destination item. This means that the
new default behaviour preserves the original ArchivedDate and
OriginalLocation on the destination item, if override values are
not specified.
For backwards compatibility, the calling application can set
suitable override values on the destination item object.
■ A new CopyOptions property identifies the source item property
values to be copied to the destination item when copying or
moving items.
Override values can be set for specific Item properties.
See “Specifying item property override values” on page 193.

BAU0378 ■ IArchiveMetaData2 provides additional properties for determining the


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

BAU0378 ■ The new IArchiveMetaData2::SequenceNum property (ULONGLONG)


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

BAU778 ■ A new read/write IArchiveMetaData2::ArchivedDate property enables


the caller to set the UTC date and time when an item was stored.
To prevent unauthorized users, who have write access to an archive,
from changing the archived date of an item, the calling application
must run under an account assigned to the Enterprise Vault Power
Administrator role or Storage Administrator role.
28 API updates
Enterprise Vault 8.0

Ref Change details

BAU1179 ■ The following properties, which were previously hidden, have now been
BAU2853 exposed for public use:
IArchiveMetaData::CustomIdentifier
IArchiveMetaData::CustomQualifier
IArchiveMetaData::CustomProperties
These properties can be used to hold proprietary information about the
stored item.
CustomIdentifier and CustomQualifier can be used to identify items
when using Get.

BAU1761 ■ IHold::ItemId property value can now be a valid Saveset Id or


Transaction Id.
See “Saveset IDs and Transaction IDs” on page 54.

BAU1473 ■ The Content Management API now supports IStream and ILockBytes
implementations where the input data length provided by the Stat
method is not known.

BAU1796 ■ Enhancements to the API mean that .NET applications no longer need
to call CoInitializeSecurity when remotely accessing IStream or
IlockBytes objects containing large items (larger than 4MB).
■ The Content Management API threading model has been changed from
COM single-threaded apartment (STA) to Both, thus simplifying use in
.NET applications.

BAU2013 ■ MSXML 3.0 is now the minimum version of MSXML required on the
computer where you install the application using the Content
Management API.
API updates 29
Enterprise Vault 8.0

Retention API

Table 2-1 Changes to Retention API

Ref Change details

BAU1072 Enabled the caller to set the date from which storage expiry is calculated.
Added the following interfaces, method and property:
■ IRetentionCategories2
Improved the retrieval of retention category details by providing a Get
method.
■ IRetentionCategory2
Provides ExpiryBasis property for determining date from which storage
expiry is calculated.

Migration API

Table 2-2 Change to Migration API

Ref Change details

BAU2485 The MigratedFileId parameter of the SendFile method identifies the object or
file in the external storage system, and must be unique within the partition.
The migrator must now explicitly set this value.

New index properties added

Table 2-3 New index properties

Ref Index property Description


name

BAU0585 crct Current Retention Category Id, searchable and retrievable

BAU0931 clcn Current location, retrievable only


cllf Current leaf folder name, retrievable only
clfn Current location folder names, retrievable only
crcn Current Retention Category name, retrievable only

BAU1320 cnhv Conversation Hierarchical View, retrievable only

BAU1426 fpdd Index Fingerprint of item, searchable and retrievable


fpcn Index Fingerprint of content, searchable and retrievable
30 API updates
Enterprise Vault 7.0 SP4

Corrections

Table 2-4 Corrections

Ref Change details

1088101, The Storage service is no longer accessed when enumerating archives.


847952

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


copy or move operation.

1271036 Description of IArchiveMetaData::RetentionExpires property has been


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

Enterprise Vault 7.0 SP4


This section lists the changes and corrections made for
Enterprise Vault 7.0 SP4.

Table 2-5 Corrections

Ref Change details

E1107082 Updated description of “IContent :: FileExtension” on page 224.

E1143215 Added description of the use of wildcard characters in ESQfilter searches.

E1167957 Updated information about supported combinations of properties in “Archives


object” on page 109.

E1185396 Added “IContentManagementAPI2 :: VaultStore” on page 87.

E1187820 Corrected description of “ISimpleIndexMetadata :: Count” on page 283.

E1188342 Corrected description of “IItem :: CanBeDeleted” on page 206.

E1191078 Added example format for the consumer GUID in


“IHold :: ConsumerGUID” on page 342.

E1193018 Updated information about retrieving items, and added information about
retrieving hold data, in “IItem :: Id” on page 177.

E1196051 Updated description of “ComplianceData object” on page 307 to note that it is


for use only with compliance devices, and updated Return values for
“IArchiveMetaData :: Update” on page 263.
API updates 31
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5

Table 2-5 Corrections

Ref Change details

E1203217 Updated Remarks section of “IHolds :: Item” on page 317 to note that the index
supplied to the property is 1-based not 0-based.

Enterprise Vault 2007 SP1, Enterprise Vault 7.0


SP3, and Enterprise Vault 6.0 SP5
This section lists the changes and corrections made for Enterprise Vault 2007
SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5.

Table 2-6 Changes and corrections

Ref Change details Availability

751207, ■ New sere index property. This property returns Enterprise Vault 6.0 SP5,
703021, sender and recipient details from the message Enterprise Vault 7.0 SP3,
605047 header (P2) if the archived item is a message. Enterprise Vault 2007 SP1
See Table B-1 on page 664.
■ menv index property changes. This property is
now only returned for journaled messages. It
returns sender recipient details from the
message envelope (P1) if the archived item is an
envelope message. See Table B-1 on page 664.

751208, ■ New interface for Exchange filtering, Enterprise Vault 6.0 SP5,
703020, IArchvingControl3, to retrieve sender and Enterprise Vault 7.0 SP3,
605036 recipient information as XML. See Enterprise Vault 2007 SP1
“IArchivingControl interface for Exchange
filtering” on page 439.

751127, ■ SimpleIndexProperty object: Added new Enterprise Vault 7.0 SP3,


703010 attachment number ("anum") in the returned Enterprise Vault 2007 SP1
index data with the attachment numbering
based on the attachment structure as stored in
the saveset indexable item data stream. See
“ISimpleIndexProperty :: Name” on page 296.
■ menv index property: This property now
includes the message sender/author and
delegate sender (if applicable) encoded in the
<AUTH> element. See Table B-1 on page 664.
32 API updates
Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5

Table 2-6 Changes and corrections

Ref Change details Availability

751143, ■ Previously, where an item’s content data was Enterprise Vault 7.0 SP3,
703011 unobtainable, the cont index metadata property Enterprise Vault 2007 SP1
value was returned with a string,
"<reason>:<type>", where reason was an error
code number and type was the item file type. For
example, "1:MSG".
Now the reason for missing content items is
returned in the content missing property (comr)
in the index metadata.
See Table B-1 on page 664.

703038, ■ IArchive::Create: updated description of Enterprise Vault 7.0 SP3,


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

Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and


Enterprise Vault 6.0 SP4
This section lists the changes and corrections made for Enterprise Vault 2007,
Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4.

Table 2-7 Changes and corrections

Ref Change details Availability

DOR610 ■ The following new Content Management API Enterprise Vault 2007
interfaces have been added to enhance
enumeration of archives and vault stores:
IContentManagementAPI2, IVaultStores,
IVaultStore, IArchives, IArchive2,
ICollectionBase. These interfaces supersede the
functionality previously provided by the
unsupported EnumVaultsByMe method.
■ DirectoryDNSAlias property in the Content
Management API and Retention API has been
enhanced to accept input of any Enterprise
Vault id, such as, archive Id, retention category
Id, vault store Id.
■ New IDiagnosticsAPI interface added to Content
Management API to enable application
integration tracing using Enterprise Vault
diagnostic tools.

DOR620 ■ Simple API removed from API Guide. Refer to Enterprise Vault 2007
previous releases of the manual for this
deprecated API.
■ Migration API included in API Guide.
■ Integrating third-party messaging removed and
now available as a tech note from Enterprise
Vault support knowledge base.
■ Provisioning API removed. This will be
incorporated in the Utilities Guide at a future
release.
34 API updates
Enterprise Vault 7.0

Table 2-7 Changes and corrections

Ref Change details Availability

702045, ■ When the enumerated value, Enterprise Vault 6.0 SP4,


604133, DETAIL_LEVEL_ITEM_CONTENT, was included Enterprise Vault 7.0 SP2
E974294 as part of the input parameter for the Content
Management API method, IItem::Get(), the
current date and time was returned by
IContent::ModifiedDate and
IContent::CreatedDate.
This has been fixed.

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

Enterprise Vault 7.0


This section lists the changes and corrections made for Enterprise Vault 7.0.

Table 2-8 Changes and corrections

Ref Change details Availability

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


instead of the saveset id when setting the
Item::Id property.
API updates 35
Enterprise Vault 7.0

Table 2-8 Changes and corrections

Ref Change details Availability

CAP433 ■ An API license is no longer required in order to Enterprise Vault 7.0


develop applications against the Enterprise
Vault APIs.

CAP463 ■ In previous releases, if an item had been marked Enterprise Vault 7.0
"on hold" using the retention category, then it
could not be deleted, and hence could not be
moved. This has been fixed.

CAP545, ■ IArchivingControl2 interface added to Exchange Enterprise Vault 7.0


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

CAP525 ■ IContentManagementAPI has a new property: Enterprise Vault 7.0


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

Overview of Enterprise Vault APIs


Enterprise Vault SDK comprises a number of APIs. The various Enterprise Vault
APIs are implemented as COM or .NET objects, which expose task-specific
interfaces. For example, archiving items uses the IContentMangementAPI and
IItem interfaces.
In general, applications which use the APIs should be run from a client
computer, and not on the Enterprise Vault server.
38 Enterprise Vault API overview
Overview of Enterprise Vault APIs

To help you choose the appropriate APIs for your application, the available APIs
are listed in Table 3-1. Examples of possible applications are also given to
provide guidance:

Table 3-1 Enterprise Vault APIs

Content Management API ■ Create archives.


■ Enumerate collections of vault stores, archives or items.
■ Get properties of vault stores and archives.
■ List the items in an archive.
■ Store, retrieve, copy, move and delete archived items.
■ Get item properties.
■ Add custom index metadata to an item as it is stored.
■ Place holds on a group of items to prevent items from
being deleted manually or by Enterprise Vault storage
expiry. (Legal Hold)
■ Remove any holds placed on items. (Legal Hold)
Archives and vault stores cannot be deleted using the Content
Management API.

NSF Manager API Enables interaction between Enterprise Vault and Notes
databases:
■ Extract notes from an archive using the Enterprise Vault
Content Management API, and import them into a
database
■ Extract notes from a database and place them in an
Enterprise Vault archive
■ Create and delete databases

Search API ■ Search Enterprise Vault indexes.

Retention API ■ Create new retention categories.


■ Enumerate retention categories.
■ Set locks on a retention category.
■ Update an existing retention category.
■ Look up an existing retention category.
Enterprise Vault API overview 39
Prerequisite software and settings

Table 3-1 Enterprise Vault APIs

Exchange Filtering API External filters enable preprocessing of items in order to


Domino Filtering API decide on the actions to take; for example, whether to archive
the item and which archive settings to apply.
The Filtering APIs provide the ability to:
■ Select certain items for processing (and possibly
archiving), based on attributes (for example, subject text,
sender).
■ Store selected items in specific archives.
■ Set a particular retention category on selected items.
■ Delete selected items without archiving them.
■ Add custom index metadata to selected items before they
are archived.

Note: The Simple API was available in previous releases. This has been replaced
by the Content Management API. For details of the Simple API, refer to the
Enterprise Vault Application Programmer’s Guide included with Enterprise
Vault 6.0.

Prerequisite software and settings


Details of prerequisites for Enterprise Vault are described in the Installing and
Configuring manual.
If you are using the Content Management API, then MSXML 6.0 or later is
required on the computer where you install the Enterprise Vault API runtime.

Permissions
In general, the caller has to have sufficient permissions to access the target
archive.
If the calling application is acting on behalf of clients, and has assumed the
responsibility of checking client permissions prior to proxying calls to the API,
then the caller must have adequate administration permissions. This can be
either Vault Service account permissions, or a suitable Enterprise Vault
administration role, which is assigned using the Enterprise Vault
Administration Console.
Similarly, to create archives, the caller must have either Vault Service account
permissions, or a suitable Enterprise Vault administration role.
Vault Service account permissions are described in the Installing and
Configuring manual.
40 Enterprise Vault API overview
Licensing

Enterprise Vault administration roles are described in the Enterprise Vault


Administration guide.

Licensing
No additional Enterprise Vault license is required in order to develop
applications against the Enterprise Vault APIs. However, customer deployments
of third-party applications which make use of the Enterprise Vault APIs will
require the following license, in addition to any third party licensing
requirements:
■ Symantec Enterprise Vault Custom Archiving Agent license (Enterprise
Vault 8.0)
■ Symantec Generic Ingest Agent license (Enterprise Vault 2007)
This section describes the licensing requirements for the Enterprise Vault APIs.

Development licensing
The Enterprise Vault APIs described in this guide are for developers who wish to
add and/or manage content in Enterprise Vault archives. In most circumstances,
these developers would be granted a Not for Resale (NFR) license to develop to
these APIs by membership of Symantec Technology Enabled Program (STEP).
Customers who wish to develop applications that integrate to these APIs would
need to purchase one of the following licenses and request access to the
Enterprise Vault SDK:
■ Symantec Enterprise Vault Custom Archiving Agent license (Enterprise
Vault 8.0 or later) for ingesting content into Enterprise Vault. This license
also covers management of content archived by Enterprise Vault.
■ Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault
8.0 or later) for management of content archived by Enterprise Vault.
■ Symantec Generic Ingest Agent license (Enterprise Vault 7.0 and Enterprise
Vault 2007) for ingesting content into Enterprise Vault. This license also
covers management of content archived by Enterprise Vault.
■ Symantec Generic Content Management Connector license (Enterprise
Vault 7.0 and Enterprise Vault 2007) for management of content archived
by Enterprise Vault.

Production licensing
The STEP licensing contract does not grant production use of the Enterprise
Vault APIs. Customer deployments of third-party applications and
Enterprise Vault API overview 41
Deploying an application that uses the API

customer-developed applications that make use of the Enterprise Vault APIs will
require one of the following licenses, in addition to any third-party licensing
requirements:
■ Symantec Enterprise Vault Custom Archiving Agent license (Enterprise
Vault 8.0 or later) for ingesting content into Enterprise Vault. This license
also covers management of content archived by Enterprise Vault.
■ Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault
8.0 or later) for management of content archived by Enterprise Vault.
■ Symantec Generic Ingest Agent license (EEnterprise Vault 7.0 and
Enterprise Vault 2007) for ingesting content into Enterprise Vault. This
license also covers management of content archived by Enterprise Vault.
■ Symantec Generic Content Management Connector license (Enterprise
Vault 7.0 and Enterprise Vault 2007) for management of content archived
by Enterprise Vault.

Deploying an application that uses the API


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.
42 Enterprise Vault API overview
Deploying an application that uses the API

Checking the API runtime version and the installation path


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

Checking version and installation path details prior to


Enterprise Vault 8.0
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.
Enterprise Vault API overview 43
Deploying an application that uses the API

To detect if Enterprise Vault server is installed, and find out the installation
location, you can query the following registry settings directly:
■ HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\Install
\VaultServices
If the value of this setting is “Installed”, then Enterprise Vault server is
installed.
■ HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\Install
\InstallPath

Deploying .NET applications


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

Using Visual Studio the required API COM libraries, for example
EVContentManagementAPI.dll, should be added to the application’s
References.

Updating binding redirections in configuration files


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

2 Apply the updates to the configuration file for each .NET application that
uses the Enterprise Vault API Runtime files.

Installing the Enterprise Vault SDK


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
Enterprise Vault API overview 45
Installing the Enterprise Vault SDK

Checking the SDK version and installation path


If you are using Enterprise Vault 8.0 or later, you can query the registry settings
InstallPath and Version in the following location to find out the the version of
the Enterprise Vault API SDK installed and the installation path:
HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\Software Development Kit
\Install
On 64-bit versions of Windows Server, the Enterprise Vault registry settings are
under the following location:
HKEY_LOCAL_MACHINE
\Software
\WOW6432node
\KVS
If you are using a version of Enterprise Vault prior to Enterprise Vault 8.0,
follow the instructions given in “Checking version and installation path details
prior to Enterprise Vault 8.0” on page 42.

SDK examples
An example application for the Content Management API is included in the
Enterprise Vault SDK, in samples\ECM API Sample.
This example application has been built using Visual Studio 2005.
The application does not have a manifest configured. If the target Enterprise
Vault server is running on Windows Server 2008, you may want to add an
application manifest, as described in the MSDN article:
http://msdn2.microsoft.com/En-US/library/bb756929.aspx

To build the test application


1 Install the SDK on your development server.
2 Open the project file TestECMClient.vcproj.
3 You need to tell the compiler where the Enterprise Vault binaries are
located in your environment.
In Visual Studio select
Tools > Options > Projects and Solutions > VC++ directories.
From the Show Directories for drop down list select Executable Files.
Add the folder containing the Enterprise Vault binaries to the list of folders.
46 Enterprise Vault API overview
Programming notes

4 Now build the test application. The application compiles with warnings,
which can be ignored.

Programming notes
■ As the API interfaces are derived from IDispatch, they can be used by
scripting languages.
■ The APIs can be used from C++, .NET languages (such as Visual Basic .NET
and C#), ASP web pages (using Visual Basic Script), and other languages that
support COM.
■ For best performance in a multi-threaded application, use a separate
instance of an API object, such as a Content Management API object, per
thread.

Using the Enterprise Vault APIs in C++


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

Using Enterprise Vault APIs .NET managed languages


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

When referencing a PIA the API types are defined in the namespace
KVS.EnterpriseVault.Interop.
When referencing an Interop assembly the API types are defined in the
namespace of the COM type library name. For example the namespace for the
Content Management API is EVContentManagementAPILib.

Using Enterprise Vault APIs in Visual Basic Script


The Content Management API interfaces, IArchive3 and IArchiveMetaData2,
which were introduced at Enterprise Vault 8.0, are not directly accessible by
Visual Basic Script applications. The Content Management API
IDispatchQueryInterface method enables Visual Basic Script applications to
perform a QueryInterface, specifying the required interface's Interface
Identifier (IID) string.

Code samples
In the code samples given in this manual, attention has been paid to the API
specifics only. Other programming aspects, such as error handling, have been
omitted for clarity.
In general, code samples are included for C++ and C#. As Visual Basic .NET is
very similar to C#, separate examples are not included in most cases.
48 Enterprise Vault API overview
Programming notes
Chapter 4
Content Management API
This chapter provides the following information:
■ An overview of the Content Management API.
■ General guidelines for using the API.
■ Enumerations
■ Detailed reference information on each interface, method and property.

About the Content Management API


The Content Management API comprises the following interfaces:
■ IContentManagementAPI
■ IContentManagementAPI2
■ IContentManagementAPI3
■ IContentManagementAPI4
■ IVaultStores
■ IVaultStore
■ IArchives
■ IArchive
■ IArchive2
■ IArchive3
■ IItems
■ IItem
■ IItem2
■ IItem3
50 Content Management API
About the Content Management API

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

Architecture of Content Management API


Figure 4-1 illustrates the organization of the Content Management API objects.
Content Management API 51
About the Content Management API

Figure 4-1 Hierarchy of Content Management API objects

All the objects shown are exposed by the Content Management API:
■ The ContentManagementAPI object provides a means of accessing the other
objects, such as VaultStores, VaultStore, Archives and Item. These objects
enable the examination of vault stores and archives in Enterprise Vault.
■ The VaultStores object enables applications to enumerate the vault stores
configured in an Enterprise Vault site.The VaultStores object exposes a
standard COM collection interface that manages a collection of VaultStore
objects.
■ The Archives object enables applications to enumerate archives in a vault
store. The properties enable the selection of archives using a combination
of archive name, type and permissions. The Archives object exposes a
standard COM collection interface that manages a collection of Archive
objects.
■ The Items object enables applications to enumerate the items in an archive
in batches. The Enterprise Vault index sequence number of an archived
item is used to determine the first item in a batch. An Items collection can
be enumerated by increasing the index sequence number (oldest archived
item first), or by decreasing the index sequence number (most recently
52 Content Management API
General guidelines for using the API

archived item first). The Items object exposes a standard COM collection
interface that manages a collection of Item objects.
■ The Archive object enables the creation of archives in an Enterprise Vault
vault store.
■ The Item object provides applications with a way to store and manage items
in Enterprise Vault archives.
The following interfaces are implemented by the Item object:
■ IContent interface provides calling applications with a set of properties
that describe the data being archived or retrieved.
■ IArchiveMetaData interface provides calling applications with a set of
properties that describe how the item is archived. The following
interfaces are exposed by IArchiveMetaData:
IComplianceData interface describes the compliance metadata set on
an item in an archive.
ISimpleIndexMetaData interface enables the calling application to add
custom index metadata to an object as it is archived. This can then be
searched for using the Search API.
■ The Holds object provides calling applications with the ability to place or
release legal holds on multiple items at a time with a single call to the
Enterprise Vault server. It exposes a standard COM collection interface that
manages a collection of IHold objects.
■ The Hold object describes a hold that is placed on an item.
■ The ExtendedErrorInfo object provides calling applications with additional
information on internal errors encountered when using Content
Management API interfaces.
■ The DiagnosticsAPI object enables calling applications to use the Enterprise
Vault tracing utility, Dtrace, and write to the Enterprise Vault event log.

General guidelines for using the API


To use the Content Management API you need to obtain an instance of the
ContentManagmentAPI object in the usual manner; by calling CoCreateInstance
(C++), or by using the new operator (.NET managed code), for example.
See “Examples” on page 72.
You can then use the properties and methods on the interface to obtain
instances of other objects.
Consider thread priority if normal Enterprise Vault Exchange Server journal or
mailbox archiving is running in your environment in addition to a Content
Management API application. If the API application archives large numbers of
Content Management API 53
General guidelines for using the API

items, and is considered less important than normal Enterprise Vault Exchange
Server archiving, then the API application should run with a lower thread
priority than THREAD_PRIORITY_NORMAL.

Use of objects
It is best practice for the calling application to keep the ContentManagementAPI
object alive as long as possible, as the ContentManagementAPI object caches
information from Enterprise Vault, and frequent creation and release would
result in poor performance of the client.
Most of the object instances obtained from the ContentManagementAPI object
are designed to be used only once. This prevents reuse of stale data.
Once an object instance has been used (that is, Get, Insert or Create have been
called), it can only be used for querying properties, not for setting them. Before
any of these methods (Get, Insert or Create) can be called again, the existing
object instance should be released and a new one obtained.
For example, the following steps are required when storing an item in an
archive:
■ Obtain an instance of an empty Item object by calling
IContentManagementAPI::Item.
■ Populate its properties (ArchiveId, ArchiveMetaData, Content etc.).
■ Call the Insert method.
■ Retrieve the item’s Id from the object property.
■ Release the Item object instance.
You cannot just repopulate the properties and call Insert again. If you
attempt to do so an error will be reported.
A number of object properties, for example Item.Id, return the default property
value and an S_FALSE return value when reading the property before it has been
written. This is a success return value. When coding in C++ the S_FALSE return
value should be handled using the Windows SUCCEEDED or FAILED macros.
When coding in C# it is not possible to differentiate between the S_OK and
S_FALSE return values.

Enumerating vault stores, archives and items


Archives are held in vault stores, and items are held in archives. When storing
or retrieving items using the Content Management API, or searching for
archived items using the Search API, calling applications need to be able to find
target vault stores and archives. This functionality is provided by the
IVaultStores and the IArchives interfaces. These interfaces enable calling
54 Content Management API
General guidelines for using the API

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
Content Management API 55
General guidelines for using the API

item within a vault store. The Transaction ID would typically only be used to
identify an item processed during filtering.

Format of a Transaction ID value


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

Property validation
The syntax of a property is validated when the property is set, but validation of
the value is typically delayed until the property is used, for example when
invoking the Get method.

Adding custom index metadata


Applications can add custom index metadata to an item as it is archived using
the ISimpleIndexMetadata interface.
See “IArchiveMetaData :: IndexData” on page 253.
When the item is indexed, this custom metadata will be included in the index for
the item. The Search API can then be used to search archives for items with the
custom information.
See Figure 4-2 on page 56.
Custom filtering is available for both Exchange Server Archiving (for the
Exchange Mailbox Archiving Task, Exchange Public Folder Task and Exchange
Journaling Task) and Domino Server Archiving, and the following methods can
be used to add custom index properties:
■ For Exchange Server filtering, the AddIndexedProperty and
AddIndexedPropertyToSet methods of the IArchivingControl interface can
be used.
See “IArchivingControl interface for Exchange filtering” on page 439.
■ For Domino Server filtering, the Add method in the IndexMetadata class
can be used.
See “IArchivingControl interface” on page 483.
56 Content Management API
General guidelines for using the API

Figure 4-2 Adding metadata to the index of an item

You can check that the metadata has been indexed by performing an archive
search for the custom information.

Audit logging
From Enterprise Vault 8.0, audit logging includes Content Management API
item operations. Auditing for various categories of item operations from all
Enterprise Vault agents can be enabled or disabled.
Table 4-1 lists the operations that can be logged and the associated Enterprise
Vault audit category. Audit logging can be enabled for specific audit categories
using the Enterprise Vault Administration Console.

Table 4-1 Operations logged and the associated audit category

API operation Enterprise Vault Audit Category

Insert Archive
CopyTo

MoveTo Archive
Delete 1

Delete Delete
Content Management API 57
General guidelines for using the API

Table 4-1 Operations logged and the associated audit category

API operation Enterprise Vault Audit Category

Get View
1.MoveTo will support two audit entries; one for the item insertion and another for the item deletion from
the original location.

Diagnostic logging and tracing


The DiagnosticsAPI object enables calling API applications to write to the
Enterprise Vault event log and use the Enterprise Vault tracing utility (Dtrace).
DiagnosticsAPI can be used from any external application, including external
filters.
58 Content Management API
Enumerations

Enumerations
This section describes the enumerations used by the Content Management API.

EV_API_DELETION_LEVEL enumeration
Deletion level enumeration defines the type of delete permitted for archived
items:
enum EV_API_DELETION_LEVEL
{
DELETION_LEVEL_SOFT_DELETE = 0,
DELETION_LEVEL_HARD_DELETE = 1
};
Items can be deleted completely (hard delete), or moved to the Enterprise Vault
"dumpster" area (soft delete). The default value is
DELETION_LEVEL_SOFT_DELETE.
In the Enterprise Vault Administration Console, in the Site Properties pages, the
administrator can enable the recovery of deleted items and specify how long
soft-deleted items are to be kept.
This enumeration value is set using the Item DeletionLevel property.
See “IItem :: DeletionLevel” on page 190

EV_API_EVENT_TYPE enumeration
Event type enumeration indicates the type of event:
enum EV_API_EVENT_TYPE
{
EVENT_TYPE_ERROR = 1,
EVENT_TYPE_WARNING = 2,
EVENT_TYPE_INFORMATION = 3,
EVENT_TYPE_SUCCESS_AUDIT = 4,
EVENT_TYPE_FAILURE_AUDIT = 5
};
When an application creates a diagnostic message in the Enterprise Vault event
log using the DiagnosticsAPI LogEvent method, this value indicates the type of
message to create.
See “IDiagnosticsAPI : LogEvent” on page 367

EV_API_ITEMS_ORDERBY enumeration
Items collection order defines whether to increase or decrease the index
sequence number when enumerating a collection of items.
Content Management API 59
Enumerations

enum EV_API_ITEMS_ORDERBY
{
ITEMS_ORDERBY_ASC = 0,
ITEMS_ORDERBY_DESC = 1
};
The default value is ITEMS_ORDERBY_ASC; items are enumerated using
ascending index sequence number order.
See “IItems :: OrderBy” on page 170

EV_API_TRACE_LEVEL enumeration
Trace level enumeration indicates the trace level:
enum EV_API_TRACE_LEVEL
{
TRACE_LEVEL_HIGH = 1,
TRACE_LEVEL_MEDIUM = 2,
TRACE_LEVEL_LOW = 3
};
The method DiagnosticsAPI IsTraceEnabled tests if the specified level of tracing
is enabled in the application for the Enterprise Vault tracing utility (Dtrace).
When sending a trace message to Dtace, the DiagnosticsAPI Trace method uses
this enumeration to set the trace level to be associated with the message.
See “IDiagnosticsAPI : IsTraceEnabled” on page 366 and
“IDiagnosticsAPI : Trace” on page 368

EV_STG_API_ARCHIVE_TYPE enumeration
Archive type enumeration indicates the type of archive:
enum EV_STG_API_ARCHIVE_TYPE
{
ARCHIVE_TYPE_NOT_SET = 0x00000000,
ARCHIVE_TYPE_SHARED = 0x00000001,
ARCHIVE_TYPE_EXCHANGE_MAILBOX = 0x00000002,
ARCHIVE_TYPE_EXCHANGE_JOURNAL = 0x00000004,
ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER = 0x00000008,
ARCHIVE_TYPE_FILE_SYSTEM = 0x00000010,
ARCHIVE_TYPE_SHAREPOINT = 0x00000020,
ARCHIVE_TYPE_DOMINO_JOURNAL = 0x00000040,
ARCHIVE_TYPE_DOMINO_MAILBOX = 0x00000080
};
The properties, Archives ArchiveTypes and Archive Type, select archives based
on the type of archive specified by this enumeration.
See “IArchives :: ArchiveTypes” on page 119
and “IArchive3 :: Type” on page 160
60 Content Management API
Enumerations

EV_STG_API_AUTHENTICATE_USING enumeration
Storage authentication enumeration indicates the authentication mode to use
when authenticating to Enterprise Vault.
enum EV_STG_API_AUTHENTICATE_USING
{
AUTHENTICATE_USING_DCOM_SECURITY = 0,
AUTHENTICATE_USING_AUTHSERVER = 1
AUTHENTICATE_USING_MOST_APPROPRIATE_MODE = 2
};
AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default value.
This value means that DCOM will be used.
Authentication using the Enterprise Vault authentication server can only be
used by applications installed on a configured Enterprise Vault server, and
should only be used on advice from Symantec Support.
See “IContentManagementAPI :: AuthenticationMode” on page 83

EV_STG_API_CAN_DELETE enumeration
Can delete enumeration indicates whether or not the item can be deleted.
enum EV_STG_API_CAN_DELETE
{
DELETE_ALLOWED = 0,
DELETE_ACCESS_DENIED = 1,
DELETE_RETCAT_ONHOLD = 2,
DELETE_ITEM_ONHOLD = 4,
DELETE_ITEM_COMPLIANCE = 8
};
The Item CanBeDeleted method returns the current value for an item.
Values that indicate that the item cannot be deleted have the following
meanings:

DELETE_ACCESS_DENIED The caller may not have sufficient access to the target
archive to delete the item, or the archive may be in a
read-only state.

DELETE_RETCAT_ONHOLD The item's retention category prevents deletion of the item.

DELETE_ITEM_ONHOLD The item cannot be deleted because a legal hold has been
placed on it.

DELETE_ITEM_COMPLIANCE The compliance device on which the item is stored does not
permit deletion

See “IItem :: CanBeDeleted” on page 206


Content Management API 61
Enumerations

EV_STG_API_CONVERTED_CONTENT enumeration
When a file is archived, the Enterprise Vault Storage Service converts the file to
HTML, if possible. The HTML version is used by the Indexing Service to index
the item. The HTML version is also presented to users when the item is
previewed or viewed using the Enterprise Vault Web Access application.
Store converted content enumeration indicates whether converted content is
stored with the item, or generated on demand:
enum EV_STG_API_CONVERTED_CONTENT
{
CONVERTED_CONTENT_STORED = 0,
CONVERTED_CONTENT_ON_DEMAND = 1
};
The property, Archive ConvertedContent, is used to set or retrieve the
enumeration value.
See “IArchive :: ConvertedContent” on page 132

EV_STG_API_CP_SETBY enumeration
Compliance set by enumeration is for use with compliance devices only. It
indicates where the compliance retention period is set:
enum EV_STG_API_CP_SETBY
{
SETBY_NOTSET = 0,
SETBY_SELF = 1,
SETBY_RETCAT = 2
};
The property, ComplianceData SetBy, uses this enumeration value to define
where the compliance retention period is set:

SETBY_NOTSET A compliance retention period is


not set.

SETBY_SELF The compliance retention period


is set by the caller using the
ComplianceData object.

SETBY_RETCAT The compliance retention period


is set by the associated Enterprise
Vault retention category.

“IArchiveMetaData :: ComplianceData” on page 247


“IComplianceData :: SetBy” on page 312
62 Content Management API
Enumerations

EV_STG_API_CP_UNITS enumeration
Compliance units enumeration indicates the units used in specifying the
compliance period:
enum EV_STG_API_CP_UNITS
{
CP_UNITS_DAYS =0,
CP_UNITS_WEEKS = 1,
CP_UNITS_MONTHS = 2,
CP_UNITS_YEARS = 3,
CP_UNITS_DEFAULT = 4,
CP_UNITS_NONE = 5
};
CP_UNITS_NONE is actually the default value, not CP_UNITS_DEFAULT.
See “IComplianceData :: Units” on page 308

EV_STG_API_DELETION_REASON enumeration
Deletion reason enumeration indicates why an item has been deleted from the
archive.
enum EV_STG_API_DELETION_REASON
{
DELETION_REASON_NONE = 0,
DELETION_REASON_USER = 1,
DELETION_REASON_EXPIRY = 2,
DELETION_REASON_SYSTEM = 3
DELETION_REASON_UNKNOWN = 2147483647
}
If an item no longer exists in the archive, the Item DeletionReason property can
be used to find out why the item was deleted. the Item DeletionReason property
uses the EV_STG_API_DELETION_REASON enumeration.
The enumeration values have the following meanings:

DELETION_REASON_NONE (Default) Indicates that the item has not yet been
deleted.

DELETION_REASON_USER Indicates that the item was deleted by a user.

DELETION_REASON_EXPIRY Indicates that the item was deleted by Enterprise Vault


expiry deletion.

DELETION_REASON_SYSTEM Indicates that the item was deleted by the Enterprise


Vault system. This value may be returned, for example,
when the archive has been deleted, or if Enterprise Vault
could not complete the archiving process because the
vault store could not be backed up.
Content Management API 63
Enumerations

DELETION_REASON_UNKNOWN Indicates that the reason why the item was deleted
cannot be identified.

See “IItem2 :: DeletionReason” on page 215

EV_STG_API_EXPIRE_ITEMS enumeration
Expire items enumeration indicates whether expired items should be deleted
automatically from the archive:
enum EV_STG_API_EXPIRE_ITEMS
{
DONT_EXPIRE_ITEMS = 0,
EXPIRE_ITEMS = 1
};
The property Archive ExpireItems can be used to return the enumeration value
for an existing archive, or set the required value for a new archive before
Archive Create is called.
See “IArchive :: ExpireItems” on page 130

EV_STG_API_INDEX_LEVEL enumeration
Index level enumeration indicates how much of an item is indexed:
enum EV_STG_API_INDEX_LEVEL
{
INDEX_LEVEL_BRIEF = 0,
INDEX_LEVEL_MEDIUM = 1,
INDEX_LEVEL_FULL = 2,
INDEX_LEVEL_DEFAULT = 3
};
The Enterprise Vault Indexing service manages the indexes of archived data to
enable users to search for archived items. When users search the archives to
which they have access, the index volume files are searched. The more
information that is indexed about an item, the quicker it is to find the item.
However, the more information that is indexed about an item, the more disk
space is required for the index.
For more information on indexing levels, see “Introduction to storing and
indexing” on page 517.
FULL indexing is required for phrase searches of the content property
(IndexPropCONT).
The property, Archive IndexLevel, is used to determine the level of detail stored
in the archive’s index.
See “IArchive :: IndexLevel” on page 136
64 Content Management API
Enumerations

EV_STG_API_INDEX_URGENCY enumeration
Index urgency enumeration indicates whether to index items as they are stored:
enum EV_STG_API_INDEX_URGENCY
{
INDEX_ITEMS_IMMEDIATELY = 0,
INDEX_ITEMS_DEFER_INDEFINITELY = 1
};
Deferring indexing may be useful if you want to store a very large number of
items quickly.
If INDEX_ITEMS_DEFER_INDEFINITELY is set, the items will not be indexed
until the value has been reset to IMMEDIATELY. Thereafter, the next time the
Indexing Service runs, it will process the indexing backlog.
The Archive IndexUrgency property is used to access index urgency
information.
“IArchive :: IndexUrgency” on page 134

EV_STG_API_ITEM_COPYOPTIONS enumeration
The Item CopyOptions property uses this enumeration to identify the source
item property values that are to be copied to the destination item when an
archived item is moved or copied to a different location.
enum EV_STG_API_ITEM_COPYOPTIONS
{
ITEM_COPYOPTIONS_UNSPECIFIED = 0x00000000,
ITEM_COPYOPTIONS_ARCHIVEMETADATA = 0x00000002,
ITEM_COPYOPTIONS_MERGE_INDEXMETADATA = 0x00000004
} ;
The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA.
■ ITEM_COPYOPTIONS_ARCHIVEMETADATA (Default value)
If this is set, then the values of the the following ArchiveMetaData
properties on the source item will be copied to the equivalent properties on
the destination item, unless explicitly provided as part of the CopyTo or
MoveTo method call:
SimpleIndexMetaData
ArchivedDate
RetentionCategory
CurrentLocation
CurrentFolder
CustomIdentifier
CustomQualifier
CustomProperties
Content Management API 65
Enumerations

■ ITEM_COPYOPTIONS_MERGE_INDEXMETADATA
If this is set, then the resulting destination item will include the custom
index metadata properties on the source item and also any additional
custom index metadata properties that were added to the destination item
before the copy or move operation was performed.
See “IItem :: CopyOptions” on page 192

EV_STG_API_ITEM_DETAIL enumeration
Item detail enumeration indicates the data to populate for an Item.Get request:
enum EV_STG_API_ITEM_DETAIL
{
DETAIL_LEVEL_ITEM_PROPERTIES = 1,
DETAIL_LEVEL_ITEM_CONTENT = 2,
DETAIL_LEVEL_ARCHIVE_METADATA = 4,
DETAIL_LEVEL_COMPLIANCE_DATA = 8,
DETAIL_LEVEL_HOLD_DATA = 16,
DETAIL_LEVEL_CUSTOM_INDEX_METADATA = 32,
DETAIL_LEVEL_SYSTEM_INDEXDATA = 64,
DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA = 128
DETAIL_LEVEL_SENDER_RECIPIENT_INDEXDATA = 256
};
The following table lists the properties that are populated for the different item
detail levels.

Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration


values

Enumeration value Properties populated

DETAIL_LEVEL_ITEM_PROPERTIES IContent.Title
IContent.Author
IContent.FileExtension
IContent.MIMEFormat
IContent.OriginalLocation
IContent.CreatedDate
IContent.ModifiedDate
IContent.OriginalSize
IItem.CanBeDeleted
IArchiveMetadata.IsItemSecured
See “Content object” on page 220
See “Item object” on page 172
See “ArchiveMetaData object” on
page 237

DETAIL_LEVEL_ITEM_CONTENT IContent.Data
66 Content Management API
Enumerations

Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration


values

Enumeration value Properties populated

DETAIL_LEVEL__ARCHIVE_METADATA IArchiveMetadata.ArchivedDate
IArchiveMetadata.SavesetSize
IArchiveMetadata.RetentionCategory
IArchiveMetadata.CustomIdentifier
IArchiveMetadata.CustomQualifier
IArchiveMetadata.CustomProperties
IArchiveMetadata.CurrentFolderId
IArchiveMetadata.SequenceNum

DETAIL_LEVEL__COMPLIANCE_DATA IArchiveMetadata.ComplianceDevice
IArchiveMetadata.RetentionExpires

DETAIL_LEVEL__HOLD_DATA IItem.Holds
See “Holds object” on page 313

DETAIL_LEVEL__CUSTOM_INDEX_METADATA IArchiveMetadata.IndexData — custom


index properties only. (System
properties are not included).
See “System properties” on page 664

DETAIL_LEVEL__SYSTEM_INDEXDATA IArchiveMetadata.IndexData — system


properties only, excluding the “menv”
and “sere” properties.
See “System properties” on page 664

DETAIL_LEVEL__MESSAGE_ENVELOPE_INDEX IArchiveMetadata.IndexData — “menv”


DATA system property only.
See “System properties” on page 664

DETAIL_LEVEL__SENDER_RECIPIENT_INDEXD IArchiveMetadata.IndexData — “sere”


ATA system property only.
See “System properties” on page 664

For details of the Get method, see “IItem :: Get” on page 200.
For details of Enterprise Vault properties, see “System properties” on page 664.

EV_STG_API_PERMISSIONS_TYPE enumeration
Archive permissions enumeration indicates archive permissions:
enum EV_STG_API_PERMISSIONS_TYPE
{
PERMISSIONS_UNSPECIFIED = 0x00000000,
Content Management API 67
Enumerations

PERMISSIONS_SEARCH = 0x00000080,
PERMISSIONS_READ = 0x00000001,
PERMISSIONS_WRITE = 0x00000002,
PERMISSIONS_DELETE = 0x00000004,
PERMISSIONS_FOLDER_READ = 0x00000008,
PERMISSIONS_FOLDER_WRITE = 0x00000010,
PERMISSIONS_FOLDER_DELETE = 0x00000020,
PERMISSIONS_READ_WRITE = PERMISSIONS_READ|PERMISSIONS_WRITE,
PERMISSIONS_READ_WRITE_DELETE= PERMISSIONS_READ
|PERMISSIONS_WRITE
|PERMISSIONS_DELETE,
PERMISSIONS_WRITE_DELETE = PERMISSIONS_WRITE
|PERMISSIONS_DELETE,
PERMISSIONS_READ_DELETE = PERMISSIONS_READ
|PERMISSIONS_DELETE,
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_DELETE,
PERMISSIONS_FOLDER_READ_DELETE = PERMISSIONS_FOLDER_READ
|PERMISSIONS_FOLDER_DELETE,
};
The Archives Permissions property uses this enumeration to select archives
based on the archive access permissions of the caller.
The Archive SecurityDescriptor property represents the manually set
permissions on an archive, which are displayed on the Permissions tab of the
archive properties dialog in the Enterprise Vault Administration Console.
EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security
descriptor permissions for an archive.
See “IArchives :: Permissions” on page 117
See “IArchive3 :: SecurityDescriptor” on page 155

EV_STG_API_STATUS enumeration
Vault store or archive status enumeration indicates the status of the vault store
or archive storage:
enum EV_STG_API_STATUS
{
STS_AVAILABLE = 0,
STS_UNAVAILABLE = 1,
STS_TEMPORARILY_UNAVAILABLE = 2
STS_INBACKUPMODE = 3
};
68 Content Management API
Enumerations

The VaultStore Status and Archive Status properties use this enumeration to
indicate the status of the vault store or archive, and whether it can be accessed.
“IVaultStore :: Status” on page 104
“IArchive2 :: Status” on page 151
Content Management API 69
ContentManagementAPI object

ContentManagementAPI object
This object provides top-level access (via the appropriate interfaces) to archives,
items and holds, and enables you to set and retrieve the Directory DNS Alias and
Authentication mode.
This object implements the following interfaces:
■ IContentManagementAPI
■ IContentManagementAPI2
■ IContentManagementAPI3
■ IContentManagementAPI4 (default)
The IContentManagementAPI interface defines methods and properties
enabling access to archives, vault stores and items. This interface inherits the
methods of the IDispatch interface.
The IContentManagementAPI2 interface provides additional properties for
accessing Enterprise Vault Directory information about vault stores and
archives.
The IContentManagementAPI3 interface provides a property for enumerating
items stored in an archive, and a method to enable applications written in Visual
Basic script to access the IContentManagementAPI3 interface.
The IContentManagementAPI4 interface provides calling applications with
extended error information if an error is encountered when using the Content
Management API methods.

Syntax
interface IContentManagementAPI : IDispatch
interface IContentManagementAPI2 : IContentManagementAPI
interface IContentManagementAPI3 : IContentManagementAPI2
interface IContentManagementAPI4 : IContentManagementAPI3

Member summary

Table 4-3 IContentManagementAPI properties

Property Read/Write Description

Archive Read only Returns an empty instance of an Archive object.

Item Read only Returns an empty instance of an Item object.

Holds Read only Returns an empty instance of a Holds object.


70 Content Management API
ContentManagementAPI object

Table 4-3 IContentManagementAPI properties

Property Read/Write Description

Hold Read only Returns an empty instance of a Hold object.

DirectoryDNSAlias Read/Write Identifies an Enterprise Vault server running an


Enterprise Vault Directory Service.

AuthenticationMode Read/Write Gets or sets the authentication mode.

Table 4-4 IContentManagementAPI2 properties

Property Read/Write Description

VaultStores Read only Returns an empty instance of a VaultStores object.

VaultStore Read only Returns an empty instance of a VaultStore object.

Archives Read only Returns an empty instance of an Archives object.

Table 4-5 IContentManagementAPI3 property

Property Read/Write Description

Items Read only Returns an empty instance of an Items object.

Table 4-6 IContentManagementAPI3 method

Method Read/Write Description

IDispatchQueryInterface Read/Write Returns an interface pointer for either the


IArchiveMetaData3 or IArchive3 interface,
depending on the Interface Indentifier string (IID)
passed to it. This enables applications written in
Visual Basic script to access the
IContentManagementAPI3 interface.
Content Management API 71
ContentManagementAPI object

Table 4-7 IContentManagementAPI4 method

Method Read Description

LastError Read Returns an interface pointer to an


ExtendedErrorInfo object, which provides
extended error information if an error is
encountered when using a Content Management
API method.

Remarks
This interface returns pointers to instances of other interfaces, such as
IVaultStores, IArchives, IItem, IHold, and IHolds. The properties of these need
to be set so that they can then be used to create, fetch, move, enumerate and
delete items, as required.
The interface also enables you to get and set the Directory DNS Alias and the
authentication mode for accessing Enterprise Vault.
For best practice on using IContentManagementAPI, see “General guidelines for
using the API” on page 52.

Requirements
■ MSXML 3.0 or later is required on the computer where you install the
application using the API.

CLSID E4BE20A4-9EF1-4B05-9117-AF43EAB4B295

Prog ID EnterpriseVault.ContentManagementAPI

Type Library EVContentManagementAPILib

DLL EVContentManagementAPI.dll

.NET Primary Interop


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

.NET PIA namespace KVS.EnterpriseVault.Interop

Version information
■ The property, IContentManagementAPI::AuthenticationMode requires
Enterprise Vault 7.0 or later.
72 Content Management API
ContentManagementAPI object

■ 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
}
Content Management API 73
IContentManagementAPI :: Archive

IContentManagementAPI :: Archive
This property returns an empty instance of an Archive object that can then be
used to perform various tasks, such as creating an archive, or modifying various
properties.
This property is read only.

Syntax
HRESULT Archive([out,retval] IArchive** pVal)

Parameters

[out,retval] IArchive** pVal A pointer, when successful, to the location of


the IArchive pointer to the newly created
archive object. This parameter is set to NULL
if an error occurs.

Remarks
After the Create method or Get method has been called, this interface pointer
must be released and a new one obtained before calling either of these methods
again.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Examples
In the following examples it is assumed a reference to IContentManagmentAPI,
m_pCmAPI (C++) or cmAPI (C#) has already been obtained.
See “Examples” on page 72.

C++
IArchive* pArchive = NULL:
m_pCmAPI->get_Archive(&pArchive);

CComBSTR bstrID(L"1C9EFA88998592944ADB634ACC0D7410D1110000EVSite");
74 Content Management API
IContentManagementAPI :: Archive

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;
Content Management API 75
IContentManagementAPI :: Item

IContentManagementAPI :: Item
This property returns an instance of an Item object that can then be used to
perform various tasks, such as creating an item and adding it to an archive,
fetching data, getting item properties, deleting items from an archive, copying
or moving items.
This property is read only.

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.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

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");
76 Content Management API
IContentManagementAPI :: Item

pItem->put_Id(bstrID);
pItem->put_ArchiveId(bstrArchId);

//get item properties


pItem->Get(DETAIL_LEVEL_ITEM_PROPERTIES);

//Do something with the properties

pItem->Release();
pItem = NULL;

C#
IItem itm = cmAPI.Item;

itm.Id = "68bd9b6a-6355-4468-b647-0ec33ade6340";
itm.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";

//get item properties


itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);

System.Runtime.InteropServices.Marshal.FinalReleaseComObject(item);
item = null;

See also
■ IContent
■ IArchiveMetaData
■ ISimpleIndexMetaData
Content Management API 77
IContentManagementAPI :: Holds

IContentManagementAPI :: Holds
This property returns an empty instance of a Holds object that can then be used
to place or release holds on a group of items with a single call to the Enterprise
Vault Server.
It exposes a standard COM interface (IEnumVariant), which manages a
collection of IHold objects.
IHolds is one of the interfaces that provides Legal Hold functionality.
This property is read only.

Syntax
HRESULT Holds([out, retval] IHolds** pVal)

Parameters

[out, retval] IHolds** pVal A pointer, when successful, to the location of the
IHolds pointer to the newly created item object.
This parameter is set to NULL if an error occurs.

Remarks
The IHold objects used to populate the Holds collection must be obtained using
the Hold property of IContentManagementAPI.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Examples

C++
IHolds* pHolds = NULL:
m_pCmAPI->get_Holds(&pHolds);

//Do something

pHolds->Release();
78 Content Management API
IContentManagementAPI :: Holds

pHolds = NULL;

C#
IHolds holds = cmAPI.Holds;
//do something
System.Runtime.InteropServices.FinalReleaseComObject(holds);
holds = null;

See also
■ IHold
Content Management API 79
IContentManagementAPI :: Hold

IContentManagementAPI :: Hold
This property returns an empty instance of a Hold object that can then be used
to place an item on hold. When a hold has been placed on an item, the item
cannot be deleted from the archive until the hold is released.
IHold is one of the interfaces that provides Legal Hold functionality
This property is read only.

Syntax
HRESULT Hold([out, retval] IHold** pVal);

Parameters

[out, retval] IHold** pVal A pointer, when successful, to the location of the
IHold pointer to the newly created item object. This
parameter is set to NULL if an error occurs.

Remarks
The IHold interface is the mechanism by which hold(s) are placed on an item
archived in Enterprise Vault. The interface allows various properties to be set
before the Hold is added to the Holds collection in Enterprise Vault. The Holds
collection is exposed via the IHolds interface.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Examples

C++
IHolds* pHolds = NULL:
m_pCmAPI->get_Holds(&pHolds);
IHold* pHold = NULL;
m_pCmAPI->get_Hold(&pHold);
80 Content Management API
IContentManagementAPI :: Hold

//Set properties

pHolds->Add(pHold);

pHold->Release();
pHold = NULL;
pHolds->Release();
pHolds = NULL;

C#
IHolds holds = cmAPI.Holds;
IHold hold = cmAPI.Hold;

//add some properties

holds.Add(hold);

System.Runtime.InteropServices.FinalReleaseComObject(holds);
holds = null;

System.Runtime.InteropServices.FinalReleaseComObject(hold);
hold = null;

See also
■ IHolds
Content Management API 81
IContentManagementAPI :: DirectoryDNSAlias

IContentManagementAPI :: DirectoryDNSAlias
This property is used to identify a computer running an Enterprise Vault
Directory Service, in order to retrieve information from the Enterprise Vault
Directory.
This property is read/write.

Syntax
HRESULT DirectoryDNSAlias([out, retval] BSTR* pVal);
HRESULT DirectoryDNSAlias([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that, on return, will contain the
current value.

[in] BSTR newVal The new value can be any one of the following:
■ DNS alias of a computer hosting an Enterprise
Vault Directory Service.
■ IP address of a computer hosting an Enterprise
Vault Directory Service.
■ Id of the Enterprise Vault Site.
■ Id of any archive in the Site.
■ Id of any vault store in the Site.

Remarks
The Id of an Enterprise Vault Site can be found in the following registry entry on
an Enterprise Vault server:
HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID
The Id of an archive can be found in the Enterprise Vault Administration
Console, in the properties dialog for an archive.
Similarly, the Id of a vault store can be found in the Administration Console, in
the properties dialog for a vault store.

Return value

S_OK Success.
82 Content Management API
IContentManagementAPI :: DirectoryDNSAlias

Examples

C++
CComBSTR bstrDNS(L"EVSERVER1");
m_pCmAPI->get_DirectoryDNSAlias(&bstrDNS);
//Do something

C#
[out]

string dns = cmAPI.DirectoryDNSAlias;

[in]

cmAPI.DirectoryDNSAlias = dns;
Content Management API 83
IContentManagementAPI :: AuthenticationMode

IContentManagementAPI :: AuthenticationMode
This property is used to get or set the mode to be used when authenticating to
Enterprise Vault. This can be either DCOM or Enterprise Vault authentication
server.
The property is read/write.

Syntax
HRESULT AuthenticationMode([out, retval]
EV_STG_API_AUTHENTICATE_USING* pVal)
HRESULT AuthenticationMode([in]
EV_STG_API_AUTHENTICATE_USING newVal)

Parameters

[out, retval]EV_STG_API_AUTHENTICATE_USING* pVal Pointer to an EV_STG_API_


AUTHENTICATE_USING
object which will return the
current authentication
mode.

[in]EV_STG_API_AUTHENTICATE_USING newVal New value for the


authentication mode.

Remarks
EV_STG_API_AUTHENTICATE_USING enumerator defines the authentication
mode to use.
See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 60.
In releases prior to Enterprise Vault 7.0, authentication was performed using
DCOM when the API application was not installed on an Enterprise Vault server,
otherwise Enterprise Vault authentication server was used. From Enterprise
Vault 7.0, DCOM authentication is used by default.
From Enterprise Vault 8.0 SP2,
AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default
enumeration value. This value means that DCOM will be used.
Authentication using the Enterprise Vault authentication server can only be
used by applications installed on a configured Enterprise Vault server, and
should only be used on advice from Symantec Support.
84 Content Management API
IContentManagementAPI :: AuthenticationMode

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Examples

C++
m_pCmAPI->put_AuthenticationMode(AUTHENTICATE_USING_DCOM_SECURITY);

C#
cmAPI.AuthenticationMode =
EV_STG_API_AUTHENTICATE_USING.AUTHENTICATE_USING_DCOM_SECURITY;
Content Management API 85
IContentManagementAPI2 :: VaultStores

IContentManagementAPI2 :: VaultStores
This property returns an empty instance of the VaultStores object, which
enables applications to enumerate details of the vault stores configured in
Enterprise Vault.

Syntax
HRESULT VaultStores([out, retval] IUnknown** pVal);

Parameters

[out, retval] IUnknown** pVal Reference to an empty VaultStores object.

Remarks
When successful, a pointer to an IUnknown* that can be QI'd (cast) for an
IVaultStores interface pointer.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Examples

C++
IVaultStores pVaultStores = NULL;
m_pCmAPI->get_VaultStores(&pVaultStores);
CComBSTR bstrComputer(L"EVSERVER1");
pVaultStores->put_Computer(bstrComputer);
pVaultStores->Get();

C#
IVaultStores vaultStores = cmAPI.VaultStores;
vaultStores.Computer = "EVSERVER1";
vaultStores.Get();
86 Content Management API
IContentManagementAPI2 :: VaultStores

See also
■ “VaultStores object” on page 94.
Content Management API 87
IContentManagementAPI2 :: VaultStore

IContentManagementAPI2 :: VaultStore
This property returns an empty instance of the VaultStore object, which can be
used to read the details of a vault store.
This property is read only.

Syntax
HRESULT VaultStore([out, retval] IUnknown** pVal);

Parameters

[out, retval] IUnknown** pVal Reference to an empty VaultStore object.

Remarks
To populate the Vault Store object, set the Id property to that of the vault store
then call Get.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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;
88 Content Management API
IContentManagementAPI2 :: VaultStore

vaultStore.ID = "16D002240AEDFAC45A44E7FBE88FDC7721210000
EVSite";
vaultStore.Get();

See also
■ “VaultStore object” on page 98.
Content Management API 89
IContentManagementAPI2 :: Archives

IContentManagementAPI2 :: Archives
This property returns an instance of the Archives collection object, which
enables applications to enumerate archives configured in the current vault
store.

Syntax
HRESULT Archives([out, retval] IUnknown** pVal);

Parameters

[out, retval] IUnknown** pVal An instance of an Archives object.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

EXAMPLES

C++
CComPtr<IArchives> spArchives;
CComPtr<IUnknown> spUnk;
m_pCmAPI->get_Archives(&spUnk);
spUnk->QueryInterface(&spArchives);
CComBSTR
bstrVaultStore(L"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite");
spArchives->put_VaultStore(bstrVaultStore);
spArchives->put_ArchiveTypes(ARCHIVE_TYPE_EXCHANGE_MAILBOX);

See also
■ “Archives object” on page 109.
90 Content Management API
IContentManagementAPI3 :: Items

IContentManagementAPI3 :: Items
This property returns an empty instance of the Items object, which is populated
by calling IItems::Get. Applications can then enumerate the items in the archive.

Syntax
HRESULT Items([out, retval] IUnknown** pVal);

Parameters

[out, retval] IUnknown** pVal Reference to an empty Items object.

Remarks
An IItems interface pointer can be obtained by calling QueryInterface on the
returned IUnknown* pointer.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Example

C++
// Get empty items collection for populating
CComPtr<IContentManagementAPI3> spCMAPI;
spCMAPI.CreateInstance(CComBSTR(L"EnterpriseVault.ContentManagement
API"));
CComPtr<IUnknown> spUnk;

// Get an Items object for enumeration


spCMapi->get_Items(&spUnk);

CComQIPtr<IItems> spItems(spUnk);

See also
■ “Items object” on page 162.
Content Management API 91
IContentManagementAPI3 :: IDispatchQueryInterface

IContentManagementAPI3 ::
IDispatchQueryInterface
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.

Return value

S_OK Success
92 Content Management API
IContentManagementAPI3 :: IDispatchQueryInterface

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either of pUnkObj or ppUnkRetVal


are NULL, or interfaceId is empty,
is not a valid interface ID (IID), or
the interface is not available on the
object being queried.

Example
The following Visual Basic Script example illustrates how to use this method to
query for an IArchiveMetaData2 interface (with the IID string
“{5C6882BD-24BE-4C32-87EF-C3701D949BAA}” ) from an IArchiveMetaData
object interface, in order to access the IArchiveMetaData2::SequenceNum
property.

dim cmAPI, item, SeqNo, IAMD2


set cmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")
set item = ContentManagementAPI.Item
set IAMD2 = cmAPI.IDispatchQueryInterface(item.ArchiveMetaData,
"{5C6882BD-24BE-4C32-87EF-C3701D949BAA}")
if (IAMD2 is nothing) then
MsgBox "ArchiveMetaData2 API Object create failed!"
end if

SeqNo = IAMD2.SequenceNum

See also
■ “Archive object” on page 120
■ “ArchiveMetaData object” on page 237
Content Management API 93
IContentManagementAPI4 :: LastError

IContentManagementAPI4 :: LastError
This method provides calling applications with extended error information if an
error is encountered when using the Content Management API methods.

Syntax
HRESULT LastError([out,retval] IUnknown** pVal);

Parameters

[out,retval] IUnknown** pVal A reference to an ExtendedErrorInfo


object.

Remarks
The ExtendedErrorInfo object provides error details for the last call to a Content
Management API method.
It is important to follow recommended best practice, and avoid sharing
IContentManagementAPI interface objects across threads, as this could cause
error information from a call on another thread to be returned.
See “Programming notes” on page 46.

Return value

S_OK Success

See also
■ “ExtendedErrorInfo object” on page 355
94 Content Management API
VaultStores object

VaultStores object
This object implements the following interface:
■ IVaultStores
The IVaultStores interface inherits the properties and methods of the
ICollectionBase interface.
The IVaultStores interface enables applications to enumerate the vault stores
configured in an Enterprise Vault Site.

Syntax
interface IVaultStores : ICollectionBase

Member summary

Table 4-8 IVaultstores properties

Property Read/Write Description

Computer Read/Write Identity of an Enterprise Vault server running a


Directory Service.

Table 4-9 and Table 4-10 list the properties and methods of the ICollectionBase
interface. For more detail see “ICollectionBase : IDispatch” on page 344.

Table 4-9 ICollectionBase properties

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.
Content Management API 95
VaultStores object

Table 4-10 ICollectionBase methods

Method Description

Get Populate the collection.

Clear Clear the current collection.

Reset Reset the object back to the initial state.

Remarks
Use the ICollectionBase :: Get method of this interface to obtain a collection of
VaultStore objects, and automatically populate the properties of each
VaultStore object .
See “VaultStore object” on page 98.

Version information
■ This interface is available from Enterprise Vault 2007.

Example

C#
This example code lists all vault stores based on a Computer DNS name.
IContentManagementAPI3 cmAPI = (IContentMangementAPI3)
new ContentManagementAPI();
IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores;
// Populate collection from EV1
vaultStores.Computer = “EV1.Acme.com”;
vaultStores.Get();
// Process each Vault Store
foreach(IVaultStore vaultStore in vaultStores)
{
ProcessIt(vaultStore.Id, vaultStore.Name);
}
96 Content Management API
IVaultStores :: Computer

IVaultStores :: Computer
This property identifies an Enterprise Vault server running a Directory Service.
The property is read/write.

Syntax
HRESULT Computer([in] BSTR pVal);
HRESULT Computer([out, retval] BSTR* pVal);

Parameters

[in] BSTR pVal The DNS name of an Enterprise Vault server, or the Id of
an Enterprise Vault entity, such as site or vault store.

[out, retval] BSTR* pVal A pointer to a string that will hold the returned value.

Remarks
This property can be set with any identifier that Enterprise Vault can use to
identify an Enterprise Vault server running a Directory Service, for example:
■ DNS name
■ IP address
■ The Id of an Enterprise Vault entity, for example:
■ Enterprise Vault Site Id
■ Vault store Id
■ Archive Id
The Id of an Enterprise Vault Site can be found in the following registry entry on
an Enterprise Vault server:
HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID
The Id of an archive can be found in the Enterprise Vault Administration
Console, in the properties dialog for an archive.
Similarly, the Id of a vault store can be found in the Administration Console, in
the properties dialog for a vault store.
If the Computer property is left empty than its value defaults to the current
value of the DirectoryDNSAlias property of the parent IContentManagementAPI
instance.
Content Management API 97
IVaultStores :: Computer

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Example

C#
IContentManagementAPI3 cmAPI = (IContentMangementAPI3)
new ContentManagementAPI();
IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores;
// Populate collection from EV1
vaultStores.Computer = “EV1.Acme.com”;
vaultStores.Get();
// Process each Vault Store
foreach(IVaultStore vaultStore in vaultStores)
{
ProcessIt(vaultStore.Id, vaultStore.Name);
}
98 Content Management API
VaultStore object

VaultStore object
This object implements the following interface:
■ 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 Identifies an Enterprise Vault server


running an Enterprise Vault Directory
Service.

Table 4-12 IVaultStore methods

Method Description

Get Get the details of the selected vault store.

Remarks
If you use the ICollectionBase interface to enumerate vault stores (see
“VaultStores object” on page 94), then the IVaultStore properties are populated
automatically for each vault store returned.
Alternatively, if you select a specific vault store using the Id property, you can
call the Get method to populate the VaultStore properties.
Content Management API 99
VaultStore object

Version information
■ This interface is available from Enterprise Vault 2007.

Example

C#
IVaultStore vaultStore = cmAPI.VaultStore;
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;
100 Content Management API
IVaultStore :: Id

IVaultStore :: Id
This property contains the Id of the target vault store.
The property is read/write.

Syntax
HRESULT Id([out, retval] BSTR* pVal);
HRESULT Id([in] BSTR newVal);

Parameters

[in] BSTR pVal Id of the required vault store.

[out, retval] BSTR* pVal String that will contain the Id of the vault store.

Remarks
The Id of a vault store can be found in the Administration Console, in the
properties dialog for a vault store.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, pVal


is not a valid Vault
Store identity, or
the object is
already populated.

Example

C#
IVaultStore vaultStore = cmAPI.VaultStore;
vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
vaultStore.Get();

//now get vault store properties


string name = vaultStore.Name;
string description = vaultsStore.Description;
string dnsAlias = vaultStore.DirectoryDNSAlias;
Content Management API 101
IVaultStore :: Id

EV_STG_API_STATUS evStatus = vaultStore.Status;


long count = vaultStore.ArchiveCount;
102 Content Management API
IVaultStore :: Name

IVaultStore :: Name
This property contains the name of the selected vault store.
The property is read only.

Syntax
HRESULT Name([out, retval] BSTR* pVal);

Parameter

[out, retval] BSTR* pVal Name of the vault store.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example

C#
IVaultStore vaultStore = cmAPI.VaultStore;
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;
Content Management API 103
IVaultStore :: Description

IVaultStore :: Description
This property contains the vault store description.
The property is read only.

Syntax
HRESULT Description([out, retval] BSTR* pVal);

Parameter

[out, retval] BSTR* pVal Vault store description.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example

C#
IVaultStore vaultStore = cmAPI.VaultStore;
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.Count;
104 Content Management API
IVaultStore :: Status

IVaultStore :: Status
This property contains the status of the vault store.
The property is read only.

Syntax
HRESULT Status([out, retval] EV_STG_API_STATUS* pVal);

Parameter

[out, retval] EV_STG_API_STATUS* pVal EV_STG_API_STATUS enumerated


value.

Remarks
EV_STG_API_STATUS is an enumerated type. See “EV_STG_API_STATUS
enumeration” on page 67.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example

C#
IVaultStore vaultStore = cmAPI.VaultStore;
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;
Content Management API 105
IVaultStore :: ArchiveCount

IVaultStore :: ArchiveCount
This property contains the number of archives in the vault store.
The property is read only.

Syntax
HRESULT ArchiveCount([out, retval] long* pVal);

Parameter

[out, retval] long* pVal Number of archives currently in the vault store.

Remarks
This property is populated using an additional call to the Enterprise Vault
server. For this reason, it is only populated when explicitly requested.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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#
IVaultStore vaultStore = cmAPI.VaultStore;
vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
vaultStore.Get();
//now get vault store properties
string name = vaultStore.Name;
string description = vaultsStore.Description;
106 Content Management API
IVaultStore :: ArchiveCount

string dnsAlias = vaultStore.DirectoryDNSAlias;


EV_STG_API_STATUS evStatus = vaultStore.Status;
long count = vaultStore.ArchiveCount;
Content Management API 107
IVaultStore :: DirectoryDNSAlias

IVaultStore :: DirectoryDNSAlias
This property contains the DNS Alias created for the Enterprise Vault Site.
The property is read only.

Syntax
HRESULT DirectoryDNSAlias([out, retval] BSTR* pVal);

Parameter

[out, retval] BSTR* pVal DNS alias for the Enterprise Vault Site.

Remarks
When configuring Enterprise Vault, a DNS alias is assigned to the IP address of
the computer that hosts the primary Enterprise Vault Directory Service for the
Enterprise Vault Site.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example

C#
IVaultStore vaultStore = cmAPI.VaultStore;
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;
108 Content Management API
IVaultStore :: Get

IVaultStore :: Get
This method returns the properties for the selected vault store.

Syntax
HRESULT Get(void);

Remarks
If you do not enumerate vault stores using the IVaultStores interface, then you
can set the Id property of the IVaultStore interface and call Get to populate the
IVaultStore properties.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The vault store does not exist.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory


service is not running.

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#
IVaultStore vaultStore = cmAPI.VaultStore;
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;
Content Management API 109
Archives object

Archives object
This object implements the following interface:
■ IArchives
The IArchives interface inherits the properties and methods of the
ICollectionBase interface.
This interface enables applications to enumerate archives optionally filtered by
archive name, type, permissions or vault store.

Syntax
interface IArchives : ICollectionBase

Member summary

Table 4-13 IArchives properties

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 required


archive or archives.

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


archive or archives.

ArchiveTypes Read/Write Types of archives required.

Table 4-14 and Table 4-15 list the properties and methods of the ICollectionBase
interface. For more detail see “ICollectionBase : IDispatch” on page 344.

Table 4-14 ICollectionBase properties

Property Read/Write Description

Count Read only Number of archives in the collection.

_NewEnum Read only Instance of the standard COM enumerator for


the collection.
110 Content Management API
Archives object

Table 4-14 ICollectionBase properties

Property Read/Write Description

Item Read only Instance of the archive at the zero-based index


into the collection.

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

More Read only Indicates whether there are more archives


available than the maximum allowed in the
collection.

Table 4-15 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
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.
Content Management API 111
Archives object

No other combinations of properties are supported.

Version information
■ This interface requires Enterprise Vault 2007 or later.

Example

C#
IArchives archives = (IArchives)cmAPI.Archives;

See also
■ “Enumerating vault stores, archives and items” on page 53.
■ “ICollectionBase : IDispatch” on page 344.
■ “Archive object” on page 120.
112 Content Management API
IArchives :: Computer

IArchives :: Computer
This property identifies an Enterprise Vault server running a Directory Service.
The property is read/write.

Syntax
HRESULT Computer([in] BSTR pVal);
HRESULT Computer([out, retval] BSTR* pVal);

Parameters

[in] BSTR pVal The DNS name of an Enterprise Vault server, or the Id of
an Enterprise Vault entity, such as site or vault store.

[out, retval] BSTR* pVal A pointer to a string that will hold the returned value.

Remarks
This property can be set with any identifier that Enterprise Vault can use to
identify an Enterprise Vault server running a Directory Service, for example:
■ DNS name
■ IP address
■ The Id of an Enterprise Vault entity in the Directory, for example:
■ Enterprise Vault Site Id
■ Vault store Id
■ Archive Id
The Id of an Enterprise Vault Site can be found in the following registry entry on
an Enterprise Vault server:
HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID
The Id of an archive can be found in the Enterprise Vault Administration
Console, in the properties dialog for an archive.
Similarly, the Id of a vault store can be found in the Administration Console, in
the properties dialog for a vault store.
If the Computer property is left empty than its value defaults to the current
value of the DirectoryDNSAlias property of the parent IContentManagementAPI
instance.
Content Management API 113
IArchives :: Computer

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example

C#
This example gets all the archives that the user has permission to search.
IArchives archives = (IArchives)cmAPI.Archives;
archives.Computer = "EV1.acme.com";

archives.Permissions =
EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;
archives.Get();
114 Content Management API
IArchives :: VaultStoreId

IArchives :: VaultStoreId
This property contains the Id of the vault store that contains the required
archive or archives.
The property is read/write.

Syntax
HRESULT VaultStoreId([in] BSTR pVal);
HRESULT VaultStoreId([out, retval] BSTR* pVal);

Parameters

[in] BSTR pVal Id of the required vault store.

[out, retval] BSTR* pVal String that will contain the Id of the vault store.

Remarks
The Id of a vault store can be found in the Administration Console, in the
properties dialog for a vault store, or by enumerating vault stores using the
VaultStores object.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or pVal is not a valid


vault store identity.

Example
This example gets all Exchange Server mailbox archives in a particular vault
store.

C#
IArchives archs = (IArchives)cmAPI.Archives;
archs.VaulStoreId =
"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";
archs.ArchiveTypes =
EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX;
archs.Get();
Content Management API 115
IArchives :: ArchiveName

IArchives :: ArchiveName
This property enables archives to be selected by name or partial name.
The property is read/write.

Syntax
HRESULT ArchiveName([in] BSTR pVal);
HRESULT ArchiveName([out, retval] BSTR* pVal);

Parameters

[in] BSTR pVal Name or partial name of required archive or archives.

[out, retval] BSTR* pVal Pointer to a string that will contain the archive names.

Remarks
Multiple archives can be selected by use of common wildcard syntax. The
following wildcard features are supported:
■ * to match none, one or any number of characters.
■ % to match any single character.
■ [] matches any single character within the specified range or set (case
insensitive). For example
■ [abdf] to match any of the set of characters a,b,d, or f.
■ [a-f] to match any of the range of characters a,b,c,d,e, or f.
■ [^] to match any single character not in the specified range or set (case
insensitive). For example
■ [^abdf] to match any character not in the set of characters a, b,d, or f.
■ [^a-f] to match any character not in the range of characters a,b,c,d,e, or
f.
■ \ escapes *, %, or [ to enable matching on those characters. For example,
50\% is used to match with 50%.
The returned collection is ordered by archive name.
116 Content Management API
IArchives :: ArchiveName

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .

Example
This example retrieves all archives with a name ending in ‘Smith’.

C#
IArchives archs = cmAPI.Archives;
archs.Computer = “SERVER1”;
archs.ArchiveName = “*Smith”;
archs.Get();
Content Management API 117
IArchives :: Permissions

IArchives :: Permissions
This property enables selection of archives based on the archive access
permissions of the caller.
The property is read/write.

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

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .

Example

C#
IArchives archives = (IArchives)cmAPI.Archives;
archives.Computer = "EV1.acme.com";
118 Content Management API
IArchives :: Permissions

archives.Permissions =
EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;
archives.Get();
Content Management API 119
IArchives :: ArchiveTypes

IArchives :: ArchiveTypes
This property enables the selection of archives based on the type of archive. For
example, Exchange Server mailbox archive, FSA archive, SharePoint archive,
and so on.
The property is read/write.

Syntax
HRESULT ArchiveTypes([in] LONG pVal));
HRESULT ArchiveTypes([out, retval] LONG* pVal);

Parameters

[in] LONG pVal One or more values of EV_STG_API_ARCHIVE_TYPE.

[out, retval] LONG* pVal One or more values of EV_STG_API_ARCHIVE_TYPE.

Remarks
EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.
See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .

Example

C#
IArchives archives = (IArchives)cmAPI.Archives;
archives.ArchiveTypes =
(int)EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX;
archives.Permissions =
(int)EV_STG_API_PERMISSIONS_TYPE.PERMISSION_SEARCH;
archives.Get();
120 Content Management API
Archive object

Archive object
This object implements the following interfaces:
■ IArchive
IID is {48092C71-5618-4EB5-9060-01030C191450}
■ IArchive2
IID is {B85C5178-0B9D-4987-8DC5-92F77B33879E}
■ IArchive3
IID is {9E2C0ACF-4CB5-4FB3-A9AB-499BB9EE959C}
These interfaces enable the creation and examination of archives in a vault
store.
IArchive2 provides additional properties to enable querying the type and status
of an archive.
IArchive3 provides additional properties to enable setting and querying the
access security assigned to an archive.

Syntax
interface IArchive : IDispatch
interface IArchive2 : IArchive
interface IArchive3 : IArchive2

Member summary

Table 4-16 IArchive properties

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.
Content Management API 121
Archive object

Table 4-16 IArchive properties

Property Read/Write Description

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.

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.
122 Content Management API
Archive object

Table 4-18 IArchive3 properties

Property Read/Write Description

SecurityDescriptorString Read/Write The security permissions on the archive


specified using Security Descriptor String
Format as described in MSDN.

Type Read/Write The type of the archive.

Table 4-19 IArchive methods

Method Description

Create Creates an archive.

Get Retrieves details of the selected archive.

Remarks
After the Create method or Get method has been called on this interface, the
reference must be released and a new one obtained before calling either of these
methods again.

Version information
■ IArchive2 interface requires Enterprise Vault 2007 or later.
■ IArchive3 interface requires Enterprise Vault 8.0 or later.

Example

C#
IArchive arch = cmAPI.Archive

arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();
Content Management API 123
IArchive :: VaultStoreId

IArchive :: VaultStoreId
This property identifies the vault store in which the archive resides or will
reside.
The property is read/write.

Syntax
HRESULT VaultStoreId([in] BSTR newVal)
HRESULT VaultStoreId([out,retval] BSTR* pVal)

Parameters

[in] BSTR newVal Id of the required vault store.

[out,retval] BSTR* pVal Pointer to a BSTR that contains the Id of the


required vault store

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Incorrect Id format.

Example
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();
124 Content Management API
IArchive :: Id

IArchive :: Id
This property contains the Archive Id of the archive.
This property is read/write.

Syntax
HRESULT Id([out, retval] BSTR* pVal);
HRESULT Id([in] BSTR newVal);

Parameters

[in] BSTR newVal The Archive Id of the archive.


This value is displayed in the properties of
the archive in the Administration Console.
Maximum length of string: 112 characters.

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the
current value.

Remarks
This value must be set prior to calling Get.
If an attempt to change this value on an existing archive is made then an error
will occur.
The following is an example value of the Id property:
“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, pVal is not a valid


archive identity, or the object is
already populated.
Content Management API 125
IArchive :: Id

Examples
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();

or
[out]
Assume an Archives object, 'archives', has been populated.
foreach (IArchive archive in archives)
{
SearchArchive(archive.Id);
}
126 Content Management API
IArchive :: Name

IArchive :: Name
This property is used to set the name for a new archive or retrieve the name of
an existing archive.
The property is read/write.

Syntax
HRESULT Name([in] BSTR newVal)
HRESULT Name([out,retval] BSTR* pVal)

Parameters

[in] BSTR newVal The name of the archive.


Maximum length: 256 characters.

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the name of an archive.

Remarks
This property must be set before creating an archive, but is not required to get
an archive.
Any attempt to change the name of an existing archive will result in an error.
The value must contain printable characters only, and cannot be blank or an
empty string.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal contains


invalid characters, or the object is
already populated.

Example
[in]
arch.Name = “my new archive”;
arch.Description = “my new archive description”;
arch.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS;
Content Management API 127
IArchive :: Name

arch.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.
CONVERTED_CONTENT_STORED;
arch.IndexUrgency = EV_STG_API_INDEX_URGENCY.
INDEX_ITEMS_IMMEDIATELY;
arch.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;
arch.Create();

[out]
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
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;
128 Content Management API
IArchive :: Description

IArchive :: Description
This property contains a more complete description of the archive.
The property is read/write.

Syntax
HRESULT Description([in] BSTR newVal)
HRESULT Description([out,retval] BSTR* pVal)

Parameters

[in] BSTR newVal Description of the archive.


Max length: 127 characters.

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the


description of the archive.

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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal contains


invalid characters, or the object is
already populated.

Examples

C++
CComBstr bstr = new CComBSTR(L”archive description”);
archive->put_Description(bstr):
Content Management API 129
IArchive :: Description

//do something – create archive


//then check name

archive->get_ Description (&bstr);

//try changing name


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

C#

archive. Description = “archive description”;

//do something – create archive


//then check name

string name = archive. Description;

//try changing name


archive. Description = “New description”; //ERROR
130 Content Management API
IArchive :: ExpireItems

IArchive :: ExpireItems
This property specifies whether or not items should be automatically deleted
(expired) from the archive.
The property is read/write.

Syntax
HRESULT ExpireItems([out, retval] EV_STG_API_EXPIRE_ITEMS* pVal);
HRESULT ExpireItems([in] EV_STG_API_EXPIRE_ITEMS newVal);

Parameters

[out, retval] EV_STG_API_EXPIRE_ITEMS* pVal Pointer to an


EV_STG_API_EXPIRE_ITEMS
object that will contain the current
value.

[in] EV_STG_API_EXPIRE_ITEMS newVal Sets a new value of ExpireItems.

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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or


the object is already populated.
Content Management API 131
IArchive :: ExpireItems

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;

//do other things and create archive


//Now check value

ei = archive.ExpireItems;

//try changing value

archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;
//ERROR
132 Content Management API
IArchive :: ConvertedContent

IArchive :: ConvertedContent
This property specifies whether converted content is stored in the item or
generated on demand.
The property is read/write.

Syntax
HRESULT ConvertedContent([out, retval]
EV_STG_API_CONVERTED_CONTENT* pVal);
HRESULT ConvertedContent([in] EV_STG_API_CONVERTED_CONTENT newVal);

Parameters

[out, retval]EV_STG_API_CONVERTED_CONTENT* pVal Pointer to an


EV_STG_API_CONVERTE
D_CONTENT object that
will contain the current
value.

[in] EV_STG_API_CONVERTED_CONTENT newVal The new value of


ConvertedContent.

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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or the


object is already populated.
Content Management API 133
IArchive :: ConvertedContent

Examples

C++
EV_STG_API_CONVERTED_CONTENT cc = CONVERTED_CONTENT_STORED;

archive->put_ConvertedContent(cc);

//do other things and create archive


//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
134 Content Management API
IArchive :: IndexUrgency

IArchive :: IndexUrgency
This property specifies when items are indexed.
The property is read/write.

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 64.
Deferring indexing may be useful if you want to store a very large number of
items quickly.
INDEX_ITEMS_DEFER_INDEFINITELY was originally introduced to be used
with File System Archiving only. If this value is set, the items will not be indexed
until the value has been reset to IMMEDIATELY, and the next time the Indexing
Service runs it will process the index backlog.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or


the object is already populated.
Content Management API 135
IArchive :: IndexUrgency

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

//try and change value

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 ;

//try and change the value

archive. IndexUrgency =
EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_DEFER_INDEFINITELY; //ERROR
136 Content Management API
IArchive :: IndexLevel

IArchive :: IndexLevel
This property determines the level of detail stored in the archive’s index.
The property is read/write.

Syntax
HRESULT IndexLevel([out, retval] EV_STG_API_INDEX_LEVEL* pVal);
HRESULT IndexLevel([in] EV_STG_API_INDEX_LEVEL newVal);

Parameters

[out, retval] EV_STG_API_INDEX_LEVEL* pVal Pointer to an


EV_STG_API_INDEX_LEVEL
object that will contain the
current value.

[in] EV_STG_API_INDEX_LEVEL newVal New value of


EV_STG_API_INDEX_LEVEL.

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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or


the object is already populated.
Content Management API 137
IArchive :: IndexLevel

Examples

C++
EV_STG_API_INDEX_LEVEL il = INDEX_LEVEL_MEDIUM;
EV_STG_API_INDEX_LEVEL il = INDEX_LEVEL_BRIEF;

archive->put_IndexLevel(il);

//do something and create archive


//Now check value

archive->get_ IndexLevel (&il);

//try and change value

archive->put_ IndexLevel (INDEX_LEVEL_FULL); //ERROR

C#
EV_STG_API_INDEX_URGENCY il =
EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_MEDIUM;
EV_STG_API_INDEX_URGENCY il =
EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_BRIEF;

archive. IndexLevel = il;

//do something – create archive


//check value

il = Archive. IndexLevel;

//try and change the value

archive. IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;


//ERROR
138 Content Management API
IArchive :: Size

IArchive :: Size
This property contains the size of the archive.
The property is read only.

Syntax
HRESULT Size([out, retval] VARIANT* pVal);

Parameters

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain


the size of the archive, expressed in
Kbytes. The VT type is a VT_U18.

Remarks
Property will only contain a value once an archive has been created.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, or the object has not


been populated.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running

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
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();

string name = arch.Name;


Content Management API 139
IArchive :: Size

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;
140 Content Management API
IArchive :: SecurityDescriptor

IArchive :: SecurityDescriptor
This property contains the self-relative security descriptor to be used when
creating an archive.
The property is write only.
(A read/write version of the property is available on the IArchive3 interface).

Syntax
HRESULT SecurityDescriptor([in] VARIANT newVal);

Parameters

[in] VARIANT newVal New value of the security descriptor.

Remarks
Any attempt to modify the security descriptor of an existing archive will result
in an error.
The self-relative security descriptor may override the current user.
If the type of the variant is VT_ARRAY then the variant is a byte array
containing the SECURITY_DESCRIPTOR for the user account that will be given
access to the archive.
If the type of the variant is VT_EMPTY then the security descriptor is set to
default (that is, the user creating the archive has full access to the archive).
Finally a type of VT_NULL means that the archive is created without any
permissions.
EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security
descriptor permissions for an archive.
See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.
The values of the EV_STG_API_PERMISSIONS_TYPE enumerator may be
combined (using OR) to set the required value. For example, to set search and
read item, you would enter PERMISSIONS_SEARCH|PERMISSIONS_READ.

Version information
At Enterprise Vault 8.0, this property is superceded by the
IArchive3::SecurityDescriptor property.
See “IArchive3 :: SecurityDescriptor” on page 155.
Content Management API 141
IArchive :: SecurityDescriptor

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER newVal is invalid, or the object is


already populated.

Example

Creating a Security Descriptor


char aszPrompt[MAX_INPUT_BUFFER];
wcout << L"Domain\\Account: " << flush;
cin.getline(aszPrompt, MAX_INPUT);

// Create Security Identifier from Domain and Account


CSid Sid;
if (!Sid.LoadAccount(aszPrompt))
{
return HRESULT_FROM_WIN32(GetLastError());
}

// Create ACE (access-control entry)


CDacl Dacl;
if (!Dacl.AddAllowedAce(Sid, PERMISSIONS_READ_WRITE_DELETE))
{
return HRESULT_FROM_WIN32(GetLastError());
}

// Set information in a DACL (discretionary access-control list)


CSecurityDesc SecurityDesc;
SecurityDesc.SetDacl(Dacl);

// Convert security descriptor to self-relative format


SecurityDesc.MakeSelfRelative();

// Copy security descriptor to a byte array


UINT SecurityDescLength = SecurityDesc.GetLength();
const SECURITY_DESCRIPTOR *pSecurityDesc =
SecurityDesc.GetPSECURITY_DESCRIPTOR();
CComSafeArray<BYTE> SecurityDescSafeArrayOfBytes;
hr = SecurityDescSafeArrayOfBytes.Add(SecurityDescLength,
(BYTE*)pSecurityDesc);

VARTYPE vt = SecurityDescSafeArrayOfBytes.GetType();
vt = vt | VT_ARRAY;
SecurityDescriptor->vt = vt;
SecurityDescriptor->parray = SecurityDescSafeArrayOfBytes.Detach();
142 Content Management API
IArchive :: ComplianceDevice

IArchive :: ComplianceDevice
This property tells the caller whether the archive resides on a device capable of
setting compliance periods.
The property is read only.

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.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, or the object has not


been populated.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

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
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();
Content Management API 143
IArchive :: ComplianceDevice

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;
144 Content Management API
IArchive :: ItemCount

IArchive :: ItemCount
This property tells the caller how many items are currently held in the archive.
The property is read only.

Syntax
HRESULT ItemCount([out,retval] VARIANT* pVal)

Parameters

[out,retval] VARIANT* pVal Pointer to a VARIANT that will contain the


current number of items in the archive.

Remarks
This property can only be used after Get or Create have been called.
The type of the variant will be unsigned long, for example, vt= VT_UI4.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, or the object has not


been populated.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

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
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch.Get();

string name = arch.Name;


Content Management API 145
IArchive :: ItemCount

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;
146 Content Management API
IArchive :: Create

IArchive :: Create
This method is used to create an archive.

Syntax
HRESULT Create(void)

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

Return value

S_OK Success.
Content Management API 147
IArchive :: Create

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One or more of the mandatory


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are 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.

CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller not in a role that includes the


operation, ‘{DIR} Can manage
Enterprise Vault Stores’. (The default
Enterprise Vault Storage
Administrator and Power
Administrator roles include this
operation).

Example

C++
archiveName = L”XYZRM_”;
archiveName += username;
archive->put_Name(archiveName);
archive->put_Description(CComBSTR(L“XYZ RM application archive”));
archive->put_VaultStoreId(CComBSTR(L“181E669473B52E64384C9A7D9EACA0
E7E1210000evsite”));
archive->put_ExpireItems(EXPIRE_ITEMS);
archive->put_IndexLevel(INDEX_LEVEL_FULL);
archive->put_ConvertedContent(CONVERTED_CONTENT_STORED);
archive->put_IndexUrgency(INDEX_ITEMS_IMMEDIATELY);
archive->Create();
archive->get_Id(&archiveId); // Remember the assigned Id for future
insertions

C#
archive.Name = ”XYZRM_” + userName;
archive.Description = “XYZ RM application archive”;
archive.VaultStoreId =
“181E669473B52E64384C9A7D9EACA0E7E1210000evsite”;
archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;
archive.IndexLevel = EV_STG_API_INDEX_LEVEL.INDEX_LEVEL_FULL;
148 Content Management API
IArchive :: Create

archive.ConvertedContent =
EV_STG_API_CONVERTED_CONTENT.CONVERTED_CONTENT_STORED;
archive.IndexUrgency
=EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_IMMEDIATELY;
archive.Create();
archiveId = archive.Id; // Remember the assigned Id for future
insertions
Content Management API 149
IArchive :: Get

IArchive :: Get
This method is used to retrieve information about an archive.

Syntax
HRESULT Get(void)

Remarks
The Get method tells the Content Management API to retrieve archive details
from the store, populating the properties of the object. Before calling this
method, the ArchiveId must be set.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The archive does not exist.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are 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
arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
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;
150 Content Management API
IArchive2 :: Type

IArchive2 :: Type
This property identifies the type of the archive, for example, Exchange Server
mailbox archive, FSA archive, SharePoint archive, and so on.
The property is read only.

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
EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.
See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.

Version information
At Enterprise Vault 8.0, this property is superceded by the IArchive3::Type
property.
See “IArchive3 :: Type” on page 160.

Return value

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.


Content Management API 151
IArchive2 :: Status

IArchive2 :: Status
This property indicates the status of the archive, that is, whether it can be
accessed.
The property is read only.

Syntax
HRESULT Status([out, retval] EV_STG_API_STATUS* pVal);

Parameters

[out, retval] EV_STG_API_STATUS* pVal Pointer to an EV_STG_API_STATUS that


contains the current value.

Remarks
EV_STG_API_STATUS enumeration indicates the status of the archive. See
“EV_STG_API_STATUS enumeration” on page 67.

Return value

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example
IArchive2 arch2 = cmAPI.Archive2;

arch2.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch2.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch2.Get();

EV_STG_API_STATUS evStatus = arch2.Status;

if (evStatus == EV_STG_API_STATUS. STS_AVAILABLE)


{
//store some items
152 Content Management API
IArchive2 :: HasFolders

IArchive2 :: HasFolders
This property indicates whether the archive is flat or contains a folder structure.
The property is read only.

Syntax
HRESULT HasFolders([out, retval] VARIANT_BOOL* pVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL that contains the


current value.

Remarks
In Enterprise Vault some types of archive, such as shared or journal archives,
cannot contain folders.

Return value

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example
IArchive2 arch2 = cmAPI.Archive2;

arch2.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch2.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;

bool hasFolders = arch2.HasFolders;

if (hasFolders == true)
{
//do something
Content Management API 153
IArchive2 :: Full

IArchive2 :: Full
This property indicates whether the archive is full.
The property is read only.

Syntax
HRESULT Full([out, retval] VARIANT_BOOL* pVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL that contains the


current value.

Remarks
If the archive is full, no more items can be stored in it.

Return value

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example
IArchive2 arch2 = cmAPI.Archive2;

arch2.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch2.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;

bool full = arch2.Full;

if (!full)
{
//store some items
154 Content Management API
IArchive2 :: DirectoryDNSAlias

IArchive2 :: DirectoryDNSAlias
This property contains the DNS Alias created for the Enterprise Vault Site.
The property is read only.

Syntax
HRESULT DirectoryDNSAlias([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Pointer to a string containing the current DNS alias for
the Enterprise Vault Site.

Remarks
When configuring Enterprise Vault, a DNS alias is assigned to the IP address of
the computer that hosts the primary Enterprise Vault Directory Service for the
Enterprise Vault Site.

Return value

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example
IArchive2 arch2 = cmAPI.Archive2;

arch.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
string dnsAlias = arch2.DirectoryDNSAlias;
Content Management API 155
IArchive3 :: SecurityDescriptor

IArchive3 :: SecurityDescriptor
This property contains the self-relative security descriptor associated with an
existing archive, or to be used when creating an archive. This property
represents the manually set permissions of the archive, which are displayed on
the Permissions tab of the archive properties dialog in the Enterprise Vault
Administration Console.
The property is read/write.
We recommend that you use the SecurityDescriptorString property to retrieve
and set the security descriptor from applications.
See “IArchive3 :: SecurityDescriptorString” on page 157.

Syntax
HRESULT SecurityDescriptor([out, retval] VARIANT* pVal);
HRESULT SecurityDescriptor([in] VARIANT newVal);

Parameters

[out, retval] VARIANT pVal Pointer to a VARIANT structure that will


hold the returned security descriptor value.

[in] VARIANT newVal New value of the security descriptor.

Remarks
If the type of the variant is VT_ARRAY, then the variant is a byte array
containing the SECURITY_DESCRIPTOR for the user account that will be given
access to the archive.
If the type of the variant is VT_EMPTY then the security descriptor is set to
default (that is, the user creating the archive has full access to the archive).
If the type of the variant is VT_NULL, then the archive is created without any
permissions.
EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security
descriptor permissions for an archive. The values are logically OR'd to get the
combined permissions.
See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.
Any attempt to modify the security descriptor of an existing archive will result
in an error.
156 Content Management API
IArchive3 :: SecurityDescriptor

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or


the object is already populated.

Example

C++
This example illustrates how to fetch the SecurityDescriptor property value.
CComPtr<IArchive> pArchive;

// Get an instance of an IArchive3 object to populate


pCmAPI->get_Archive(&pArchive);

CComQIPtr<IArchive3> pArchive3(pArchive);

if (pArchive3 != NULL)
{
pArchive3->put_Id(CComBSTR(L"240A579483C52B89384A9D7D9EACA0E7E
9350000evsite");

pArchive3->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7
D9EACA0E7E1210000evsite"));

// Retrieve Archive information


//
pArchive3->Get();

// Fetch the SecurityDescriptor property value associated


with archive
//
CComVariant varSecurityDescriptor;

pArchive3->get_SecurityDescriptor(&varSecurityDescriptor);

}
Content Management API 157
IArchive3 :: SecurityDescriptorString

IArchive3 :: SecurityDescriptorString
This property contains the security descriptor string associated with an existing
archive, or to be used when creating an archive. This property represents the
manually set permissions of the archive, which are displayed on the
Permissions tab of the archive properties dialog in the Enterprise Vault
Administration Console.
The property is read/write.

Syntax
HRESULT SecurityDescriptorString ([in] BSTR newVal);
HRESULT SecurityDescriptorString([out, retval] BSTR* pVal);

Parameters

[in] BSTR newVal The security descriptor value formatted as a


text string which conforms to the Security
Descriptor string format.

[out, retval] BSTR* pVal Pointer to a string that will hold the
returned security descriptor value.

Remarks
If specified, this property must be set before calling the Create archive method.
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.
158 Content Management API
IArchive3 :: SecurityDescriptorString

Security Descriptor strings using C++


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

Security Descriptor strings using .NET managed code


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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid, or


the object is already populated.

Examples

Example 1
The following security descriptor string indicates a user who has been granted
full permissions access (Read+Write+Delete) to an archive:
“D:(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-201182662-6419)”
This example shows the value associated with the Manual security descriptor
setting for the archive to which the user has full permissions access.

Example 2
This example includes the access described in “Example 1”, and in addition a
group has been granted full permissions access ( Read+Write+Delete) on the
archive:
Content Management API 159
IArchive3 :: SecurityDescriptorString

“D:(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-2011822662-6419)
(A;;CCDCLCSW;;;S-1-5-21-2986758783-3322231649-3643854221-1255)”

Example 3
This example includes the access described in “Example 1”, and in addition a
group have been denied full permissions access (Read+Write+Delete) on the
archive:
“D:(D;;CCDCLCSW;;;S-1-5-21-2986758783-3322231649-3643854221-1255)
(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-2011822662-6419)”
160 Content Management API
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.
The property is read/write.

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
contains the current value.

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.
EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.
See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.
The value of the property IArchive::HasFolders will be implied from the Type
property value. Table 4-20 shows the implied values. False means that the
archive is flat. True means that the archive is structured.

Table 4-20 Structure of archive types

EV_STG_API_ARCHIVE_TYPE value HasFolders property value

ARCHIVE_TYPE_SHARED False

ARCHIVE_TYPE_EXCHANGE_MAILBOX True

ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER True

ARCHIVE_TYPE_EXCHANGE_JOURNAL False

ARCHIVE_TYPE_FILE_SYSTEM True
Content Management API 161
IArchive3 :: Type

Table 4-20 Structure of archive types

EV_STG_API_ARCHIVE_TYPE value HasFolders property value

ARCHIVE_TYPE_SHAREPOINT True

ARCHIVE_TYPE_DOMINO_MAILBOX False

ARCHIVE_TYPE_DOMINO_JOURNAL False

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, newVal is invalid,


the object is already populated.

Example
[out]
IArchive3 arch3 = cmAPI.Archive3;

arch3.VaultStoreId =
“16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;
arch3.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
arch3.Get();

EV_STG_API_ARCHIVE_TYPE evType = arch3.Type;

if (evType == EV_STG_API_ARCHIVE_TYPE.
ARCHIVE_TYPE_EXCHANGE_MAILBOX)
{
// do something

[in]

IArchive3 arch3 = cmAPI.Archive3;

arch3.Name = “my new archive”;


arch3.Description = “my new archive description”;
arch3.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS;
arch3.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.
CONVERTED_CONTENT_STORED;
arch3.IndexUrgency = EV_STG_API_INDEX_URGENCY.
INDEX_ITEMS_IMMEDIATELY;
arch3.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;
arch3.Type = EV_STG_API_ARCHIVE_TYPE. ARCHIVE_TYPE_SHARED;
arch.Create();
162 Content Management API
Items object

Items object
This object implements the following interface:
■ 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 Read/Write The index sequence number ordering to be


used when enumerating items in the collection.

Table 4-9 and Table 4-10 list the properties and methods of the ICollectionBase
interface. For more detail see “ICollectionBase : IDispatch” on page 344.

Table 4-22 ICollectionBase properties

Property Read/Write Description

Count Read only Number of items in the collection.

_NewEnum Read only Instance of the standard COM enumerator for


the collection.

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


into the collection.

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


Content Management API 163
Items object

Table 4-22 ICollectionBase properties

Property Read/Write Description

More Read only Whether or not there were more items than
Maximum.

Table 4-23 ICollectionBase methods

Method Description

Get Populate the collection.

Clear Clear the current collection.

Reset Reset the object back to the initial state.

Remarks
Calling applications must have at least Read access to the target archive.
The following properties are populated for each Item object in the collection. If
additional properties are required for an Item, the Get method should be called
specifying the required detail level.
IItem::Id
IItem::ArchiveId
IArchiveMetaData2::SequenceNum
IArchiveMetaData2::CurrentLocation
IArchiveMetaData2::CurrentFolderId
IArchiveMetaData::RetentionCategory
IItem::CopyOptions
IItem::DeletionLevel
IArchvieMetaData::ComplianceDevice
IArchiveMetaData::OverrideOnholdRetCat
Populating these properties avoids the need to call Get to determine the source
item information before calling CopyTo or MoveTo.
Note that the items collection will not include items that have been soft deleted
from the archive, if this has been enabled. The soft delete functionality is
enabled using the Enterprise Vault Administration Console; by selecting the
archive setting, Enable recovery of user deleted items, in Site properties.
164 Content Management API
Items object

Version information
■ This interface requires Enterprise Vault 8.0 or later.

Example

C++
This example creates an Items collection object, enumerates the required items
in the target archive and retrieves details of the items from the Enterprise Vault
Directory.
// Get empty items collection for populating
CComPtr<IContentManagementAPI3> spCMAPI;
spCMAPI.CreateInstance(CComBSTR(L"EnterpriseVault.ContentManagement
API"));
CComPtr<IUnknown> spUnk;
VARIANT_BOOL vbMore = VARIANT_TRUE;

ULONGLONG LastSequenceNum;

// Get an Items object for enumeration


spCMapi->get_Items(&spUnk);

CComQIPtr<IItems> spItems(spUnk);

// Populate the Items collection


spItems->put_ArchiveId (CComBSTR("1C51F75FFC26EC840A012AD322C579
3AF1e10000LAGUNA4.REA.RND.SYM.COM"));
spItems->put_StartSequenceNum (1) // [Min = 1]
spItems->put_Maximum(500) // [Max = 10,000] (Comment: Ref
ICollectionBase :: Maximum)
spItems->put_OrderBy(ITEMS_ORDERBY_ASC) // Ascending

do
{
CComPtr<IItem> spItem;

// Fetch a batch of items


spItems->Get();

// Process each item in collection


long lCount = 0;
spItems->get_Count(&lCount);

// Iterative loop
for(long idx = 0; idx < lCount; ++idx)
{
CComPtr<IUnknown> spUnk;

//Fetch item
Content Management API 165
Items object

spItems->get_Item(idx, &spUnk);
CComQIPtr<IItem> spItem(spUnk);

//Do something
spItem->Get(DETAIL_LEVEL_ITEM_CONTENT |
DETAIL_LEVEL_ARCHIVE_METADATA);
...

// Remember the last item seq. no.


CComPtr<IArchiveMetaData> spAMD;
spItem->get_ArchiveMetaData(&spAMD);
CComQIPtr<IArchiveMetaData2> spAMD2(spAMD);
spAMD2->get_SequenceNum(&LastSequenceNum)
}

vbMore = spItems->More();

// Fetch next chunk of items


if (vbMore)
{
// Reset start sequence no to last itemís sequence no.
(of previous collection) + 1
spItems->put_StartSequenceNum = LastSequenceNum+1;
}
} while (vbMore)

See also
■ “Enumerating vault stores, archives and items” on page 53.
■ “ICollectionBase : IDispatch” on page 344.
■ “Item object” on page 172.
■ “ArchiveMetaData object” on page 237.
■ “Content object” on page 220.
166 Content Management API
IItems :: ArchiveId

IItems :: ArchiveId
This property identifies the archive in which the required items are stored.
The property is read/write.

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.

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the ID of
the current archive.

Remarks
Note that the value used can be either the Archive ID or the ID of a folder in the
archive, as this identifies both the archive and the archive folder.
The Archive ID is displayed in the properties of the archive in the
Administration Console.
The following gives an example value of the ArchiveId property:
“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is


not a valid archive identity.

Example
IContentManagementAPI4 cmAPI4 = new
(IContentManagementAPI4)ContentManagementAPIClass();

IItems items = cmAPI4.Items;


items.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
items.StartSequenceNum = 1000;
Content Management API 167
IItems :: ArchiveId

items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC;

items.Get();
168 Content Management API
IItems :: StartSequenceNum

IItems :: StartSequenceNum
This property specifies the Index Sequence Number (ISN) of the first item in the
items collection.
The property is read/write.

Syntax
HRESULT StartSequenceNum([in] ULONGLONG newValue);
HRESULT StartSequenceNum([out,retval] ULONGLONG* pVal);

Parameters

[in] ULONGLONG newValue Index sequence number of the first item in the
required items collection.

[out,retval] ULONGLONG* pVal Integer that will receive the index sequence number
of the first item in the collection.

Remarks
The Index Sequence Number of an archived item is specified in the
IArchiveMetaData2::SequenceNum property. This property can be used to
determine the start Index Sequence Number for the collection enumeration.
See “IArchiveMetaData2 :: SequenceNum” on page 273.
Enterprise Vault item sequence numbers are not always consecutive, as items
may have expired or been deleted.
The default value for this property is 1.

Requirements
Windows Server 2003 supports ULONGLONG types with OLE Automation.
However ULONGLONG types are not supported on Windows Server 2000.
.NET managed code and C++ support ULONGLONG types, but these types are
not supported by Visual Basic Script.

Return value

S_OK Success.
Content Management API 169
IItems :: StartSequenceNum

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is not a


valid archive identity.

Example
IContentManagementAPI3 cmAPI3 = new
(IContentManagementAPI3)ContentManagementAPIClass();

IItems items = cmAPI3.Items;


items.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
items.StartSequenceNum = 1000;
items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC;

items.Get();
170 Content Management API
IItems :: OrderBy

IItems :: OrderBy
This property is used to specify the index sequence number order to be used
when enumerating items in the collection.
The property is read/write.

Syntax
HRESULT OrderBy([in] EV_API_ITEMS_ORDERBY newVal);
HRESULT OrderBy[out,retval] EV_API_ITEMS_ORDERBY* pVal);

Parameters

[in] EV_API_ITEMS_ORDERBY newVal The index sequence number order


to use when enumerating the item
collection.

[out,retval] EV_API_ITEMS_ORDERBY* pVal The index sequence number order


used when enumerating the
current item collection.

Remarks
The default is to order by ascending index sequence number
(ITEMS_ORDERBY_ASC).
See “EV_API_ITEMS_ORDERBY enumeration” on page 58.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is invalid.

Example
IContentManagementAPI4 cmAPI4 = new
(IContentManagementAPI3)ContentManagementAPIClass();

IItems items = cmAPI4.Items;


items.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
items.StartSequenceNum = 1000;
items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC;
Content Management API 171
IItems :: OrderBy

items.Get();
172 Content Management API
Item object

Item object
This object implements the following interfaces:
■ 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.

DefaultMSGFormat Read/Write Sets the format (ANSI or Unicode) for the item being
retrieved, where the original format has not been
stored.
Content Management API 173
Item object

Table 4-24 IItem properties

Property Read/Write Description

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.
174 Content Management API
Item object

Table 4-27 IItem3 method

Property Description

Undelete Recover an item that has been soft-deleted.

Remarks
After the Create or Get method has been called on this interface, the current
interface pointer must be released and a new one obtained before calling either
of these methods again.

Version information
■ CopyOptions property requires Enterprise Vault 8.0.
■ IItem2 interface requires Enterprise Vault 8.0 SP3.
■ IItem3 interface requires Enterprise Vault 9.0.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);
Content Management API 175
IItem :: ArchiveId

IItem :: ArchiveId
This property identifies the archive in which the item is stored, or to be stored.
The property is read/write.

Syntax
HRESULT ArchiveId([out, retval] BSTR* pVal);
HRESULT ArchiveId([in] BSTR newVal);

Parameters

[in] BSTR newVal The Archive ID of the archive.


Maximum length of string: 127 characters.

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the ID of
the current archive.

Remarks
Note that the value used can be either the Archive ID or the ID of a folder in the
archive, as this identifies both the archive and the archive folder.
This property must be set before calling Get.
An error will result if an attempt is made to change the value of an existing item.
This value is displayed in the properties of the archive in the Administration
Console.
The following gives an example value of the ArchiveId property:
“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL, or newVal is not a


valid Archive Id.
176 Content Management API
IItem :: ArchiveId

Examples

C#
IItem itm = cmAPI.Item;
itm.ArchiveId = "“181E669473B52E64384C9A7D9EACA0E7E1110000evsite";
itm.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7
9f3298dc8a1e60";
itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);
Content Management API 177
IItem :: Id

IItem :: Id
This property identifies the item in the archive.
This property is read/write.

Syntax
HRESULT Id([out, retval] BSTR* pVal);
HRESULT Id([in] BSTR newVal);

Parameters

[in] BSTR newVal Id of stored item.

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the


current value of this item’s ID.

Remarks
This property sets or retrieves the identifier of the item in the archive. It is only
populated once an item has been stored in an archive, and must be set before
calling the Get method.
It should not be set before calling an Insert method, as this will result in an
error.
Any attempt to change the value of an existing item will result in an error.
This property can hold the item’s Transaction ID or Saveset ID.
See “Saveset IDs and Transaction IDs” on page 54.

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.
178 Content Management API
IItem :: Id

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL,


or newVal is not a valid Saveset ID or
Transaction ID,
or an attempt has been made to set the
Saveset ID of an existing item.

Examples

C++
CComBSTR bstr(L“161000000000000~200501051649270000~0~9039eb282e3d4
083b79f3298dc8a1e60“)

item->put_Id(bstr);

//DO Get and check the id

bstr.Clear();
item->get_Id(&bstr);

C#
IItem item = cmAPI.Item;
item.Id = “161000000000000~200501051649270000~0~9039eb282e3d4083b7
9f3298dc8a1e60“;
itm.Archive.Id = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite";
itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);
Content Management API 179
IItem :: Content

IItem :: Content
This property returns an instance of a Content object that gives access to the
data that is to be archived, or has been archived (depending on when it is used).
The property is read only.
The interface pointer to IContent is read only, however, the methods and
properties exposed by IContent allow the content, including the item data, to be
modified.

Syntax
HRESULT Content([out, retval] IContent** pVal);

Parameters

[out,retval] IContent** pVal Instance of a Content object.

Remarks
The IContent interface makes the following properties available. Each of these is
described in more detail in the relevant section.
■ Title
■ OriginalLocation
■ FileExtension
■ MimeFormat
■ CreatedDate
■ ModifiedDate
■ Data
■ OriginalSize
■ Author
See “Content object” on page 220.

Return value

S_OK Success.
180 Content Management API
IItem :: Content

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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);
Content Management API 181
IItem :: ArchiveMetaData

IItem :: ArchiveMetaData
This property returns a pointer to an IArchiveMetaData interface that provides
details of how the item will be or has been archived.
The property is read only.
The interface pointer to IArchiveMetaData is read only. However, the methods
and properties exposed by IArchiveMetaData allow the metadata to be modified.

Syntax
HRESULT ArchiveMetaData([out, retval] IArchiveMetaData** pVal);

Parameters

[out,retval] IArchiveMetaData** pVal Pointer to an IArchiveMetaData pointer.

Remarks
The IArchiveMetaData interface makes available properties that hold
information about the item, such as the assigned Retention Category and the
date and time when the item was archived. Each of these is described in more
detail in the relevant section.
See “ArchiveMetaData object” on page 237.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;


182 Content Management API
IItem :: ArchiveMetaData

See also
■ See “ArchiveMetaData object” on page 237.
Content Management API 183
IItem :: BrowserViewURL

IItem :: BrowserViewURL
This property returns a string containing the URL that should be entered into a
web browser (for example) to view the item.
The property is read only.

Syntax
HRESULT BrowserViewURL([out,retval] BSTR* pVal)

Parameters

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the URL.

Remarks
This property will return an error if the archive Id and item Id have not been set
previously.
The URL returned includes the IIS virtual directory for the Enterprise Vault
Web access application, but not a specific Web server name. Enterprise Vault
dynamically generates the full URL as needed, with the appropriate server name
for each caller.
This form of URL is compatible with Enterprise Vault Building Blocks architec-
ture.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the Archive Id or Saveset Id


have not been set or the Saveset Id is
invalid.

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.
184 Content Management API
IItem :: BrowserViewURL

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;


Content Management API 185
IItem :: DefaultMSGFormat

IItem :: DefaultMSGFormat
This property allows the caller to set the format as ANSI or Unicode for the item
being retrieved, where the original format has not been stored with the saveset.
The property is optional.

Syntax
HRESULT DefaultMSGFormat([in] BSTR newVal);
HRESULT DefaultMSGFormat([out,retval] BSTR* pVal);

Parameters

[in] BSTR newVal New value to be set.


See “Remarks”.

[out,retval] BSTR* pVal Pointer to a BSTR that will hold the current value.

Remarks
The following values can be assigned to newVal:

“N” Perform no conversion.

"U" Return as Unicode.

"A:nnnn" Return as ANSI code page. For example, "A:932" return as Japanese ANSI.

DefaultMSGFormat allows the caller to set the default format as ANSI or


Unicode for the item being retrieved, where the original format has not been
stored with the saveset.
From Enterprise Vault 6.0 SP1, items are stored in Enterprise Vault as Unicode.
In addition, items archived using File System Archiving, SharePoint archiving,
or API methods, store details of the original format with the saveset. If details of
the original format were stored, then the item will always be returned in its
original format, irrespective of the value of DefaultMSGFormat.
However, items stored using Exchange Server archiving tasks (or PST
migration) do not record details of the original format. The value set for
DefaultMSGFormat, will be applied to any such items that do not have the
original format recorded.
If no value is specified for DefaultMSGFormat, then no conversion is performed
and the archive format is used. On a system with messages archived using an
186 Content Management API
IItem :: DefaultMSGFormat

earlier release than Enterprise Vault 6.0 SP1, this means that items archived
prior to Enterprise Vault 6.0 SP1 are returned in ANSI format, and items
archived since the upgrade to Enterprise Vault 6.0 SP1 are returned in Unicode
format.
If a value has not been explicitly set, then this property will return null.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


attempt has been made to change an
existing value.

Examples

C++
item->put_DefaultMSGFormat(L“U“);

//do something, put ids etc


Item->Get(DETAIL_LEVEL_ALL);
Itm->put_DefaultMSGFormat(L”N”); // ERROR

C#
itm.DefaultMSGFomart = “U”;

//do something – set ids etc


Itm.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ALL));
Itm.=defaultMSGFormat = “N”; //ERROR
Content Management API 187
IItem :: Holds

IItem :: Holds
This property gives access to the set of holds currently placed on the item. The
property is read only. For a description of a hold, see “About Legal Hold” on
page 313.

Syntax
HRESULT Holds([out,retval] IHolds** pVal);

Parameters

[out,retval] IHolds** pVal Pointer to an IHolds pointer which will contain the
current IHolds pointer.

Remarks
This property is a collection of IHold pointers, each of which defines a hold
placed on the particular item.
The caller must have called the IItem.Get method with the
DETAIL_LEVEL_HOLD_DATA flag set prior to calling this property.
See “IItem :: Get” on page 200.
This property is a collection of IHold pointers, each of which defines a hold
placed on the particular item.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or could not


find the HOLDS collection.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA);

IHolds holds = Item.Holds;


188 Content Management API
IItem :: NativeItemURL

IItem :: NativeItemURL
The URL downloads the item that was archived and attempts to open the item
using the default application for the type of the item.

Syntax
HRESULT NativeItemURL([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal A pointer to a BSTR that will contain the current value.

Remarks
There will be an error if either the item Id or the archive Id have not been set
before using this property.
The URL returned includes the IIS virtual directory for the Enterprise Vault
Web access application, but not a specific Web server name. Enterprise Vault
dynamically generates the full URL as needed, with the appropriate server name
for each caller.
This form of URL is compatible with Enterprise Vault Building Blocks architec-
ture.

Return Value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


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

Examples

C++
CComBSTR bstr;

item->get_NativeItemURL(&bstr); //ERROR
Content Management API 189
IItem :: NativeItemURL

item->put_Id(L”200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e6
0”)

item->put_ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evsit
e”);
item->get_NativeItemURL(&bstr); //SUCCESS

C#
string url = item.NativeItemURL; //ERROR

item.Id(“200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”);

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
string url = item.NativeItemURL; //SUCCESS
190 Content Management API
IItem :: DeletionLevel

IItem :: DeletionLevel
This property indicates the type of delete to be used for the archived item. Items
can be deleted completely (hard delete), or moved to the Enterprise Vault
"dumpster" area (soft delete).
The property is read/write.

Syntax
HRESULT DeletionLevel([in] EV_API_DELETION_LEVEL newVal);
HRESULT DeletionLevel([out,retval] EV_API_DELETION_LEVEL* pVal);

Parameters

[in] EV_API_DELETION_LEVEL newVal New EV_API_DELETION_LEVEL


value.

[out,retval] EV_API_DELETION_LEVEL* pVal Current EV_API_DELETION_LEVEL


value.

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

Version information
■ The ability to retrieve deleted items in Enterprise Vault is available from
Enterprise Vault 2007.
Content Management API 191
IItem :: DeletionLevel

Return Value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or newVal is invalid.

Example
[in]

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
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]
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ITEM_PROPERTIES);

EV_API_DELETION_LEVEL evDL = item.DeletionLevel;


192 Content Management API
IItem :: CopyOptions

IItem :: CopyOptions
This property identifies the source item property values to be copied to the
destination item.
The property is read/write.

Syntax
HRESULT CopyOptions([in] EV_STG_API_ITEM_COPYOPTIONS newVal);
HRESULT CopyOptions([out,retval] EV_STG_API_ITEM_COPYOPTIONS*
pVal);

Parameters

[in] EV_STG_API_ITEM_COPYOPTIONS newVal New bit mask value specifying


which item elements are to be
copied from the source item
equivalents.
This value can be one or more
of the enumerated values. Use
more than one by joining them
with ‘OR'.

[out,retval] EV_STG_API_ITEM_COPYOPTIONS* pVal Current bit mask value.

Remarks
The calling application sets the CopyOptions property on the destination item
object that is supplied in calls to the CopyTo or MoveTo methods.
The value of CopyOptions can be one or more of the
EV_STG_API_ITEM_COPYOPTIONS enumeration values. The default value is
ITEM_COPYOPTIONS_ARCHIVEMETADATA. If this is set, then the values of
the following ArchiveMetaData properties on the source item will be copied to
the equivalent properties on the destination item, unless explicitly provided as
part of the CopyTo or MoveTo method call:
■ SimpleIndexMetaData
■ ArchivedDate
■ RetentionCategory
■ CurrentLocation
■ CurrentFolder
Content Management API 193
IItem :: CopyOptions

■ CustomIdentifier
■ CustomQualifier
■ CustomProperties
See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 64.

Specifying item property override values


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

Table 4-28 Effect of setting override item property values with


ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value

Item property Option Override Property value in copied item


selected value set on
destination
item

ArchivedDate Yes (Default) Yes Set to override value.


Set to current date/time if the override
value supplied as a null (VT_NULL)
variant property value.

No Yes As above.

Yes (Default) No Copied from source item.

No No Set to current date/time.

RetentionCategory Yes (Default) Yes Set to override value.


Set to the site default Retention Category
if override value specified as a zero
length string value.

No Yes As above.
194 Content Management API
IItem :: CopyOptions

Table 4-28 Effect of setting override item property values with


ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value

Item property Option Override Property value in copied item


selected value set on
destination
item

Yes (Default) No Copied from source item. 1

No No Set to the site default Retention


Category.

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


CustomQualifier Set to zero value if override specified as
CustomProperties zero value.

No Yes As above.

Yes (Default) No Copied from source item.

No No Set to zero value.

CurrentLocation Yes (Default) Yes Set to override value.


CurrentFolderId

No Yes See “Which properties determine the


current archive folder” on page 267.

Yes (Default) No Copied from source item. 3

No No See “Which properties determine the


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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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.
Content Management API 195
IItem :: CopyOptions

Examples

Visual Basic Script example


In the following example the source item’s ArchiveMetaData values are
preserved on the destination item.
Dim ecmAPI
Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")

Dim oItem, oDestItem

' Establish the source item

Set oItem = ecmAPI.Item

' Establish the destination item

Set oDestItem = ecmAPI.Item

oDestItem.ArchiveId =
“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”

' Set the CopyOptions flags to set the copied item's TransactionId
' and ArchiveMetaData values
' from the source item (Ref EV_STG_API_ITEM_COPYOPTIONS)

oDestItem.CopyOptions = 3

oItem.CopyTo (oDestItem)
196 Content Management API
IItem :: Insert

IItem :: Insert
This method is used to store an item in an archive.

Syntax
HRESULT Insert(void);

Remarks
It is important to make sure that this interface pointer has not been used before
to perform an Insert or Get action.
The caller must have WRITE access permissions on the destination archive,
otherwise an error will occur. For structured archives, the caller must have write
access to the destination archive folder.
If an override value is specified for the ArchivedDate property, the calling
application must be in an Enterprise Vault role that includes the operation,
“{API} Can Use Extended API Features”. This operation is included in the default
Enterprise Vault Power Administrator and Storage Administrator roles.
The Insert method stores an item in the specified archive. Before calling Insert,
the following properties must be populated:
■ IItem :: ArchiveId
■ IContent :: Data
■ Either IContent :: FileExtension or IContent :: MIMEFormat. Enterprise
Vault uses the supplied extension or MIME type to enhance indexing and
storage functionality for content types such as Outlook messages. If you
assign any other values to an item, Enterprise Vault archives and indexes
the item as a file. Enterprise Vault provides enhanced indexing and storage
functionality for the following content types:

Content type File extension MIME format

Outlook messages .msg application/vnd.ms-outlook

SMTP messages .eml message/rfc822

When you call Insert, the IItem :: Id property must be empty.


After this method has been called, and assuming the operation was successful,
the Id property will be populated with the identifier of the item in the archive.
Calling this method on an Item that already contains an Id (that is, an item that
has already been stored) will cause an error condition.
Content Management API 197
IItem :: Insert

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One of the required property


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault


Directory or Storage services
are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently


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

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is


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

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The target archive is full or


exceeds its quota limit.
198 Content Management API
IItem :: Insert

CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have write


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

CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID Item Id is not unique in the


target vault store.

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to insert items


into a structured archive
containing multiple root
folders (for example, a public
folder archive).

Examples

C+ +

spItem.put->ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evs
ite”);
IContent* pContent = null;
spItem->get_Content(&pContent);
pContent->put_Title(L"new title");
pContent->put_FileExtension(L"msg");
pContent->put_Data(L“C:\\temp\\test.msg”);
spItem->Insert();

C#

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.Data = "C:\\temp\\test.msg";
item.Insert();
Content Management API 199
IItem :: Insert

See Also
“Content object” on page 220
200 Content Management API
IItem :: Get

IItem :: Get
This method is used to retrieve an archived item or information about an item.

Syntax
HRESULT Get([in] LONG DetailLevel);

Parameters

[in] LONG DetailLevel A bit-mask that specifies the item related data to retrieve.
This value can be one or more of the
EV_STG_API_ITEM_DETAIL enumerated values. Use more
than one by joining them with ‘or'.
See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.

Remarks
The item's ArchiveId and either its Id property or
IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier
properties must be set prior to calling this method.
When retrieving hold data only, the item's Id property must be used
(DetailLevel = DETAIL_LEVEL_HOLD_DATA).
The item's CustomIdentifier and CustomQualifier properties can only be used
when together they uniquely identify an item.
See “IIArchiveMetaData :: CustomIdentifier” on page 257.
EV_STG_API_ITEM_DETAIL indicates the data to retrieve for an item.
See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.
The caller can “bitwise OR” the bit masks together. For example, IItem.Get(255)
returns the item properties and the metadata.
If the soft delete feature has been enabled, items that have been soft deleted
from the archive are retrieved. The soft delete functionality is enabled using the
Enterprise Vault Administration Console; by selecting the archive setting,
Enable recovery of user deleted items, in Site properties.
To retrieve the item content, the caller must populate the IContent::Data
property with a file location on disk, or to an IStream or ILockbytes object that
has been created ready to receive the item content.

Note: If you specify a file, any existing content will be overwritten.


Content Management API 201
IItem :: Get

The Content Management API supports IStream and ILockBytes


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

Return values

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer passed in is NULL,


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory


or Storage services are not
running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently


busy or has insufficient
resource to complete the
request. This error indicates
that the caller should retry
later.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is


unknown or has been deleted,
or the selected item is not
present or has been deleted.
202 Content Management API
IItem :: Get

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

Version information
■ Retrieving expanded distribution list information using the
DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA value of
EV_STG_API_ITEM_DETAIL enumeration is available in Enterprise Vault
6.0 SP4 and Enterprise Vault 7.0 SP2.
See “Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault
6.0 SP4” on page 33.
Note that this feature requires MSXML 3.0 or later.
■ When the enumerated value, DETAIL_LEVEL_ITEM_CONTENT, is included
as part of the input parameter for IItem::Get, the correct date and time is
now returned by IContent::ModifiedDate and IContent::CreatedDate. This is
fixed in Enterprise Vault 6.0 SP4 and Enterprise Vault 7.0 SP2, and later.
See “Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault
6.0 SP4” on page 33.
■ IArchiveMetaData::CustomIdentifier and
IArchiveMetaData::CustomQualifier require Enterprise Vault 8.0.
See “Enterprise Vault 8.0” on page 25.

Examples
Refer to Microsoft documentation for details and usage of IStorage and IStream.

C++
item->put_Id(
L” 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”);
item->put_ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000site“
);
IStorage* pStorage = NULL;
StgCreateStorageEx(NULL, STGM_READWRITE | STGM_CREATE, STGFMT_FILE,
0, NULL, 0, NULL, IID_IStorage,
reinterpret_cast<void**>(&pStorage));
IStream* pStream = NULL;
Content Management API 203
IItem :: Get

pStorage->CreateStream(„Test Stream“, STGM_READSWRITE |


STGM_CREATE, 0, 0, &pStream);

IContent* pContent = NULL;


item->get_Content(&pContent);

pContent->put_Data(pStream);

item->Get(DETAIL_LEVEL_ITEM_CONTENT);

//do something

pStream->Release();
pStream = NULL;
pStorage->Release();
pStorage = NULL;
pContent->Release();
pContent = NULL;
item->Release();
item = NULL;

C#
item.Id = ” 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
Item.ArchiveId = “181E669473B52E64384C9A7D9EACA0E7E1110000evsite“;

IContent content = null;


content = item.Content;
content.Data = "C:\\temp\\temp.msg";

item.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_CONTENT));
//do something
204 Content Management API
IItem :: Delete

IItem :: Delete
This method is used to delete an item from an archive.

Syntax
HRESULT Delete(void);

Remarks
Calling the Delete method will remove the item from its archive. The value of the
DeletionLevel property will determine whether a hard or soft delete is
performed.
Prior to calling this method, the application programmer must have set the
ArchiveId (to identify the archive containing the item), and the Id property to
identify the item within its container.
It cannot be called on an item whose ArchiveId and Id properties have not been
set, as this will cause an error.
The calling user must have the appropriate permissions to delete the item. It is
also possible that the server will reject the request because an item is “On Hold”
or cannot be removed for compliance reasons.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in,


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

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or


has been deleted.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or


has insufficient resource to
complete the request. This error
indicates that the caller should retry
later.
Content Management API 205
IItem :: Delete

CONTENTMANAGEMENTAPI_E_NO_ACCESS 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“);

item->Delete();

C#
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ITEM_PROPERTIES);

object obj = item.CanBeDeleted;


int canBeDeleted = (int)obj;
if (obj == 0)
{
item.Delete();
}
206 Content Management API
IItem :: CanBeDeleted

IItem :: CanBeDeleted
This method determines if an item can be deleted from an archive.

Syntax
HRESULT CanBeDeleted([out,retval] VARIANT* CanDelete);

Parameters

[out,retval] VARIANT* CanDelete Pointer to a VARIANT containing the


current value.

Remarks
CanBeDeleted returns a value to indicate whether or not the item can be deleted.
For possible values, see “EV_STG_API_CAN_DELETE enumeration” on page 60.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER ANULL pointer has been passed in,


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or


has insufficient resource to complete
the request. This error indicates that
the caller should retry later.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or


has been deleted, or
the selected item is not present or
has been deleted.

CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have read access


to the target archive or archive
folder.
Content Management API 207
IItem :: CanBeDeleted

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

object obj = item.CanBeDeleted;


int canBeDeleted = (int)obj;
if (obj == 0)
{
item.Delete();
}
208 Content Management API
IItem :: CopyTo

IItem :: CopyTo
This method is used to copy an item from one archive to another.

Syntax
HRESULT CopyTo([in] IItem* DestinationItem);

Parameters

[in] IItem* DestinationItem IItem interface pointer that represents the


destination item.

Remarks
The source and destination archive and vault store may be different, but the
source and destination site must be the same.
The caller must have READ access to the source archive, and WRITE access
permissions on the destination archive, otherwise an error will occur. For
structured archives, the caller must have READ access to the source archive
folder and WRITE access to the destination archive folder.
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.
When copying an item:
■ Create the destination item object.
■ Set the ArchiveId on the destination item object.
■ Set CopyOptions properties on the destination item object.
■ Optionally set any ArchiveMetadata override property values if the copy
option, ITEM_COPYOPTIONS_ARCHIVEMETADATA, is selected.
The CopyOptions property on the destination item object specifies the item
elements to be copied across to the destination item.
See “IItem :: CopyOptions” on page 192.
From Enterprise Vault 8.0, the default action has changed; the item content and
its associated ArchiveMetaData and IndexData elements are copied from the
source item. This means that the default behaviour preserves the original
ArchivedDate and OriginalLocation on the destination item, if override values
are not specified.
Content Management API 209
IItem :: CopyTo

For backwards compatibility, the calling application can set suitable override
values on the destination item object.
See “Specifying item property override values” on page 193.
For important considerations when specifying the destination archive folder,
see “Which properties determine the current archive folder” on page 267.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the destination archive


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault


Directory or Storage services
are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently


busy or has insufficient
resource to complete the copy,
or Enterprise Vault is
currently being backed up and
is not accepting copy
requests. This error indicates
that the caller should retry
later.
210 Content Management API
IItem :: CopyTo

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

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is full


or exceeds its quota limit.

CONTENTMANAGEMENTAPI_E_NO_ACCESS No access to the archive or


archive folder, or
or the target archive is in a
read-only state,
an override value has been
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).

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to copy items to a


structured archive containing
multiple root folders (for
example, a public folder
archive).

Examples

C++
IItem* pItemSrc = NULL;
pCmAPI->get_Item(&pItemSrc);
pItemSrc->put_ArchiveId(CComBSTR(L”181E669473B52E64384C9A7D9EACA0E7
E1110000evsite”));
pItemSrc->put_Id(CComBSTR(L“334880000000000~200707251102240000~0~D3
962A35951E4B03AE9CFB68AFE1218“));

IItem* pItemDst = NULL;


pCmAPI->get_Item(&pItemDst);

IArchiveMetaData* pDstAMD = NULL;


Content Management API 211
IItem :: CopyTo

pItemDst->get_ArchiveMetaData(&pDstAMD);
pDstAMD->put_RetentionCategory(CComBSTR(L”Business”));

IComplianceData* pDstComp = NULL;


pDstAMD->get_ComplianceData(&pDstComp);
pDstComp->SetBy(SETBY_RETCAT);

pItemSrc->CopyTo(pItemDst);

C#
IItem itemSrc = cmAPI.Item;
IItem itemDst = cmAPI.Item;
itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000ev
site”;
itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218”;

itemDst.ArchiveMetaData.RetentionCategory = “Business”;
itemDst.ArchiveMetaData.ComplianceData.SetBy =
EV_STG_API_CP_SETBY.SETBY_RETCAT;
itemSrc.CopyTo(itemDst);
212 Content Management API
IItem :: MoveTo

IItem :: MoveTo
This method is used to move an item from one archive to another.

Syntax
HRESULT MoveTo([in] IItem* DestinationItem);

Parameters

[in] IItem* DestinationItem Pointer to the destination item object.

Remarks
The source and destination archive and vault store may be different, but the
source and destination site must be the same.
The caller must have DELETE access to the source archive and archive folder,
and WRITE access permissions on the destination archive and archive folder,
otherwise an error will occur.
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 MoveTo method is identical to the CopyTo operation, but it additionally
removes the source item from the source archive after the copy has completed.
See “IItem :: CopyTo” on page 208.
The CopyOptions property on the destination item object specifies the item
elements to be copied across to the destination item.
See “IItem :: CopyOptions” on page 192.

Return value

S_OK Success.
Content Management API 213
IItem :: MoveTo

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the destination


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault


Directory or Storage services
are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently


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

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

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is


full or exceeds its quota limit.
214 Content Management API
IItem :: MoveTo

CONTENTMANAGEMENTAPI_E_DELETION_BARRED The source item cannot be


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

CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have


delete access to the source
archive or archive folder,
or does not have write access
to the destination archive or
archive folder,or
or the source or destination
archive is in a read-only
state,
an override value has been
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)

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to move items to


a structured archive
containing multiple root
folders (for example, a public
folder archive).

Example
IItem itemSrc = cmAPI.Item;
IItem itemDst = cmAPI.Item;
itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000ev
site”;
itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218”;
itemDst.ArchiveMetaData.RetentionCategory = “Business”;
itemDst.ArchiveMetaData.ComplianceData.SetBy =
EV_STG_API_CP_SETBY.SETBY_RETCAT;
itemSrc.MoveTo(itemDst);
Content Management API 215
IItem2 :: DeletionReason

IItem2 :: DeletionReason
If an item no longer exists in the archive, this property can be used to find out
why the item was deleted.
This property is read only.

Syntax
HRESULT DeletionReason([out,retval]
EV_STG_API_DELETION_REASON* pVal)

Parameters

[out,retval] EV_STG_API_DELETION_REASON* pVal Current EV_STG_API_


DELETION_REASON value.

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

Return value

S_OK Success.

S_FALSE Success. The default value (NULL)


is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is


NULL, or
the item's Archive Id or Id
property have not been set.

CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have read access to


the archive.
216 Content Management API
IItem2 :: DeletionReason

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND There is no evidence that the


requested item existed in the
specified archive; the item does
not exist in the archive and there
is no current record of deletion.

Examples

C#
Item2 destItem = (IItem2)cmAPI.Item;
destItem.ArchiveId = ="1BFE65542AFD18F418824B15EF3288CD51110000
EVServer.corp.com";
destItem.Id = "200908040000000~200908041247260000~Z~80BD742AD7B88D0
850524974B9F44901";
try
{
// Try to get the item
destItem.Get((int)(
EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES
|EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA
|EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_SYSTEM_INDEXDATA));
}
catch (COMException e)
{
// If ITEM NOT FOUND error is thrown,
// check the deletion reason of the item.
if (e.ErrorCode == (int)EV_STG_API_ErrorCodes.
CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND)
{
EV_STG_API_DELETION_REASON delReason =
EV_STG_API_DELETION_REASON.DELETION_REASON_UNKNOWN;

try
{
delReason = destItem.DeletionReason;
}
finally
{
// Log that the item was not found together with the
// deletion reason
LogItemNotFound(destItem, delReason);
}
}
}
Content Management API 217
IItem3 :: Undelete

IItem3 :: Undelete
If an item has been moved to the Enterprise Vault "dumpster" area (soft deleted),
this method can be used to recover the item. The item is restored from the
dumpster area to the archive.

Syntax
HRESULT Undelete([out, retval] VARIANT_BOOL* pVal)

Parameters

[out,retval] VARIANT_BOOL* pVal A value of TRUE indicates that the item has
been recovered.

Remarks
The caller must be in an Enterprise Vault role that allows the operation “Can
undelete items in any archive”. (The task definition, "EVT Execute undelete
from archives", is included in the role, "Placeholder Application".)
Before calling Undelete, both the Archive ID and the Item ID must be set on the
Item object.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id has not been


found.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is


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

CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have undelete


access to the archive. That is, the
caller is not in a role that allows
the operation, “Can undelete items
in any archive”.
218 Content Management API
IItem3 :: Undelete

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND The item could not be found in the


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy


or has insufficient resources to
complete the request. This error
indicates that the caller should
retry later.

Version information
■ IItem3 interface requires Enterprise Vault 9.0.

See also
■ “IItem :: DeletionLevel” on page 190

Examples

C#
IItem3 item = (IItem3)cmAPI.Item;

item.ArchiveId =
“118F819534E391C43B6854E2DD3A708C61110000EV.example.com”;
item.Id =
“201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51
651”;

bool UnDeleted = item.Undelete();

Visual Basic Script


Dim ecmAPI, oItem, oItem3

Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")


set oItem = ecmAPI.Item

set oItem3 =
ecmAPI.IDispatchQueryInterface(oItem,"{E5C7F710-36AD-4e24-B00A-E3D7
09FF76CD}")
Content Management API 219
IItem3 :: Undelete

oItem3.ArchiveId =
"118F819534E391C43B6854E2DD3A708C61110000EV.example.com"
oItem3.ID =
"201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51
651"

dim results
result = oItem3.Undelete

if (Err.number <> 0) then


WScript.Echo "Error: " & Err.Description
end if

if result then
WScript.Echo "Item Undeleted"
else
WScript.Echo "Item has not been Undeleted"
end if
220 Content Management API
Content object

Content object
This object implements the following interface:
■ IContent
The IContent interface is obtained from an instance of IItem using the Content
property and provides calling applications with a set of properties that describe
the data being archived.

Syntax
interface IContent : IDispatch

Member summary

Table 4-29 IContent Properties

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.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
Content Management API 221
Content object

content.Title = "New title";


content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
item.Insert();
222 Content Management API
IContent :: Title

IContent :: Title
This property holds the name, title or subject of the item.
The property is read/write.

Syntax
HRESULT Title([out, retval] BSTR* pVal);
HRESULT Title([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal The title of this item.

[in] BSTR newVal The new title of this item.

Remarks
If an attempt is made to change the title after a call to Insert or Get, an error will
occur.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or the


title of this item has already been
set in a previous call to Insert.

Example

C#
IContent content = itm.Content;
string title = content.Title;
Content Management API 223
IContent :: OriginalLocation

IContent :: OriginalLocation
This property holds the original location of the item.
The property is read/write.

Syntax
HRESULT OriginalLocation([out, retval] BSTR* pVal);
HRESULT OriginalLocation([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the original
location

[in] BSTR newVal The original location value to be set.

Return value

S_OK Success.

S_FALSE Success. The default value (NULL) is


returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or this property has already been set.

Example
item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
item.Insert();
224 Content Management API
IContent :: FileExtension

IContent :: FileExtension
This property holds the file extension describing the format of the item.
The property is read/write.

Syntax
HRESULT FileExtension([out, retval] BSTR* pVal);
HRESULT FileExtension([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current
file extension.

[in] BSTR newVal The file extension to use.

Remarks
This property describes the format of the item.
For example, use ‘ .txt’ where the content is simple text, or ‘.msg’ where the
content is in Outlook message file format.
It is required so that the item can be indexed when it is archived, and opened
correctly by a web browser using IItem :: BrowserViewURL. The default value is
“.bin”.
The preceding period in a file extension can be included or omitted when setting
a value. It will be added by the API when the item is archived.
Once this value has been set it cannot be changed.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


attempt has been made to change
an existing value.
Content Management API 225
IContent :: FileExtension

Example
item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
item.Insert();
226 Content Management API
IContent :: MIMEFormat

IContent :: MIMEFormat
This property is optional and describes the MIME file format of the item.
This property is useful for HTTP Web-based client applications that process
byte streams with the MIME type parameter (content-type), rather than files.
The property is read/write.

Syntax
HRESULT MIMEFormat([out, retval] BSTR* pVal);
HRESULT MIMEFormat([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current value
of the property

[in] BSTR newVal The new value of the property to be set

Remarks
For example, use ‘text/plain’ where the content is simple text, or
‘application/vnd.ms-outlook’ where the content is in Outlook message file
format.
If the property is set, it cannot be changed after the item has been archived.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


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

Example
item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.MIMEFormat = "text/plain";
content.OriginalLocation = “C:\\temp”;
Content Management API 227
IContent :: MIMEFormat

content.Data = "C:\\temp\\test.txt";
item.Insert();
228 Content Management API
IContent :: CreatedDate

IContent :: CreatedDate
This property contains the UTC date and time that the item was created.
The property is read/write.

Syntax
HRESULT CreatedDate([out, retval] VARIANT* pVal);
HRESULT CreatedDate([in] VARIANT newVal);

Parameters

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the value
of the property.

[in] VARIANT newVal The new value to set this property.

Remarks
Once this item has been archived it is not possible to change the value of this
property.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or


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

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ITEM_PROPERTIES);

IContent cont = item.Content;


Content Management API 229
IContent :: CreatedDate

object obj = content.CreatedTime;


DateTime dt = (DateTime)obj;
230 Content Management API
IContent :: ModifiedDate

IContent :: ModifiedDate
This property contains the UTC date and time that the item was last modified.
The property is read/write.

Syntax
HRESULT ModifiedDate([out, retval] VARIANT* pVal);
HRESULT ModifiedDate([in] VARIANT newVal);

Parameters

[out, retval] VARIANT* pVal The UTC date and time that the item was last
modified.

[in] VARIANT newVal Optional property that contains the UTC date and
time that the item was last modified.

Return value
Once this item has been archived it is not possible to change the value of this
property.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or either


this property is being modified after
the item has been saved in the
archive, or the value passed into the
property is not in the correct
format.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ITEM_PROPERTIES);

IContent cont = item.Content;

object obj = content.ModifiedTime;


Content Management API 231
IContent :: ModifiedDate

DateTime dt = (DateTime)obj;
232 Content Management API
IContent :: Data

IContent :: Data
This property is used to pass the raw content of the item to or from the archive.
The property is read/write.

Syntax
HRESULT Data([out, retval] VARIANT* pVal);
HRESULT Data([in] VARIANT newVal);

Parameters

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the actual
item data.

[in] VARIANT newVal Variant containing the data.

Remarks
One important point to remember is that the item data, properties and archive
metadata is not archived until the Insert method has been called.
This property must be set to the path of a file on disk, or an IStream or
ILockBytes object.

Note: If you specify a file, any existing content will be overwritten when
retrieving an item.

If the calling application is a .NET application, and the overhead of saving the
item content to a file is not acceptable, you will need to create a managed
implementation of the
System.Runtime.InteropServices.ComTypes.IStream interface.
For example, you can create a .NET class that inherits from
System.Runtime.InteropServices.ComTypes.IStream and
implements its methods using an instance of a managed stream,
System.IO.Stream.
The Content Management API supports IStream and ILockBytes
implementations where the input data length provided by the Stat method is not
known.
Content Management API 233
IContent :: Data

Handling items larger than 4MB prior to Enterprise Vault 8.0


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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


attempt has been made to modify this
property after the item has been
stored in the archive.

Example

C#
IContent content = itm.Content;
content.Data = “C:\\temp\\temp.msg”;
A C# implementation of IStream can be used instead:
MemoryStream itemCont = new MemoryStream();
content.Data = (IStream) new ComStreamAdaptor(itemCont);
234 Content Management API
IContent :: OriginalSize

IContent :: OriginalSize
This property returns the size of the original item, in bytes, before it was
archived.
The property is read only.

Syntax
HRESULT OriginalSize([out, retval] VARIANT* pVal);

Parameters

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the
value of this property.
The VARIANT should have been set to
VARTYPE vt = VT_R8

Remarks
This property is only available after an item has been archived.
No error will be returned if this property is called before archiving and the
returned value will be 0.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

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

IContent cont = item.Content;

object obj = content.OriginalSize;


double size = (double)obj;
Content Management API 235
IContent :: Author

IContent :: Author
This property contains the author of the item.
The property is read/write and optional.

Syntax
HRESULT Author([out, retval] BSTR* pVal);
HRESULT Author([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current value
of this property.

[in] BSTR newVal The new value of the property to be set

Remarks
This is an optional property and does not need to be populated before archiving
an item. However, once set and the item archived, an error will occur if an
attempt is made to change the value.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


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

Example

C#
[in]

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
236 Content Management API
IContent :: Author

content.Author = “Charles Dickens”


content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
item.Insert();

[out]

IItem item = cmAPI.Item;


item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ITEM_PROPERTIES);

IContent cont = item.Content;

string author = content.Author;


Content Management API 237
ArchiveMetaData object

ArchiveMetaData object
This object implements the following interfaces:
■ 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.

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.
238 Content Management API
ArchiveMetaData object

Table 4-30 IArchiveMetaData properties

Property Read/Write Description

SavesetSize Read only This property contains the saveset size (that is, the
final size of the archived item as stored on disk)
rounded to the nearest KB.

RetentionExpires Read only This property that contains the UTC date and time
that the item will be able to be deleted from the
archive.

IndexData Read only Pointer to a SimpleIndexMetaData object.


ISimpleIndexMetaData methods and properties
enable the calling application to retrieve the index
properties of an archived item, or add custom index
properties to an item as it is archived. The Search API
can be used to find items with specific index data.

IsItemSecured Read only Property that indicates that is it safe to delete the
original item from the source store. If the original item
is deleted before the archive item is secured, then the
item may not be restored as part of a disaster recovery
of the Enterprise Vault server.

CustomIdentifier Read/write This property, together with CustomQualifier can be


used to provide proprietary identity information for
the item.

CustomQualifier Read/write This property, together with CustomIdentifier can be


used to provide proprietary identity information for
the item.

CustomProperties Read/write This property can be used to hold proprietary


information about the stored item.

Table 4-31 IArchiveMetaData method

Method Description

Update Used to apply ComplianceData changes to a stored item.


Content Management API 239
ArchiveMetaData object

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.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;


240 Content Management API
IArchiveMetaData :: RetentionCategory

IArchiveMetaData :: RetentionCategory
This property contains the name or Id of the retention category assigned to the
item.
The property is read/write.

Syntax
HRESULT RetentionCategory([out, retval] BSTR* pVal);
HRESULT RetentionCategory([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR containing the current value of
this property.

[in] BSTR newVal New value to set this property to.

Remarks
An example of this would be "Business" or any other retention category created
using the Enterprise Vault Administrator Console.
The retention category Id may be specified as an alternative.
The Retention API can be used to discover or create retention categories.
See “Retention API” on page 387.
This property may be modified after the item has been archived.

Return value

S_OK Success.

S_FALSE Success. The default value (NULL) is


returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory


Service is not running.
Content Management API 241
IArchiveMetaData :: RetentionCategory

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
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

string retCat = amd.RetentionCategory;


242 Content Management API
IArchiveMetaData :: ComplianceDevice

IArchiveMetaData :: ComplianceDevice
This property indicates whether the item is stored on a compliance device on
which retention periods can be set.
The property is read only.

Syntax
HRESULT ComplianceDevice([out, retval] VARIANT_BOOL* pVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which will contain


the current value of this property

Remarks
A value of true is returned if this item is on a compliance device.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

bool compDevice = amd.ComplianceDevice;

if (conpDevice == true)
{
//do something
Content Management API 243
IArchiveMetaData :: OverrideOnHoldRetCat

IArchiveMetaData :: OverrideOnHoldRetCat
This property enables deletion of an item even if the retention category on-hold
flag is enabled.
The property is read/write.

Syntax
HRESULT OverrideOnHoldRetCat([out, retval] VARIANT_BOOL* pVal);
HRESULT OverrideOnHoldRetCat([in] VARIANT_BOOL newVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to an VARIANT_BOOL which will


contain the current value of this property

[in] VARIANT_BOOL newVal VARIANT_BOOL containing the value to be set.

Remarks
This property is set to 'true' if the item can be deleted even if the retention
category on-hold flag is set.
Once an item has been archived this property cannot be changed.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


attempt was made to modify this
property after the item had been stored
in an archive.

Example
[in]

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
244 Content Management API
IArchiveMetaData :: OverrideOnHoldRetCat

IArchiveMetaDate amd = item.ArcxhiveMetaData;


amd.OverrideOnHoldRetCat = true;
item.Insert();

[out]

IItem item = cmAPI.Item;


item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

bool override = amd. OverrideOnHoldRetCat;

if (override == true)
{
//do something
Content Management API 245
IArchiveMetaData :: ArchivedDate

IArchiveMetaData :: ArchivedDate
This property contains the UTC date and time that the item was originally
stored in the archive.
The property is read only.

Syntax
HRESULT ArchivedDate([out, retval] VARIANT* pVal);

Parameters

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived
date of this item

Remarks
This property is optional.

Version information
At Enterprise Vault 8.0, this property becomes a read/write property.
See “IArchiveMetaData2 :: ArchivedDate” on page 275.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or


the value input is not a valid date time..

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

object obj = amd.ArchivedDate;


246 Content Management API
IArchiveMetaData :: ArchivedDate

DateTime dt = (DateTime) obj;


Content Management API 247
IArchiveMetaData :: ComplianceData

IArchiveMetaData :: ComplianceData
This property returns a valid pointer to an instance of the
IComplianceDataInterface that allows the caller to set and view compliance
values for the archived item.
The property is read only.

Syntax
HRESULT ComplianceData([out, retval] IComplianceData** pVal);

Parameters

[out, retval] IComplianceData** pVal Pointer to a valid IComplianceData


pointer.

Remarks
Although this property itself is read-only, its own properties allow compliance
data to be added/modified.
The IComplianceData interface enables compliance metadata to be set on an
item in an archive.
See “ComplianceData object” on page 307.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

IComplinceData compData = amd.ComplianceData;


248 Content Management API
IArchiveMetaData :: ComplianceData

EV_STG_API_CP_UNITS evUnits = compData.Units;


object obj = compData.Value;
ulong val = (ulong)obj;
Content Management API 249
IArchiveMetaData :: SavesetSize

IArchiveMetaData :: SavesetSize
This property holds the size of the archived item saveset, rounded to the nearest
KB.
The property is read/write.

Syntax
HRESULT SavesetSize([out, retval] VARIANT* pVal);

Parameters

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the current
value of the property

Remarks
This property is only available after an item has been archived. The VARIANT
type of this property should be vt = VT_UI4.
Although it is marked as read/write, this property cannot be modified on an item
that has already been archived.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


attempt has been made to modify
this property after it has been stored
in an archive.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

object obj = amd.SavesetSize;


250 Content Management API
IArchiveMetaData :: SavesetSize

ulong size = (ulong)obj;


Content Management API 251
IArchiveMetaData :: RetentionExpires

IArchiveMetaData :: RetentionExpires
This property contains the UTC date and time when the item can be deleted
from a compliance storage device.
The property is read only.

Syntax
HRESULT RetentionExpires([out,retval] VARIANT* pVal);

Parameters

[out,retval] VARIANT* pVal Pointer to a VARIANT that will contain the current
value.

Remarks
This property value is populated when the item detail level,
DETAIL_LEVEL_COMPLIANCE_DATA, is set on the item Get method.
“EV_STG_API_ITEM_DETAIL enumeration” on page 65.
If the item is stored on a compliance device, then the property value is the UTC
date and time when the item can be deleted from the device.
If the storage device is not a compliance device, then then the property value is
30/12/1899 00:00:00, which is equivalent to an Automation date of 0.
The VARTYPE of the variant should be vt = VT_DATE.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_COMPLIANCE_DATA)));
252 Content Management API
IArchiveMetaData :: RetentionExpires

IArchiveMetaData amd = item.ArchiveMetaData;

object obj = amd.RetentionExpires;


DateTime dt = (DateTime)obj;
Content Management API 253
IArchiveMetaData :: IndexData

IArchiveMetaData :: IndexData
This property returns a pointer to a SimpleIndexMetadata object, which allows
the calling application to enumerate system and custom index properties for the
current item, and add custom index properties when the item is archived.
The property is read only.

Syntax
HRESULT IndexData([out, retval] ISimpleIndexMetadata** pVal);

Parameters

[out, retval] ISimpleIndexMetadata** pVal Pointer to a SimpleIndexMetadata object.

Remarks
The properties and methods of the ISimpleIndexMetadata interface can also be
used to add custom index data to an item as it is archived. The additional index
data is then available in the archive's index.
The Search API can be used to find items with specific index properties and
values.
For an overview of adding index properties to items, see “Adding custom index
metadata” on page 55.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or an


attempt has been made to access
this property after the item has
been archived.

Requirements
Requires KVS.EnterpriseVault.Common.dll.

Example
IArchiveMetaData amd = item.ArchiveMetaData;
254 Content Management API
IArchiveMetaData :: IndexData

ISimpleIndexMetadata simple = amd.IndexData;

See also
■ “IItem :: Get” on page 200.
■ “SimpleIndexMetadata object” on page 277.
Content Management API 255
IArchiveMetaData :: IsItemSecured

IArchiveMetaData :: IsItemSecured
This property indicates that is it safe to delete the original item from the source
store.
The property is read only.

Syntax
HRESULT IsItemSecured([out, retval] VARIANT_BOOL* pVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which contains


the current value of this property

Remarks
If the original item is deleted before the archive item is secured, then the item
may not be restored as part of a disaster recovery of the Enterprise Vault server.
The meaning of “secured” depends upon the storage device; it may mean that
the item has been backed-up, or that the storage device has replicated the item
to a duplicate device.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)(EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA)

IArchiveMetaData amd = item.ArchiveMetaData;

bool isSecured = amd.IsItemSecured;

if (isSecured == true)
256 Content Management API
IArchiveMetaData :: IsItemSecured

{
//safe to delete original item from the source
Content Management API 257
IIArchiveMetaData :: CustomIdentifier

IIArchiveMetaData :: CustomIdentifier
This property, together with the CustomQualifier property, can be used to
provide proprietary identity information for the item. For example, this
property could be used to hold the source store's identifier for the original item.
The property is read/write.

Syntax
HRESULT CustomIdentifier ([in] BSTR newVal);
HRESULT CustomIdentifier ([out, retval] BSTR* pVal);

Parameters

[in] BSTR newVal New value to set for this property.

[out, retval] BSTR* pVal Pointer to a BSTR containing the current value of this
property.

Remarks
The maximum length of this property is 255 characters.
This property is used in conjunction with the CustomQualifier property, which
defaults to zero.
It is possible to duplicate values using the CustomIdentifier/CustomQualifier
properties. To ensure uniqueness, the CustomIdentifier value should use an
application namespace, for example a GUID, as a prefix to the application
identifier. For example, <application GUID>.<application Id>.
As FSA and SharePoint Archiving use this property to hold information for
restoring items, the property value should not be changed for items archived
using FSA or SharePoint Archiving.

Return value

S_OK Success.

S_FALSE Success. The default value (NULL) is


returned.
258 Content Management API
IIArchiveMetaData :: CustomIdentifier

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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 255
characters.

Example

Visual Basic Script


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

const CUSTOM_ID = "AcmeWidgetId-00002"


const CUSTOM_QUALIFIER = 1

Dim oItem

oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID
oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES
oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER
Content Management API 259
IIArchiveMetaData :: CustomQualifier

IIArchiveMetaData :: CustomQualifier
This property, together with the CustomIdentifier property, can be used to
provide proprietary identity information for the item. For example, if different
versions of a document are archived, this property could hold the document
version information.
The property is read/write.

Syntax
HRESULT CustomQualifier ([in] LONG newVal);
HRESULT CustomQualifier ([out, retval] LONG* pVal);

Parameters

[in] LONG newVal New value to set for this property.

[out, retval] LONG* pVal Pointer to a LONG containing the current value of
this property.

Remarks
This property is used in conjunction with the CustomIdentifier property. The
property can only be set after the CustomIdentifier property has been set.
If a CustomIdentifier has been set this property defaults to zero.
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 Success. The default value (0) is


returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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 CustomIdentifier
property has not been set.
260 Content Management API
IIArchiveMetaData :: CustomQualifier

Example

Visual Basic Script


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

const CUSTOM_ID = "AcmeWidgetId-00002"


const CUSTOM_QUALIFIER = 1

Dim oItem

oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID
oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES
oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER
Content Management API 261
IIArchiveMetaData :: CustomProperties

IIArchiveMetaData :: CustomProperties
This property can be used to hold proprietary information about the stored item.
The property is read/write.

Syntax
HRESULT CustomProperties ([in] BSTR newVal);
HRESULT CustomProperties ([out, retval] BSTR* pVal);

Parameters

[in] BSTR newVal New value to set for this property.

[out, retval] BSTR* pVal Pointer to a BSTR containing the current value of
this property.

Remarks
The maximum length of this property is 2500 characters.
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 Success. The default value (NULL) is


returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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.
262 Content Management API
IIArchiveMetaData :: CustomProperties

Example

Visual Basic Script


This example shows how CustomIdentifier, CustomQualifier and
CustomProperties can be set.
const CUSTOM_PROPERTIES = "<?xml version='1.0'?><properties><key =
'1' cost='543'/></properties>"

const CUSTOM_ID = "AcmeWidgetId-00002"


const CUSTOM_QUALIFIER = 1

Dim oItem

oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID
oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER
oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES
Content Management API 263
IArchiveMetaData :: Update

IArchiveMetaData :: Update
The Update method is used to effect changes made to the ICompliance interface
by the calling application to the item stored in Enterprise Vault.

Syntax
HRESULT Update(void)

Remarks
The ArchiveId and Id properties must be set prior to calling the Update method.
The operation will only be performed if the compliance device allows it. If this is
not the case, a bad HRESULT will be returned, indicating the cause of the failure.
Note the following when extending the compliance period on an item:
■ You cannot change the compliance period if the item is stored on a device
that has no compliance period or does not support extending the
compliance period.
■ The new retention period must be longer than the original retention period.
■ You can only extend the retention period of the retention category assigned
to the item; you cannot assign a different retention category.
■ You cannot remove the compliance period completely by setting values to
"NONE”.
■ The only values that can be changed currently are the compliance unit and
value properties.
See “ComplianceData object” on page 307.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in,


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

CONTENTMANAGEMENTAPI_E_INVALID_DEVICE The storage device is not a


compliance device.
264 Content Management API
IArchiveMetaData :: Update

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or


has insufficient resource to complete
the update request, or Enterprise
Vault is currently being backed up and
is not accepting update requests. This
error indicates that the caller should
retry later.

CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have write access


to the target archive or archive folder.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_COMPLIANCE_DATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

IComplinceData compData = amd.ComplianceData;

compData.Units = EV_STG_API_CP. CP_UNITS_MONTHS;


compData.Value = 18;

amd.Update();
Content Management API 265
IArchiveMetaData2 :: CurrentLocation

IArchiveMetaData2 :: CurrentLocation
This property specifies the path of the archive folder in which the item is
currently stored, or is to be stored when performing insert, copy or move item
operations.
This property is only intended for use with structured archives, that is, archives
that contain folders.
The property is read/write.

Syntax
HRESULT CurrentLocation ([in] BSTR newVal);
HRESULT CurrentLocation ([out, retval] BSTR* pVal);

Parameters

[in] BSTR newVal Folder path to be set as the item’s current location in
the archive.

[out, retval] BSTR* pVal Archive folder path set as the item’s current location.

Remarks
The Items collection object can be used to populate this property automatically.
The property value is automatically populated by any of the following methods:
■ Insert
■ MoveTo
■ CopyTo
The folder path specifies the archive folder path relative to the root, or default,
archive folder. The following examples illustrate the default root archive folder
path used by the CurrentLocation property for the different types of archives:
■ Mailbox archives.
The CurrentLocation property value does not contain any folder path
elements for the default root archive folder.
The example value “Inbox\Accounts” represents the location of an item in
the folder “Accounts”, which is subfolder of “Inbox” archive folder.
■ Public Folder archives.
The default root archive folder path in the CurrentLocation property value
represents the location of the Exchange Public Folder archiving target.
266 Content Management API
IArchiveMetaData2 :: CurrentLocation

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.
The default root archive folder path in the CurrentLocation property value
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.
The default root archive folder path in the CurrentLocation property value
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.
Content Management API 267
IArchiveMetaData2 :: CurrentLocation

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

■ IContent::OriginalLocation

Table 4-33 Determining the target archive folder for insert, move and copy operations

ArchiveId CurrentFolderId CurrentLocation OriginalLocation Archived to Saveset


Property Property Property Property folder… OriginalLocation1

Archive Id Not specified Not specified Not specified Root folder “” (i.e. Empty string)

Archive Id Not specified Not specified Specified Folder matching Value of


CurrentLocation or OriginalLocation
OriginalLocation property
property (Folder
created as necessary
– viz current refile
behaviour)

Archive Id Not specified Specified Not specified Folder matching Value of


CurrentLocation CurrentLocation
property (Folder property
created as necessary)

Archive Id Not specified Specified Specified Folder matching Value of


CurrentLocation OriginalLocation
property (Folder property
created as necessary)

Archive ID Specified Not specified Not specified Specified folder. Path of the specified
(It must be a folder in CurrentFolderId
the archive) from the Directory

Archive ID Specified Not specified Specified Specified folder. Value of


(It must be a folder OriginalLocation
within the archive) property

Archive ID Specified Specified Irrelevant Not supported;


error with invalid
arguments 2

Archive folder ID Not specified Not specified Not specified Folder specified in Path of specified
ArchiveId property Archive folder ID
from the Directory

Archive folder ID Not specified Not specified Specified Folder specified in Value of
ArchiveId property OriginalLocation
property
Content Management API 269
IArchiveMetaData2 :: CurrentLocation

Table 4-33 Determining the target archive folder for insert, move and copy operations

ArchiveId CurrentFolderId CurrentLocation OriginalLocation Archived to Saveset


Property Property Property Property folder… OriginalLocation1

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

Archive folder ID Not specified Specified Specified Folder matching Value of


CurrentLocation OriginalLocation
property. property
(Folder created as
necessary)

Archive folder ID Specified Not specified Not specified Specified folder. Path of the specified
(It must be a folder in CurrentFolderId
the archive) from the Directory

Archive folder ID Specified Not specified Specified Specified folder. Value of


(It must be a folder in OriginalLocation
the archive) property

Archive folder ID Specified Specified Irrelevant Not supported;


error with invalid
arguments 2
1.(CopyTo and MoveTo) If OriginalLocation is not specified, then it is copied from the source item saveset value.
2.Allowed if the archive folder ID associated with the specified CurrentLocation matches the specified CurrentFolderId value.

Return value

S_OK Success.

S_FALSE Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or newVal is not a syntactically valid


folder path.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not


running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource


to complete the request. This error indicates that the caller
should retry later.
270 Content Management API
IArchiveMetaData2 :: CurrentLocation

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);
Content Management API 271
IArchiveMetaData2 :: CurrentFolderId

IArchiveMetaData2 :: CurrentFolderId
This property specifies the ID of the archive folder in which the item is currently
stored, or is to be stored when performing insert, copy or move item operations.
This property is only intended for use with structured archives, that is, archives
that contain folders.
The property is read/write.

Syntax
HRESULT CurrentFolderId ([in] BSTR newVal);
HRESULT CurrentFolderId ([out, retval] BSTR* pVal);

Parameters

[in] BSTR newVal The ID of the archive folder to set as current folder
for the item.

[out, retval] BSTR* pVal The ID of the item’s current archive folder.

Remarks
The Items collection object populates this property automatically.
The property value is automatically populated by any of the following methods:
■ IItem::Insert
■ IItem::MoveTo
■ IItem::CopyTo
For item insert, copy or move operations on structured archives, each of the
following properties can define the destination archive folder:
■ IArchiveMetaData2::CurrentLocation
■ IArchiveMetaData2:: CurrentFolderId
■ IContent::OriginalLocation
See “Which properties determine the current archive folder” on page 267.
If the CurrentFolderId property is specified for a flat archive (for example,
shared or journal archives, which do not contain folders), then the property
value is populated with the archive Id value after an Item property retrieval
operation.
272 Content Management API
IArchiveMetaData2 :: CurrentFolderId

You can use the IArchive2::HasFolders property to determine if the archive is


flat or has a folder structure.

Return value

S_OK Success.

S_FALSE Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or newVal is an not a valid archive


folder Id.

Example

C++
IItem* pItem = NULL;
pCmAPI->get_Item(&pItem);

// Identify ArchiveID of archive in which item is stored


CComBSTR ArchiveId
(L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
pItem->put_ArchiveId(ArchiveId);

// Identify Id of stored item


CComBSTR ItemId (L” 161000000000000~200501051649270000~0~9039
eb282e3d4083b79f3298dc8a1e60”)
pItem->put_Id(ItemId);

pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA );

IArchiveMetaDatat* pAMD = NULL;


pItem->get_ArchiveMetaData(&pAMD);

//Fetch the item’s current archive folder ID


CComBSTR CurrentFolderId;

CComQIPtr<IArchiveMetaData2> pAMD2(pAMD);
pAMD2->get_CurrentFolderId(&CurrentFolderId);
Content Management API 273
IArchiveMetaData2 :: SequenceNum

IArchiveMetaData2 :: SequenceNum
This property specifies the Index Sequence Number of the archived item.
The property is read only.

Syntax
HRESULT SequenceNum ([out, retval] ULONGLONG* pVal)

Parameters

[out, retval] ULONGLONG* pVal The Index Sequence Number (ISN) of the archived
item.

Remarks
This property uniquely identifies the item in the archive. It can be used to
identify the start Index Sequence Number when enumerating collections of
archived items using the Items collection object.
See “IItems :: StartSequenceNum” on page 168.
The Items collection object populatesthis property automatically. This is useful
for bulk moving or copying items.
The property value is automatically populated immediately after any of the
following operations:
■ IItem::Insert
■ IItem::MoveTo
■ IItem::CopyTo
Enterprise Vault item sequence numbers are not always consecutive, as items
may have expired or been deleted.

Requirements
Windows Server 2003 supports ULONGLONG types with OLE Automation.
However ULONGLONG types are not supported on Windows Server 2000.
.NET managed code and C++ support ULONGLONG types, but these types are
not supported by Visual Basic Script.
274 Content Management API
IArchiveMetaData2 :: SequenceNum

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example

C#
This example shows how to use the IArchiveMetaData2 interface to fetch the
SequenceNUm property.
Item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite”;

Item.Id = "200808070000000~200808070940280000~Z~BFA0C1B1FAB1468DB82
2E2473B4AAB05"

Item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA);

// Fetch the item's sequence no property


//
IArchiveMetaData2 IAMD2 = (IArchiveMetaData2)EVItem.
ArchiveMetaData;
ulong SeqNo = EVIAMD2.SequenceNum;
Content Management API 275
IArchiveMetaData2 :: ArchivedDate

IArchiveMetaData2 :: ArchivedDate
This property enables the caller to retrieve and set the original archived date
and time (UTC) for the item.
The property is read/write.

Syntax
HRESULT ArchivedDate([in] VARIANT newVal);
HRESULT ArchivedDate([out, retval] VARIANT* pVal);

Parameters

[in] VARIANT newVal The required UTC date and timeto be set for this
item

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived
date of this item

Remarks
Setting this property is optional. Typically it is only set to retain the archived
date when copying or moving items.

Note: Setting the archived date can affect the item's retention period.

To specify an ArchivedDate when storing an item, set the ArchivedDate


property value before calling the Insert method.
When copying or moving an item, the default action is to retain the item's
archived date. To reset the achived date to the current date time, simply set a
null value on the destination ArchiveMetadata object.
See “Specifying item property override values” on page 193.

Return value

S_OK Success.

S_FALSE Success. The default value (0) is


returned.
276 Content Management API
IArchiveMetaData2 :: ArchivedDate

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Supplied Variant type not VT_NULL


or VT_DATE,
or an attempt was made to modify
this property after the item had been
stored in an archive,
or pVal is NULL.

Example
IItem itemSrc = cmAPI.Item;
IItem itemDst = cmAPI.Item;
itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000ev
site”;
itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03
AE9CFB68AFE1218”;
itemDst.ArchiveMetaData.RetentionCategory = “Business”;
itemDst.ArchiveMetaData.ComplianceData.SetBy =
EV_STG_API_CP_SETBY.SETBY_RETCAT;
IArchiveMetaData2 amd =
(IArchiveMetaData2)itemDest.ArchiveMetaData;
amd.ArchivedDate = DateTime.Now();
itemSrc.CopyTo(itemDst);
Content Management API 277
SimpleIndexMetadata object

SimpleIndexMetadata object
This object implements the following interface:
■ ISimpleIndexMetadata
A SimpleIndexMetadata object is a collection of SimpleIndexProperty objects.
You can use the ISimpleIndexMetadata methods and properties to add new
custom index properties before an item is archived, and to enumerate the
individual properties that belong to an item.

Syntax
interface ISimpleIndexMetadata : IDispatch

Member summary

Table 4-34 ISimpleIndexMetadata properties

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.


278 Content Management API
SimpleIndexMetadata object

Table 4-35 ISimpleIndexMetadata methods

Method Description

ToUTCTime Converts a local system time to UTC time.

Remarks
The type of properties returned in the collection can be controlled using the
enumeration, EV_STG_API_ITEM_DETAIL, on the Get method of the IItem
interface.

Examples

C#
IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

VBScript
The following VBScript excerpt gives an example of how metadata can be read
from the instance returned by Content Management API:
' Get the Index Metadata from the retrieved item
Set IMData = oItem.ArchiveMetaData.IndexData
if (IMData.Count() = 0) then
WScript.Echo "No properties loaded!", vbOKOnly + vbExclamation,
"Index Metadata"
Err.Clear
else
'Use local system date/times
IMData.DateTimesUTC = false
' Loop through the properties displaying the details of each
Dim idxprop
for each idxprop in IMData
Dim propInfo
Dim pVal
propInfo = "Set: " + idxprop.Set + vbCrLf + "Name: " +
idxprop.Name
propInfo = propInfo + vbCrlf + "Searchable: " +
CStr(idxprop.Searchable)
propInfo = propInfo + vbCrlf + "Retrievable: " +
CStr(idxprop.Retrievable)
pVal = idxprop.Value
propInfo = propInfo + vbCrLf + "Value (" + TypeName(pVal) +
"): " + CStr(pVal)
Content Management API 279
SimpleIndexMetadata object

WScript.Echo propInfo, vbOKOnly, "Index Metadata Properties


List"
next
if (Err.number <> 0) then
WScript.Echo "Enumerating failed!" + vbCrLf + "Reason: " +
Hex(Err.number) + vbCrLf + "Description: " +
Err.Description, vbOKOnly + vbExclamation,
"Index Metadata"
Err.Clear
end if
end if

Requirements
Implemented in KVS.EnterpriseVault.Common.dll.

See also
■ “SimpleIndexProperty object” on page 293.
■ “IItem :: Get” on page 200.
280 Content Management API
ISimpleIndexMetadata :: _NewEnum

ISimpleIndexMetadata :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the SimpleIndexMetadata collection object. This property is
hidden in Visual Basic Scripting Edition (VBScript).
The property is read only.

Syntax
HRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

[out,retval] IUnknown** enumerator Returned reference to the IUnknown


interface of the object.

Remarks
This property is a standard property used to support enumerating collections, it
is automatically used internally when you use the For Each construct in C#, or
VBScript.
A collection of SimpleIndexProperty objects is returned.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;


Content Management API 281
ISimpleIndexMetadata :: _NewEnum

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


}
282 Content Management API
ISimpleIndexMetadata :: DateTimesUTC

ISimpleIndexMetadata :: DateTimesUTC
This boolean property sets or retrieves whether the date and time properties are
input and output in UTC or local system time.

Syntax
HRESULT DateTimesUTC([out, retval] VARIANT_BOOL* pRetVal);
HRESULT DateTimesUTC([in] VARIANT_BOOL pRetVal);

Parameters

[out, retval] VARIANT_BOOL* pRetVal Whether time property values are UTC
times or as local system times.

[in] VARIANT_BOOL pRetVal Whether time property values are UTC


times or as local system times.

Remarks
By default, items are always archived using UTC time.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL.

Examples
'Use local system date/times
IMData.DateTimesUTC = false
Content Management API 283
ISimpleIndexMetadata :: Count

ISimpleIndexMetadata :: Count
This method gives the number of custom index metadata properties for the
current item.

Syntax
HRESULT Count([out, retval] long* pRetVal);

Parameters

[out, retval] long* pRetVal Number of custom index metadata properties.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

if (simple.Count > 0)
{
//do something
284 Content Management API
ISimpleIndexMetadata :: Add

ISimpleIndexMetadata :: Add
This method is used to add a custom index property to an item before it is
archived. The property is then available in the index document for the item.
The Search API can be used to search for specific index data.

Syntax
HRESULT Add
[in] BSTR propertySet,
[in] BSTR propertyName,
[in] VARIANT propertyValue,
[in] VARIANT_BOOL propertySearchable,
[in] VARIANT_BOOL propertyRetrievable);

Parameters

[in] BSTR propertySet Name of the property set to which the property belongs,
or is to be added. If no property set is specified, the
property is added to the default (global) property set.

[in] BSTR propertyName Name of the property.

[in] VARIANT propertyValue Property value. A Variant containing a value of any of the
support types as follows:

Value type Variant type Note

String VT_BSTR

Datetime VT_DATE Limited to the


UTC date range
of 1st January
100 to 31st
December 2148

Integer VT_UI1, VT_UI2, Limited to the


VT_UI4, VT_UI8, range 0 to
VT_I1, VT_I2, 4,294,967,294
VT_I4, VT_I8,
VT_INT,
VT_UINT, or
VT_DECIMAL
Content Management API 285
ISimpleIndexMetadata :: Add

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

[in] VARIANT_BOOL Defines whether the property values can be requested in


propertyRetrievable search results. Setting the value to true means that
property information can be retrieved and displayed
later with the item in search results.
The default value is false.

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

Return value

S_OK Success.
286 Content Management API
ISimpleIndexMetadata :: Add

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER propertySet is NULL,


or propertyName is NULL or an
empty string,
or propertyValue is NULL or an
invalid type or is an invalid value, for
example out of supported range.

Example
item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
IArchiveMetaDate amd = item.ArcxhiveMetaData;
ISimpleIndexMetaData simple = amd.IndexData;

//add some custom index data


simple.Add(“My set”, “My name”, 32, true, true);

item.Insert();
Content Management API 287
ISimpleIndexMetadata :: Clear

ISimpleIndexMetadata :: Clear
This method is used to clear all properties from the SimpleIndexMetadata object
for the current item.

Syntax
HRESULT Clear();

Return value

S_OK Success.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;


ISimpleIndexMetadata simple = amd.IndexData;
simple.Clear();
288 Content Management API
ISimpleIndexMetadata :: ToXML

ISimpleIndexMetadata :: ToXML
This method returns the metadata in XML format.

Syntax
HRESULT ToXML(
[in] VARIANT_BOOL formattedLayout,
[out, retval] BSTR* pRetVal);

Parameters

[in] VARIANT_BOOL formattedLayout If true, the XML returned will be in


human-readable format.

[out, retval] BSTR* pRetVal An XML string is returned.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 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
Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")
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
Content Management API 289
ISimpleIndexMetadata :: ToXML

IMData.DateTimesUTC = false
‘ Add a property called Agent, with the string value,
‘ "EgApplication" to the default, global property set. This property
‘ is searchable and retrievable.
IMData.Add vbNullString, "Agent", "EgApplication",true, true

‘ Add the following properties to the property set called "EgApp".


IMData.Add "Egapp", "File", "EgFilename", false, true
IMData.Add "EgApp", "TimeStamp", CDate("2006-10-23 12:00:00"),
false, true

‘ return the property information as formatted XML


WScript.Echo IMData.ToXML(true)

oItem.Insert() // actually performs the insert


...
The ToXML method in this example would display the custom metadata as
formatted XML, as shown in Figure 4-3‚ ”ToXML result”.

Figure 4-3 ToXML result

See also
■ “ArchiveMetaData object” on page 237
290 Content Management API
ISimpleIndexMetadata :: FromXML

ISimpleIndexMetadata :: FromXML
This method enables you to load a set of properties that have previously been
defined and stored using the ToXML method.

Syntax
HRESULT FromXML([in] BSTR xmlIndexMetadata);

Parameters

[in] BSTR xmlIndexMetadata The XML stream to input.

Remarks
Use the Add method to add item specific values.
The XML schema is not published, as the Add method should always be used to
add metadata properties.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER xmlIndexMetadata supplied as


NULL, or is invalid XML.

Example
item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);
IContent content = item.Content;
content.Title = "New title";
content.FileExtension = "msg";
content.OriginalLocation = “Inbox”;
content.Data = "C:\\temp\\test.msg";
IArchiveMetaDate amd = item.ArcxhiveMetaData;
ISimpleIndexMetaData simple = amd.IndexData;

//add some custom index data from xml


simple. FromXML(xmlData); //xmlData is a pre-populated string
containing the xml
item.Insert();
Content Management API 291
ISimpleIndexMetadata :: ToLocalTime

ISimpleIndexMetadata :: ToLocalTime
This is a helper method to convert a UTC time to local system time.

Syntax
HRESULT ToLocalTime(
[in] DATE utcDateTime,
[out, retval] DATE* pRetVal);

Parameters

[in] DATE utcDateTime The UTC date and time to convert.

[out, retval] DATE* pRetVal The local date and time are returned.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL,


or utcDateTime is not a syntactically
valid UTC date time value.
292 Content Management API
ISimpleIndexMetadata :: ToUTCTime

ISimpleIndexMetadata :: ToUTCTime
This is a helper method to convert a local system time to UTC date and time.

Syntax
HRESULT ToUTCTime(
[in] DATE localDateTime,
[out, retval] DATE* pRetVal);

Parameters

[in] DATE localDateTime The local date and time to convert.

[out, retval] DATE* pRetVal The local date and time are returned.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL,


or localDateTime is not a
syntactically valid local date time
value.
Content Management API 293
SimpleIndexProperty object

SimpleIndexProperty object
The SimpleIndexProperty object implements the following interface:
■ ISimpleIndexProperty

Syntax
interface ISimpleIndexProperty : IDispatch

Member summary
This read-only interface has the following properties defined:

Table 4-36 ISimpleIndexProperty properties

Parameter Read/Write Description

Set Read only Name of the property set.

Name Read only Name of the property.

Value Read only Value assigned to the property.

Searchable Read only Whether the property is to be added to the item


index.

Retrievable Read only Whether the property can be included in search


results.

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


default during the archiving process.

Remarks
Properties added to the item index using the Add method of the
ISimpleIndexMetadata interface are held as SimpleIndexProperty objects.

Example
IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

foreach (ISimpleIndexProperty ip in simple)


{
294 Content Management API
ISimpleIndexProperty :: Set

ISimpleIndexProperty :: Set
This property returns the property set name.
The property is read only.

Syntax
HRESULT Set([out, retval] BSTR* value);

Parameters

[out, retval] BSTR* value Property set name.

Remarks
If empty, the property is a member of the global property set.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

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;
Content Management API 295
ISimpleIndexProperty :: Set

//do something with the values obtained


}
296 Content Management API
ISimpleIndexProperty :: Name

ISimpleIndexProperty :: Name
This property returns the property name.
The property is read only.

Syntax
HRESULT Name([out,retval] BSTR* value);

Parameters

[out,retval] BSTR* value Name of the property.

Remarks
The name of a property can be a predefined name, such as IndexPropSUBJ, the
numeric identification of an attachment (for example, 1.1), or a custom name.
If the value is a formatted number (1, 1.1, 1.2 and so on), then the property refers
to a message attachment, which may be a file or a message. In this case, the
value is another instance of a SimpleIndexMetadata object, detailing the index
properties of the attachment.
If the property is a top-level message, then the Name is “1”. The first attachment
would be “1.1”. The first attachment on a nested message would be “1.1.1”.
Figure 4-4 illustrates the naming convention for messages and attachments.

Figure 4-4 Naming format for messages

Top-level message

Message Attachments

1.1 1.2 1.3

1.1.2 1.2.1
1.1.1

1.2.1.1
Content Management API 297
ISimpleIndexProperty :: Name

Each of the nested items has their own set of properties, which can be
enumerated.
The property, IndexPropANUM, also contains the numeric identity of a message
attachment. The value of this property differs from the property Name.
Figure 4-5 shows the values of IndexPropANUM for a message with an attached
document and an attached message, which also has attached documents.

Figure 4-5 Example values of IndexPropANUM

Top-level message

anum=0

Message attachments

anum=1 anum=4 anum=7

anum
anum=2 =3 anum=5

anum=6

If content items are missing, the COMR (content missing) property is returned in
the index data. The value of this property indicates the reason for the missing
content. For predefined values for this property, see “Note 4” on page 677.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive


property value.

Version information
■ Numeric identity of a message attachments in IndexPropANUM is available
in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise
Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on
page 31.
298 Content Management API
ISimpleIndexProperty :: Name

■ Content missing reasons returned in the index data COMR property is


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

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

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


}

See also
■ “System properties” on page 664.
Content Management API 299
ISimpleIndexProperty :: Value

ISimpleIndexProperty :: Value
This property returns the property value.
The property is read only.

Syntax
HRESULT Value([out,retval] VARIANT* value);

Parameters

[out,retval] VARIANT* value Property value. A Variant containing a value of any of


the support types as follows:

Value type Variant type Note

String VT_BSTR

Datetime VT_DATE Limited to the


UTC date range of
1st January 100 to
31st December
2148

Integer VT_UI1, Limited to the


VT_UI2, range 0 to
VT_UI4, 4,294,967,294
VT_UI8, VT_I1,
VT_I2, VT_I4,
VT_I8, VT_INT,
VT_UINT, or
VT_DECIMAL

SimpleIndexMeta VT_UNKNOWN An
data object ISimpleIndexProp
erty instance

Remarks
If the Name property is a formatted number (1.1, 1.2 and so on), then the
property refers to a message attachment, which may be a file or a message. In
this case, the Value property is a SimpleIndexMetadata object, detailing the
index properties of the attachment.
300 Content Management API
ISimpleIndexProperty :: Value

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

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


}
Content Management API 301
ISimpleIndexProperty :: Searchable

ISimpleIndexProperty :: Searchable
This property returns whether the property is indexed, and hence can be
searched for using the Search API.
The property is read only.

Syntax
HRESULT Searchable([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

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


}
302 Content Management API
ISimpleIndexProperty :: Searchable

See also
■ “System properties” on page 664.
Content Management API 303
ISimpleIndexProperty :: Retrievable

ISimpleIndexProperty :: Retrievable
This property returns whether the property can be retrieved and displayed with
search results in the search application.
The property is read only.

Syntax
HRESULT Retrievable([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) |
(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

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


}
304 Content Management API
ISimpleIndexProperty :: Retrievable

See also
■ “System properties” on page 664.
Content Management API 305
ISimpleIndexProperty :: System

ISimpleIndexProperty :: System
This property indicates that the property is an Enterprise Vault system
property.
See “System properties” on page 664.
The property is read only.

Syntax
HRESULT System([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value

Remarks
For custom properties that are added using Add, the value of System is always
false.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)((EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA) |
(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA) |
(EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_SYSTEM_INDEXDATA)));

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

foreach (ISimpleIndexProperty ip in simple)


{
306 Content Management API
ISimpleIndexProperty :: System

string set = ip.Set;


string name = ip.Name;
object val = ip.Value;
bool searchable = ip.Searchable;
bool retrievable = ip.Retrievable;
bool isSystem = ip.System;

//do something with the values obtained


}

See also
■ “System properties” on page 664.
Content Management API 307
ComplianceData object

ComplianceData object
This object implements the following interface:
■ IComplianceData
The IComplianceData interface is obtained by using the ComplianceData
property of the IArchiveMetaData interface.

Syntax
interface IComplianceData : IDispatch

Remarks
The IComplianceData interface is for use only with compliance devices.

Member summary

Table 4-37 IComplianceData properties

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
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;


IComplinceData compData = amd.ComplianceData;
308 Content Management API
IComplianceData :: Units

IComplianceData :: Units
This property, combined with the Value property, specifies the duration of the
compliance period.
The property is read/write.

Syntax
HRESULT Units([out, retval] EV_STG_API_CP_UNITS* pVal);
HRESULT Units([in] EV_STG_API_CP_UNITS newVal);

Parameters

[out, retval] EV_STG_API_CP_UNITS* pVal Pointer an EV_STG_API_CP_UNITS


enumerated type that contains the
current value of this property

[in] EV_STG_API_CP_UNITS newVal The new value to be set.

Remarks
EV_STG_API_CP_UNITS indicates the units used in specifying the compliance
period.
See “EV_STG_API_CP_UNITS enumeration” on page 62.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or the


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

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;


Content Management API 309
IComplianceData :: Units

IComplinceData compData = amd.ComplianceData;

EV_STG_API_CP_UNITS evUnits = compData.Units;


object obj = compData.Value;
ulong val = (ulong)obj;
310 Content Management API
IComplianceData :: Value

IComplianceData :: Value
This property, combined with the Units property, specifies the duration of the
compliance period.
The property is read/write.

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.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or newVal is invalid.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL.
DETAIL_LEVEL_ARCHIVE_METADATA);

IArchiveMetaData amd = item.ArchiveMetaData;

IComplinceData compData = amd.ComplianceData;


Content Management API 311
IComplianceData :: Value

EV_STG_API_CP_UNITS evUnits = compData.Units;


object obj = compData.Value;
ulong val = (ulong)obj;
312 Content Management API
IComplianceData :: SetBy

IComplianceData :: SetBy
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 61.
This property should only be used during a copy/move operation and should not
be called once an item has added to the archive.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Invalid pointer passed to receive


property value,
or the value passed in does not
conform to one of the enumeration
type values.
Content Management API 313
Holds object

Holds object
This object implements the following interfaces:
■ IHolds
■ IHolds2
These interfaces enable calling applications to place holds on groups of items (to
prevent them from being deleted), remove existing holds and list the holds that
have been placed on items in a vault store.
The IHolds2 interface inherits from IHolds, and provides the method
ReleaseHolds2, which returns information in XML about the success or failure
of removing holds on items in each vault store.

Syntax
interface IHolds : IDispatch
interface IHolds2 : IHolds

About Legal Hold


Legal Hold is the ability to prevent deletion of documents that are relevant to a
legal case; items that are placed on hold cannot be deleted by a user or by
Enterprise Vault (using storage expiry).
Legal Hold functionality is provided by the IHolds and IHold interfaces in the
Content Management API. These interfaces allow Enterprise Vault Accelerator
products and third-party applications to put items on hold, remove holds from
items and enumerate all existing holds on an item.
Existing functionality in Discovery Accelerator allows the administrator to put
items on hold.
Items can be placed on hold by specifying the following:
■ A Consumer ID, to identify the calling application.
■ A Group ID, to identify the group of items with a particular hold applied.
The Group ID could, for example, identify the legal case.
■ Metadata, to provide additional information about the hold.
■ The list of items that the calling application wants to place on hold.
314 Content Management API
Holds object

The metadata may be useful when there are several consumers of the Legal Hold
API at the same time. For example, metadata could be used to say why one
consumer has put the item on hold, and this information could then be accessed
by other consumers. The metadata is in XML format, for example:
<MetaData>
<Reason Value="John Doe against EG Corp" />
</MetaData>
Using the IItem.Holds property, an application can enumerate all the holds
which have been placed on an item; the API returns a list of holds (Hold IDs) on
that item along with the metadata that was supplied when the item was put on
hold.
Holds may be removed from items in two ways:
■ By specifying the Consumer ID and the Group ID. This will remove all holds
which have been placed on an item with the supplied Consumer ID and
Group ID.
■ By supplying the Consumer ID and a list of Hold IDs of items from which the
consumer wants to remove holds. This allows the consumer to remove
holds from items in batches rather than a whole group at once.

Member summary

Table 4-38 IHolds Properties

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.
Content Management API 315
Holds object

Table 4-38 IHolds Properties

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-39 IHolds Methods

Method Description

Add Adds an IHold interface pointer to the collection.

PlaceHolds Places a hold on each item in the collection.

ReleaseHolds Releases a hold on each item in the collection.

Table 4-40 IHolds2 Method

Method Description

ReleaseHolds2 Releases a hold on each item in the collection, and returns success
or failure information, in XML format, for each vault store
processed.

Version information
IHolds2 interface requires Enterprise Vault 8.0 SP1.

See also
“Hold object” on page 332
316 Content Management API
IHolds :: _NewEnum

IHolds :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the IHolds collection object. This property is hidden in Visual
Basic Scripting Edition (VBScript).
The property is read only.

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 IHold objects is returned.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive


property value.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA);

IHolds holds = Item.Holds;

foreach (IHold hold in holds)


{
Content Management API 317
IHolds :: Item

IHolds :: Item
This property gives access to a particular hold in a collection.
The property is read/write.

Syntax
HRESULT Item([in] VARIANT index;
HRESULT Item([out, retval] LPVARIANT pRetVal);

Parameters

[in] VARIANT index VARIANT holding the value of the index of the
required hold.

[out, retval] LPVARIANT pRetVal Pointer to a VARIANT that will return the
current index value.

Remarks
The VARTPYE of this property should be vt = VT_I4.
Note that the index supplied to the property is 1-based not 0-based.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL,


or data type of variant was incorrect,
or index is out of range.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA);

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);
318 Content Management API
IHolds :: Count

IHolds :: Count
This read only property returns the number of Holds in the collection.
The property is read only.

Syntax
HRESULT Count([out, retval] long* pRetVal);

Parameters

[out, retval] long* pRetVal Current number of holds in the collection.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL.

Example
IItem item = cmAPI.Item;
item.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
item.Id = “200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA);

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);
Content Management API 319
IHolds :: GroupId

IHolds :: GroupId
This property is set to identify a group of holds placed at one time. This would
typically be an identifier of a particular legal case, for example.
The property is read/write.

Syntax
HRESULT GroupId([in] BSTR newVal);
HRESULT GroupId([out,retval] BSTR* pVal);

Parameters

[in] BSTR newVal BSTR containing the new group Id.

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the current group Id.

Remarks
The same GroupId used to place holds can also used to release all the holds in
that group.
A GroupId should consist of printable characters and should not contain any of
the following characters: <> & ' "

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or newVal contains invalid
characters,
or one or more holds have already
been placed for the current group.

Example
IHolds holds = cmAPI.Holds;

holds.GroupId = “Group 1”;


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

IHold hold = cmAPI.Hold;


320 Content Management API
IHolds :: GroupId

hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);

//add more hold’s if necessary

holds.PlaceHolds();
Content Management API 321
IHolds :: ConsumerGUID

IHolds :: ConsumerGUID
This property is the unique identifier of the application calling the API.
The property is read only.

Syntax
HRESULT ConsumerGUID([in] BSTR newVal);
HRESULT ConsumerGUID([out,retval] BSTR* pVal);

Parameters

[in] BSTR newVal BSTR containing any valid GUID value. Set by caller.

[out,retval] BSTR* pVal Pointer to a BSTR containing the current GUID

Remarks
The value should remain the same for all calls made to the ContentManagement
API by the same calling application.
It must be set before holds can be placed or released.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER PlaceHolds has been called so it is not


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

Example
IHolds holds = cmAPI.Holds;

holds.GroupId = “Group 1”;


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

IHold hold = cmAPI.Hold;


hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
322 Content Management API
IHolds :: ConsumerGUID

holds.Add(hold);

//add more hold’s if necessary

holds.PlaceHolds();
Content Management API 323
IHolds :: Metadata

IHolds :: Metadata
This property contains the metadata to be passed with the holds to the
Enterprise Vault server.
The property is read/write.

Syntax
HRESULT Metadata([in] BSTR newVal);
HRESULT Metadata([out,retval] BSTR* pVal);

Parameters

[in] BSTR newVal BSTR containing the new MetaData value.

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the current value
of the metadata.

Remarks
The same metadata will be applied to each hold in the group.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER An attempt was made to modify this


property once the PlaceHolds had
been called.

Example
IHolds holds = cmAPI.Holds;

holds.GroupId = “Group 1”;


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

IHold hold = cmAPI.Hold;


hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
324 Content Management API
IHolds :: Metadata

//add more hold’s if necessary

holds.PlaceHolds();
Content Management API 325
IHolds :: Add

IHolds :: Add
This method allows a client to add a new hold to the collection.

Syntax
HRESULT Add([in] IHold* newHold);

Parameters

.[in] IHold* newHold IHold interface pointer to add to the collection.

Remarks
The IHold interface pointer must be obtained through the
IContentManagementAPI property, Hold.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Hold object has been used,


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

Example
IHolds holds = cmAPI.Holds;

holds.GroupId = “Group 1”;


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

IHold hold = cmAPI.Hold;


hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);

//add more hold’s if necessary

holds.PlaceHolds();
326 Content Management API
IHolds :: PlaceHolds

IHolds :: PlaceHolds
This function is used to actually place a hold on each item in the collection.

Syntax
HRESULT PlaceHolds();

Remarks
After the call has been placed, any errors in placing holds are reported in the
Status property of the hold objects in the collection.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed to


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or


has insufficient resource to complete
the request. This error indicates that
the caller should retry later.

Example
IHolds holds = cmAPI.Holds;

holds.GroupId = “Group 1”;


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

IHold hold = cmAPI.Hold;


hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);

//add more hold’s if necessary


Content Management API 327
IHolds :: PlaceHolds

holds.PlaceHolds();
328 Content Management API
IHolds :: ReleaseHolds

IHolds :: ReleaseHolds
This function is used to release a hold on each item in the collection.

Syntax
HRESULT ReleaseHolds();

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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointerhas been passed to


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.
Content Management API 329
IHolds :: ReleaseHolds

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or


has insufficient resource to complete
the request. This error indicates that
the caller should retry later.

Example
cmAPI.DirectoryDNSAlias = “SERVER1”;

IHolds holds = cmAPI.Holds;


holds.GroupId = “Group 1”;
holds.ConsumerGUID = “{1D938946-329D-4bfa-87FF-9D30B808ADD1}”;
holds.ReleaseHolds();
330 Content Management API
IHolds2 :: ReleaseHolds2

IHolds2 :: ReleaseHolds2
This method is similar to ReleaseHolds, in that it can be used to release a hold on
each item in a collection, but this method also returns a summary status report,
in XML, for each vault store in which items were processed.

Syntax
HRESULT ReleaseHolds2([out, retval] BSTR* pVal);

Parameters

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the status report
in XML.

Remarks
The IContentManagementAPI :: DirectoryDNSAlias property should be set by
the caller before releasing holds by GroupId. This is required to identify the
Enterprise Vault server hosting the directory that will be used to enumerate the
Enterprise Vault Storage service computers that the group of holds spans.
When using a GroupId, if any of the holds in the group fail to be released, then
the whole group is considered to have failed.
Note that some holds may actually have been released, but the caller will need to
repeat the release on the group as whole until it succeeds, after establishing the
reason for failure and correcting it.
When not using a GroupId, if the holds are spread over multiple vault stores,
and any of the holds within a vault store fails to be released, all the holds in the
vault store will also be marked as failed.
Finally, when all holds in a group are eventually released, then to dispose of the
group itself, you must also call ReleaseHolds2( ) specifying the GroupId as
before.
The XML returned by the method indicates the success or failure of the action
for each vault store as a whole. In the XML, the vault store is identified by the Id
field, and success or failure of the operation is indicated by the hr field
(HRESULT). If the hold was released successfully on all affected items in a vault
store, then the HRESULT returned for the vault store is 0. If the hold could not
be released on some or all of the affected items in the vault store, then the hr
field contains the error code value.
Content Management API 331
IHolds2 :: ReleaseHolds2

Version information
ReleaseHolds2 method requires Enterprise Vault 8.0 SP1.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointerhas been passed to


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or


has insufficient resource to complete
the request. This error indicates that
the caller should retry later.

Example
cmAPI.DirectoryDNSAlias = “SERVER1”;

IHolds2 holds = (IHolds2)cmAPI.Holds;


holds2.GroupId = “Group 1”;
holds2.ConsumerGUID = “{1D938946-329D-4bfa-87FF-9D30B808ADD1}”;
string xml holds2.ReleaseHolds2();
The following example shows XML returned by ReleaseHolds2. The HRESULT
returned for the second vault store is not zero, indicating that the attempt to
release the hold on items in this vault store failed.
<VaultStores>
<VaultStore Id="16918E349851B39307B57E2FC4603DDB2121
0000VS2.eg.com" hr="0"/>
<VaultStore Id="157E2F1B39307B86918E3498C4603DDB2121
0000VS2.eg.com" hr="0x80040300"/>
<VaultStore Id="1B39307B86918E3498557E2FC4603DDB2121
0000VS.eg.com" hr="0"/>
</VaultStores>
332 Content Management API
Hold object

Hold object
This object implements the following interface:
■ IHold
The IHold interface contains properties that relate to a particular hold placed on
a particular item. It is a collection of IHold interface pointers that are stored in
the IHolds collection.

Syntax
interface IHold : IDispatch

Member summary

Table 4-41 IHold properties

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.

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.
Content Management API 333
Hold object

Example
IHold hold = cmAPI.Hold;
hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
334 Content Management API
IHold :: ArchiveId

IHold :: ArchiveId
This property specifies the ArchiveID of the archive where the item that this
hold object refers to is stored.
The property is read/write.

Syntax
HRESULT ArchiveId([out, retval] BSTR* pVal);
HRESULT ArchiveId([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the archive Id of
the archive holding the item referred to by this hold.

[in] BSTR newVal BSTR containing the value of the archive Id where
the current item, to which this hold is about to be
applied, is stored.

Remarks
This property must be set before a hold is placed or released.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or the value is not a syntactically
valid Archive Id.

Example
[in]

IHold hold = cmAPI.Hold;


hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
Content Management API 335
IHold :: ArchiveId

[out]

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);

string archId = hold.ArchiveId;


336 Content Management API
IHold :: ItemId

IHold :: ItemId
This property specifies the identifier of the item to which the hold object refers.
The property is read/write.

Syntax
HRESULT ItemId([out, retval] BSTR* pVal);
HRESULT ItemId([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current
item Id held by this hold.

[in] BSTR newVal BSTR containing the item Id to set for this hold.

Remarks
This property must be set before a hold is placed.
The identifier can be a Saveset Id or a Transaction Id.
See “Saveset IDs and Transaction IDs” on page 54.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


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

Example
[in]

IHold hold = cmAPI.Hold;


hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.ItemId =
200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;
holds.Add(hold);
Content Management API 337
IHold :: ItemId

[out]

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);

string itemID = hold.ItemId;


338 Content Management API
IHold :: Id

IHold :: Id
This property identifies the hold object.
The property is read/write.

Syntax
HRESULT Id([out, retval] BSTR* pVal);
HRESULT Id([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current hold Id.

[in] BSTR newVal BSTR that will contain the new value of the hold Id.

Remarks
The maximum length for this property is 128 characters.
This property is returned after a hold has been placed, and must be set before a
hold can be released.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or newVal is not a syntactically valid
Hold Id.

Example
[in]

IHolds holds = cmAPI.Holds;

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

IHold hold = cmAPI.Hold;

hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;
hold.Id = 123;
Content Management API 339
IHold :: Id

holds.Add(hold);

//add more holds

holds.ReleaseHolds;

[out]

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);

string ID = hold.Id;
340 Content Management API
IHold :: Status

IHold :: Status
This property returns the status of the hold after an attempt to either place or
release a hold.
The property is read only.

Syntax
HRESULT Status([out, retval] VARIANT* pVal);

Parameters

[out, retval] VARIANT* pVal 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.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.


Content Management API 341
IHold :: Metadata

IHold :: Metadata
This property returns the metadata that is stored with the hold.
The property is read only.

Syntax
HRESULT Metadata([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the metadata for this
hold.

Remarks
This property is only populated when the IItem.Get method is called and the
DetailLevel parameter includes the HoldData bit.
See “IItem :: Get” on page 200.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example
IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);

string metadata = hold.MetaData;


342 Content Management API
IHold :: ConsumerGUID

IHold :: ConsumerGUID
This property returns the unique identifier of the calling application that placed
the hold.
The property is read only.

Syntax
HRESULT ConsumerGUID([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the consumer GUID
of the application that placed the hold.

Remarks
The format of the consumer GUID should be as in the following example:
{3BC4797A-3238-478b-9CA6-5CC9989078DE}
Any other format will generate an error.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,


or pVal is not a valid GUID.

Example
IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);

string conGUID = hold.ConsumerGUID;


Content Management API 343
IHold :: GroupId

IHold :: GroupId
This property returns the identifier of the group of holds to which the hold
belongs.
The property is read only.

Syntax
HRESULT GroupId([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the current group Id.

Remarks
See “IHolds :: GroupId” on page 319.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Example
IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++)


{
IHold hold = (IHold)holds.Item(i + 1);

string groupID = hold.GroupId;


344 Content Management API
ICollectionBase : IDispatch

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

Syntax
interface ICollectionBase : IDispatch

Member summary

Table 4-42 ICollectionBase properties

Property Read/Write Description

Count Read only Number of items in the collection.

_NewEnum Read only Instance of the standard COM enumerator for


the collection.

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


into the collection.

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

More Read only Whether or not there were more items than
Maximum.

Table 4-43 ICollectionBase methods

Method Description

Get Populate the collection.

Clear Clear the current collection.

Reset Reset the object back to the initial state.

Version information
■ This interface is available in Enterprise Vault 2007 or later.
Content Management API 345
ICollectionBase :: Count

ICollectionBase :: Count
This property returns the current number of items in the collection.
The property is read only.

Syntax
HRESULT Count([out,retval] long* value);

Parameters

[out,retval] long* value Number of items in the collection.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL.

Example

C#
archives.Get();
for (long i = 0; i < archives.Count; i++)
{
ProcessArchive(archives.Item(i));
346 Content Management API
ICollectionBase :: _NewEnum

ICollectionBase :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the collection object. This property is hidden in Visual Basic
Scripting Edition (VBScript).
The property is read only.

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.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER enumerator is NULL.

Example

C#
archives.Get();
foreach (IArchive archive in archives)
{
SearchArchive(archive.Id);
Content Management API 347
ICollectionBase :: Item

ICollectionBase :: Item
This property returns an instance of the item at the zero-based index into the
collection treated as a virtual array.
The property is read only.

Syntax
HRESULT Item([in] long index, [out,retval] IUnknown** item);

Parameters

[in] long index Zero-based index.

[out,retval] IUnknown** item Reference to an instance of the collection.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER item is NULL, or index is invalid.

Example

C#
archives.Get();
for (long i = 0; i < archives.Count; i++)
{
IArchive archive = (IArchive)archives.Item(i);
SearchArchive(archive.Id);
348 Content Management API
ICollectionBase :: Maximum

ICollectionBase :: Maximum
This property sets the maximum number of items for the collection.
The property is read/write.

Syntax
HRESULT Maximum([out,retval] long* value);
HRESULT Maximum([in] long value);

Parameters

[out,retval] long* value Maximum number of items in the collection.

[in] long value Required maximum number of items for the


collection.

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

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL, or value is invalid.


Content Management API 349
ICollectionBase :: Maximum

Example

C#
archives.Maximum = 6000;
archives.Get();
350 Content Management API
ICollectionBase :: More

ICollectionBase :: More
This property indicates whether there were more items available in the
collection than specified by Maximum.
The property is read only.

Syntax
HRESULT More([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain


true, if there are more items in the collection
than the Maximum number specified. Otherwise
it will contain false.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL.

Example

C#
archives.Maximum = 6000;

archives.Get();

if (archives.More == true)
{
//do something,
Content Management API 351
ICollectionBase :: Get

ICollectionBase :: Get
This method populates the collection with items that match the selection
criteria up to the maximum number of items specified by Maximum.

Syntax
HRESULT Get(void);

Remarks
Any existing collection is cleared prior to attempting to repopulate the
collection.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The combination of properties used for


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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or


Storage services are 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, if there
are insufficient resources the
maximum number of records
requested should be reduced.

Example

C#
archives.Computer = ""EV1.acme.com";
archives.Permissions =
EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;
archives.ArchiveTypes =
EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_SHARED;
352 Content Management API
ICollectionBase :: Get

archives.Get();
Content Management API 353
ICollectionBase :: Clear

ICollectionBase :: Clear
This method clears the current collection.

Syntax
HRESULT Clear(void);

Remarks
Clears all items from the current collection setting it back to the empty state;
Count returns zero.

Return value

S_OK Success.

Example

C#
archives.Get();
for (long i = 0; i < archives.Count; i++)
{
ProcessArchive(archives.Item(i));
}

//now clear archives before doing another get with different filters
set
archives.Clear();
354 Content Management API
ICollectionBase :: Reset

ICollectionBase :: Reset
This method resets the collection back to the initial empty state.

Syntax
HRESULT Reset(void);

Remarks
All items are cleared from the current collection, if any, and all selection criteria
properties are reset back to their default empty values.

Return value

S_OK Success.

Examples

C#
archives.Get();
for (long i = 0; i < archives.Count; i++)
{
ProcessArchive(archives.Item(i));
}

//now reset archives before doing another get with different filters
set
archives.Reset();
Content Management API 355
ExtendedErrorInfo object

ExtendedErrorInfo object
This object implements the following interface:
■ IExtendedErrorInfo
This interface makes available properties that provide additional details about
the return value of the most recent call to a child object of the parent Content
Management API object instance.

Syntax
interface IExtendedErrorInfo : IDispatch

Member summary

Table 4-44 IExtendedErrorInfo properties

Property Read/Write Description

Error Read only The Content Management API return


value associated with the most recent
call to a Content Management API
method.

Description Read only The description for the Content


Management API return value.

InnerError Read only The associated internal return value.

InnerErrorDescription Read only The description for the internal return


value.

Source Read only This property is not currently


implemented.

Remarks
The ExtendedErrorInfo object is read-only, and is not updated by any
subsequent Content Management API call — a new instance of the
ExtendedErrorInfo object must be requested from the Content Management API
object.
The inner error can be any Windows or Enterprise Vault COM return value. It is
provided for additional information only; for example, to add to extended
logging details. The list of values is not documented, and it is not guaranteed
356 Content Management API
ExtendedErrorInfo object

that the same error scenario will return the same inner error value with future
versions of Enterprise Vault.

Version information
■ This interface is available from Enterprise Vault 8.0 SP2.

Examples
In the following example, the additional information returned by the
IExtendedErrorInfo interface shows that the Enterprise Vault server is in
Backup Mode:

API Error Code:


0x80040302 (Ref: CONTENTMANAGEMENTAPI_E_BUSY)

API Error Description:


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

EV Internal Error Code:


0xC0041B85 (Ref STORAGE_E_VAULTSTORE_INBACKUPMODE)

EV Internal Error Description:


The Vault Store is currently in Backup Mode.

C++ example
The following example code shows how the ExtendedErrorInfo object is used.

CComPtr<IContentManagementAPI4> pCMAPI;

CComPtr<IItem> pItem;

HRESULT hr = pItem->CopyTo(pDestItem);

if (FAILED(hr))
{
HRESULT hrGLE (S_OK);
CComPtr<IUnknown> pIUnkErrInfo;

hrGLE = pCMAPI->get_LastError(&pIUnkErrInfo);

if (SUCCEEDED(hrGLE))
{
CComQIPtr<IExtendedErrorInfo> pExtErrInfo(pIUnkErrInfo);
Content Management API 357
ExtendedErrorInfo object

if (pExErrInfo != NULL)

HRESULT hrError = S_OK;


HRESULT hrInnerError = S_OK;
CComBSTR bsErrorDesc;
CComBSTR bsInnerErrorDesc;

pExErrInfo->get_Error(&hrError);
pExErrInfo->get_InnerError(&hrInnerError);
pExErrInfo->get_Description(&bsErrorDesc);
pExErrInfo->get_InnerErrorDescription(&bsInnerErrorDesc);

// *** Use error info


AddExtendedErrorToLogFile(L"Failed to copy archived
item", hrError, bsErrorDesc, hrInnerError,
bsInnerErrorDesc);
}

}
}

VBScript example
The following example code shows how the ExtendedErrorInfo object is used.

private Sub ReportCMAPIError(byref ecmAPI)

dim oExtErr
dim szErrorDesc, szInnerErrorDesc
dim vbError, vbExtError
dim Msg

Err.Clear

set oExtErr = ecmAPI.LastError

vbError = oExtErr.Error

vbExtError = oExtErr.InnerError

szErrorDesc = oExtErr.Description

szInnerErrorDesc = oExtErr.InnerErrorDescription

Msg = "***************************" & vbCrLf & vbCrLf


Msg = Msg & "** CM API EXTENDED ERROR INFO" & vbCrLf & vbCrLf
Msg = Msg & " Error Code: 0x" & Hex(vbError) & vbCrLf & vbCrLf
358 Content Management API
ExtendedErrorInfo object

Msg = Msg & " Error Description: " & szErrorDesc & vbCrLf &
vbCrLf
Msg = Msg & " InnerError Code: 0x" & Hex(vbExtError) & vbCrLf &
vbCrLf
Msg = Msg & " InnerError Description: " & szInnerErrorDesc &
vbCrLf & vbCrLf
Msg = Msg & "***************************"

WScript.Echo Msg
Err.Clear
end sub
Content Management API 359
IExtendedErrorInfo :: Error

IExtendedErrorInfo :: Error
This property provides the Content Management API return value associated
with the most recent call to a Content Management API method.
This property is read only.

Syntax
HRESULT Error([out, retval] long* pVal);

Parameters

[out,retval] long* pVal Pointer to a long data type containing the Content
Management API return value.

Remarks
For a list of the return values, see “Content Management API return values” on
page 685.

Return value

S_OK Success.

E_INVALIDARG pVal is Null.


360 Content Management API
IExtendedErrorInfo :: Description

IExtendedErrorInfo :: Description
This property provides the error description for the Content Management API
return value.
This property is read only.

Syntax
HRESULT Description([out, retval] BSTR* pVal);

Parameters

[out,retval] BSTR* pVal Pointer to a BSTR containing the error description.

Remarks
The error description strings are supplied in English only.

Return value

S_OK Success.

E_INVALIDARG pVal is Null


Content Management API 361
IExtendedErrorInfo :: InnerError

IExtendedErrorInfo :: InnerError
This property provides the internal return value associated with the most recent
call to a Content Management API method.
This property is read only.

Syntax
HRESULT InnerError([out, retval] long* pVal);

Parameters

[out,retval] long* pVal Pointer to a long data type containing the internal return
value.

Remarks
The inner error can be any Windows or Enterprise Vault COM return value. It is
provided for additional information only, for example, to add to extended
logging details.
The list of values is not documented, and it is not guaranteed that the same
error scenario will return the same inner error value with future versions of
Enterprise Vault.

Return value

S_OK Success.

E_INVALIDARG pVal is Null


362 Content Management API
IExtendedErrorInfo :: InnerErrorDescription

IExtendedErrorInfo :: InnerErrorDescription
This property provides the error description for the Enterprise Vault internal
return value.
This property is read only.

Syntax
HRESULT InnerErrorDescription([out, retval] BSTR* pVal);

Parameters

[out,retval] BSTR* pVal Pointer to a BSTR containing the error description.

Remarks
The error description strings are supplied in English only.

Return value

S_OK Success.

E_INVALIDARG pVal is Null


Content Management API 363
IExtendedErrorInfo :: Source

IExtendedErrorInfo :: Source
This property provides the GUID of the Content Management API object that
was the source of the error information.
This property is read only.

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.


364 Content Management API
DiagnosticsAPI object

DiagnosticsAPI object
This object implements the following interface:
■ IDiagnosticsAPI
This interface enables applications to write to Enterprise Vault event log and to
use Enterprise Vault tracing functionality (Dtrace).

Syntax
interface IDiagnosticsAPI : IDispatch

Member summary

Table 4-45 IDiagnosticsAPI properties

Property Read/Write Description

Name Read/Write Name of application

Table 4-46 IDiagnosticsAPI methods

Method Description

IsTraceEnabled Test whether trace is enabled for the selected level.

LogEvent Creates an entry in the Enterprise Vault event log.

Trace Traces a message, if trace enabled for the selected level.

Remarks
For a description of the Dtrace utility, see the Enterprise Vault Utilities guide.

Version information
■ This interface is available from Enterprise Vault 2007.
Content Management API 365
IDiagnosticsAPI : Name

IDiagnosticsAPI : Name
This property holds the name of the application.
This property is read/write.

Syntax
HRESULT Name([out, retval] BSTR* pVal);
HRESULT Name([in] BSTR pVal);

Parameters

[out, retval] BSTR* pVal Pointer to a string containing the name of the
application.

[in] BSTR pVal Name of application. Maximum of 50 characters. Default


is “API”.

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

Failed to determine archive.


Identity: John Paul Jones
Error: Entry Not Found (0x0002)

Return value

S_OK Success.

E_POINTER pVal is NULL, or is invalid.

E_ACCESSDENIED The property has already been set.


366 Content Management API
IDiagnosticsAPI : IsTraceEnabled

IDiagnosticsAPI : IsTraceEnabled
This method tests whether tracing is enabled for the selected level.

Syntax
HRESULT IsTraceEnabled([in] EV_API_TRACE_LEVEL traceLevel,
[out, retval] VARIANT_BOOL* enabled);

Parameters

[in] EV_API_TRACE_LEVEL traceLevel EV_API_TRACE_LEVEL value to check.

[out, retval] VARIANT_BOOL* enabled Whether the trace level is enabled.

Remarks
EV_API_TRACE_LEVEL is an enumerated value that indicates the level of
tracing.
See “EV_API_TRACE_LEVEL enumeration” on page 59.
This method can be used to optimize the cost of building the trace message for
the normal case, where trace is not enabled.

Return value

S_OK Success.

E_POINTER enabled is NULL.


Content Management API 367
IDiagnosticsAPI : LogEvent

IDiagnosticsAPI : LogEvent
This method creates an entry in the Enterprise Vault event log.

Syntax
HRESULT LogEvent([in] EV_API_EVENT_TYPE eventType,
[in] BSTR message);

Parameters

[in] EV_API_EVENT_TYPE eventType EV_API_EVENT_TYPE value.

[in] BSTR message Message to write.

Remarks
EV_API_EVENT_TYPE is an enumerated value that indicates the type of event.
See “EV_API_EVENT_TYPE enumeration” on page 58.
The events are logged under a single Event Id, 7002. The event source is set to
Enterprise Vault and the event category is determined by the executable logging
the event. If the executable is not an Enterprise Vault executable then the
category is None.

Return value

S_OK Success.

E_INVALIDARG eventType is invalid or message is


NULL.
368 Content Management API
IDiagnosticsAPI : Trace

IDiagnosticsAPI : Trace
This method traces a message, if trace is enabled for the selected level.

Syntax
HRESULT Trace([in] EV_API_TRACE_LEVEL traceLevel,
[in] BSTR message);

Parameters

[in] EV_API_TRACE_LEVEL traceLevel EV_API_TRACE_LEVEL value for trace


level.

[in] BSTR message Trace message.

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

not the trace message is captured by the DTrace utility as shown in the table
below.

Table 4-47 Mapping of API trace levels to Dtrace monitoring level settings

EV_API_TRACE_LEVEL value: TRACE_LEVEL_ TRACE_LEVEL_ TRACE_LEVEL_


HIGH MEDIUM LOW

Off No No No
DTrace
monitoring Brief Yes No No
level Medium Yes Yes No
setting:
Verbose Yes Yes Yes

The standard coding advice for tracing is to use TRACE_LEVEL_MEDIUM by


default, use TRACE_LEVEL_HIGH to provide a high level view of the application
progress, and reserve use of TRACE_LEVEL_LOW for situations requiring
low-level debugging.

Return value

S_OK Success.

E_INVALIDARG message is NULL.


370 Content Management API
IDiagnosticsAPI : Trace
Chapter 5
NSF Manager API
This chapter describes the Enterprise Vault NSF Manager API, and its interface
and methods.

NSF Manager API


The NSF Manager API interacts with the Content Management API to enable
items in Notes databases to be stored in, or retrieved from, Enterprise Vault
archives.
NSF Manager API creates and uses an NSF database file to hold data being
passed to, or received from, the Content Management API.

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

See “IContent :: FileExtension” on page 224 and “IContent ::


MIMEFormat” on page 226.
■ IItem::ArchiveId determines the destination archive for the item.
See “IItem :: ArchiveId” on page 175.
■ IItem::Insert stores the item in the archive.
“IItem :: Insert” on page 196.
■ Use DeleteNote to delete the note from the NSF database (optional).
■ Use CloseNSF to release the open NSF database.
■ Use TerminateNotes to terminate the NSF Manager API.
The following steps outline how an application can use the NSF Manager and
Content Management API to retrieve a Note from an archive and view it in the
Notes client:
■ Use InitializeNotes to initialize the API.
■ Use SwitchToID to set the Notes security context (optional).
■ Use OpenNSF or CreateNSF to open or create an NSF database to hold the
item to be retrieved and viewed.
■ Use ImportNote to import the item from Content Management API to the
NSF database.
The following Content Management API properties and method can be used
to retrieve the item from the archive:
■ IItem::ArchiveId defines the archive where the item is stored.
See “IItem :: ArchiveId” on page 175.
■ IItem::Get retrieves the item from the archive.
See “IItem :: Get” on page 200.
■ IContent::Data holds the item content (as a file, or an IStream or
ILockBytes object).
“IContent :: Data” on page 232.
■ IContent::FileExtension specifies the type of the item (“dvns” or
IContent::MIMEFormat = “application/x-evnotestream”).
See “IContent :: FileExtension” on page 224 and “IContent ::
MIMEFormat” on page 226.
■ Use ViewNote to open the item in the Notes client.
■ Use DeleteNote to delete the item from the NSF database (optional).
■ Use CloseNSF to release the open NSF database.
■ Use TerminateNotes to terminate the NSF Manager API.
NSF Manager API 373
NSF Manager API

Components
The NSF Manager API contains one apartment-threaded, automation-friendly
COM class:
■ NSFManager

Security
When you interact with databases on a server, you must use an ID file that has
appropriate permissions.
374 NSF Manager API
Enumerations

Enumerations
This section describes enumerations used by the NSF Manager API.

InitializeNotes enumeration
InitializeNotes is an enumerated value that is used in conjunction with the
InitializeNotes and TerminateNotes methods:

enum EV_NOTES_INIT_MODE
{
EV_NOTES_INIT_APPLICATION,
EV_NOTES_INIT_THREAD
};
NSF Manager API 375
NSFManager object

NSFManager object
The NSFManager object implements the following interface:
■ INSFManager

Syntax
interface NSFManager : IDispatch

Member summary

Method Description

OpenNSF Opens an existing database.

CreateNSF Creates a new database.

CloseNSF Closes the open database and optionally deletes it.

ViewNote Launches the Notes client and opens the specified note.

ImportNote Imports a note from a file, or an IStream or ILockBytes object.

ExportNote Exports a note to a file, or an IStream or ILockBytes object.

DeleteNote Deletes the specified note.

InitializeNotes Initializes the Notes runtime on the main application thread, or on


a worker thread.

TerminateNotes Terminates the Notes runtime on the main application thread, or


on a worker thread.

SwitchToID Switches to the specified ID file.

Requirements
See “Programming notes” on page 46.

CLSID FBD0FA42-EF3C-4761-B3E4-9C39422273CE

Prog ID KVS.EnterpriseVault.LotusDomino.NSFManager

Type Library EVContentManagementAPILib

DLL KVS.EnterpriseVault.NSFManager.dll
376 NSF Manager API
NSFManager object

.NET Primary Interop


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

.NET PIA namespace KVS.EnterpriseVault.Interop


NSF Manager API 377
INSFManager :: OpenNSF

INSFManager :: OpenNSF
This method opens an existing NSF database.

Syntax
HRESULT OpenNSF([in] BSTR bsFilePath);

Parameters

[in] BSTR bsFilePath Specifies the full path to the database.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use OpenNSF to open a database:

Type type = Type.GetTypeFromProgID(


"KVS.EnterpriseVault.LotusDomino.NSFManager");
INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type);

try
{
nsfMgr.InitializeNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf");
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
378 NSF Manager API
INSFManager :: CreateNSF

INSFManager :: CreateNSF
This method creates a new NSF database.
If you supply the name of a template on which to base the new database, the
template must exist on the local machine.

Syntax
HRESULT CreateNSF(
[in] BSTR bsTemplateName,
[in] BSTR bsFilePath);

Parameters

[in] BSTR bsTemplateName The full path and file name of the template on which
you want to base the new database.

[in] BSTR bsFilePath The full path and file name of the new database.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use CreateNSF to create a database based
on a specified template:

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.CreateNSF(
@"c:\Program Files\Lotus\Notes\Data\mail8.ntf",
@"c:\DBs\TestDB.nsf");
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
NSF Manager API 379
INSFManager :: CloseNSF

INSFManager :: CloseNSF
This method closes the open NSF database and optionally deletes it.

Syntax
HRESULT CloseNSF([in] VARIANT_BOOL bDeleteNSF);

Parameters

[in] VARIANT_BOOL bDeleteNSF Use VARIANT_TRUE to delete the database.


Use VARIANT_FALSE to retain the database.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use CloseNSF to close a database, without
deleting it:

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(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
380 NSF Manager API
INSFManager :: ViewNote

INSFManager :: ViewNote
This method launches the Notes client and opens the specified note.

Syntax
HRESULT ViewNote([in] ULONG ulNoteId);

Parameters

[in] ULONG ulNoteId The ID of the note, which must exist in the database.

Return value
S_OK (success) or standard COM error codes.

Example
The following example how to use ViewNote to open a note:

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");
uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns");
nsfMgr.ViewNote(noteId);
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
NSF Manager API 381
INSFManager :: ImportNote

INSFManager :: ImportNote
This method imports a note from a file, or an IStream or ILockBytes object.
The note to be imported is in the proprietary Enterprise Vault format, as
returned from the Content Management API or by the ExportNote method.

Syntax
HRESULT ImportNote(
[in] VARIANT vInputNote,
[out, retval] ULONG *pulNoteId);

Parameters

[in] VARIANT vInputNote Variant that contains the data to be


imported.

[out, retval] ULONG *pulNoteId Returns the ID of the imported note.

Return value
S_OK (success) or standard COM error codes.

Example
The following example how to use ImportNote to import a note:

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");
uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns");
nsfMgr.ViewNote(noteId);
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
382 NSF Manager API
INSFManager :: ExportNote

INSFManager :: ExportNote
This method exports a note from the NSF database to a file, or an IStream or
ILockBytes object.
The note exported is in proprietary Enterprise Vault format, and can be passed
to the Content Management API or ImportNote method.

Syntax
HRESULT ExportNote(
[in] ULONG lNoteId,
[in] VARIANT vOutputNote);

Parameters

[in] ULONG ulNoteId The ID of the note.

[in] VARIANT vOutputNote A variant that contains the exported data.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use ExportNote to export a note:

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");
nsfMgr.ExportNote(0x8f6, @"c:\EVNotes\storedNote.dvns");
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
NSF Manager API 383
INSFManager :: DeleteNote

INSFManager :: DeleteNote
This method deletes the note from the NSF database.

Syntax
HRESULT DeleteNote([in] ULONG ulNoteId);

Parameters

[in] ULONG ulNoteId The ID of the note.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use DeleteNote to delete a note:

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");
nsfMgr.DeleteNote(0x8a6);
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
384 NSF Manager API
INSFManager :: InitializeNotes

INSFManager :: InitializeNotes
This method initializes the Notes runtime on the main application thread, or on
a worker thread.
The main thread must initialize Notes before any worker threads.

Syntax
HRESULT InitializeNotes([in] EV_NOTES_INIT_MODE initMode);

Parameters

[in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to


initialize on the main application thread or a
worker thread.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use InitializeNotes to initialize the Notes
runtime on the main application thread:

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.CreateNSF(
@"c:\Program Files\Lotus\Notes\Data\mail8.ntf",
@"c:\DBs\TestDB.nsf");
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
NSF Manager API 385
INSFManager :: TerminateNotes

INSFManager :: TerminateNotes
This method terminates the Notes runtime on the main application thread, or on
a worker thread.
Terminate the Notes runtime on the worker threads before the main thread.

Syntax
HRESULT TerminateNotes([in] EV_NOTES_INIT_MODE initMode);

Parameters

[in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to


terminate on the main application thread or a
worker thread.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use TerminateNotes to terminate the
Notes runtime:

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(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
386 NSF Manager API
INSFManager :: SwitchToID

INSFManager :: SwitchToID
This method switches to the specified ID file, which is required when you create
an NSF database from a template, or open an NSF database from a remote
server.

Syntax
HRESULT SwitchToID(
[in] BSTR bsIdFilePath,
[in] BSTR bsPassword);

Parameters

[in] BSTR bsIdFilePath The full path and file name of the ID file.

[in] BSTR bsPassword The ID file’s password.

Return value
S_OK (success) or standard COM error codes.

Example
The following example shows how to use SwitchToID to switch to a specified ID:

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.SwitchToID(
@"c:\Program Files\Lotus\Notes\Data\IDs\user.id",
@"passw0rd");
nsfMgr.OpenNSF(@"DomSvr1/ACME!!mail\user.nsf");
}
finally
{
nsfMgr.CloseNSF(false);
nsfMgr.TerminateNotes(
EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);
}
Chapter 6
Retention API
This chapter describes the Enterprise Vault Retention API and its interfaces,
methods and properties.

Retention API
The Retention API enables management of the set of Enterprise Vault retention
categories. An application using the Content Management API to archive items
or an application using the Filtering APIs can use the Retention API to select an
existing retention category, or create a new retention category.
The Retention API enables client applications to:
■ Create a new retention category.
■ Update an existing retention category.
■ Retrieve the details of an existing retention category.
■ Enumerate retention categories.

Components
The API consists of two apartment-threaded, automation-friendly COM classes:
■ RetentionCategories
RetentionCategories implements a collection object of class
RetentionCategory. It implements the IRetentionCategories and
IRetentionCategories2 interfaces. The methods and properties enable the
calling application to enumerate the current list of retention categories and
add new retention categories.
■ RetentionCategory
The RetentionCategory class maintains a collection of RetentionCategory
properties. It implements the IRetentionCategory and IRetentionCategory2
388 Retention API
Retention API

interfaces. The methods and properties enable the calling application to


view and change the various attributes of a retention category.

Security
No special privileges are required to list and read retention categories.
To create or update retention categories requires that the API is run under the
Vault Service Account, or an account that is in a suitable Enterprise Vault
roles-based administration role that includes the role task “EVT Administer
Enterprise Vault Retention Categories”.
Retention API 389
Enumerations

Enumerations
This section describes enumerations used by the Retention API.

Retention Units enumeration


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

Retention Date Basis enumeration


The RetentionDateBasis value indicates the date from which to calculate the
storage expiry date of an item.
enum _RetentionDateBasis {
ExpiryBasisArchiveDate = 0,
ExpiryBasisModifiedDate = 1,
ExpiryBasisInherit = 2,
ExpiryBasisUnknown = 3
} ;
ExpiryBasisInherit takes the value set for the Enterprise Vault site.
The retention category cannot be saved or updated if the value set is
ExpiryBasisUnknown.
390 Retention API
RetentionCategories object

RetentionCategories object
The RetentionCategories object implements the following interfaces:
■ IRetentionCategories
■ IRetentionCategories2 (default)
The interfaces implement a collection object for the creation and enumeration
of RetentionCategory objects.
The IRetentionCategories2 interface inherits the properties and methods of the
IRetentionCategories interface, and also provides a Get method to retrieve the
properties of a retention category.

Syntax
interface IRetentionCategories : IDispatch
interface IRetentionCategories2 : IRetentionCategories

Member summary

Table 6-1 IRetentionCategories properties

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.
Retention API 391
RetentionCategories object

Table 6-2 IRetentionCategories methods

Method Description

Lookup Retrieve limited details of a retention category.


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

Create Create a new retention category.


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

Add Add a retention category to the collection. This is the preferred


method for creating a new retention category.

Update Update details of an existing retention category.

Table 6-3 IRetentionCategories2 method

Method Description

Get Retrieve details of a retention category.

Remarks
To ensure all available retention category properties can be retrieved, use the
Add method to create a new retention category, and the Get method to retrieve
details of a retention category.
The DirectoryDNSAlias property identifies an Enterprise Vault server that can
be used to access the Enterprise Vault Directory for retention category
information.
392 Retention API
RetentionCategories object

Requirements
See “Programming notes” on page 46.

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 KVS.EnterpriseVault.Interop


Retention API 393
IRetentionCategories :: Count

IRetentionCategories :: Count
This property returns the number of retention categories in the collection.
The property is read only.

Syntax
HRESULT Count([out, retval] long *plCount);

Parameters

[out, retval] long *plCount Pointer to a long that will contain the current value.

Return value

S_OK Success.

E_POINTER The plCount pointer is NULL.

Examples
The following example Visual Basic script enumerates the available retention
categories.
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")


if Err.Number <> 0 then
MsgBox(Err.Description)
else
oRCs.DirectoryDNSAlias = "EVSite"
MsgBox("There are " & oRCs.Count & " categories")
For Each oRC In oRCs
sMsg = "Category is " & oRC.Name & " ; IsVisible=" &
oRC.IsVisible & " ;
OnHold=" & oRC.OnHold & " ; Locked=" & oRC.Locked
MsgBox(sMsg)
sNames = sNames & " " & oRC.Name
Next
set oRCS = Nothing
MsgBox("The list is: " & sNames)
end if
394 Retention API
IRetentionCategories :: _NewEnum

IRetentionCategories :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the collection of retention categories. This property is hidden
in Visual Basic and Visual Basic Scripting Edition (VBScript).
The property is read only.

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 .NET
managed code or VBScript.
This property returns a collection of RetentionCategory objects.

Return value

S_OK Success.

E_POINTER The pointer to the IUnknown pointer passed to the property


is invalid.

Example
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")


if Err.Number <> 0 then
MsgBox(Err.Description)
else
oRCs.DirectoryDNSAlias = "EVSite"
Retention API 395
IRetentionCategories :: _NewEnum

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
396 Retention API
IRetentionCategories :: Item

IRetentionCategories :: Item
This property returns the nth retention category object in the collection.
The property is read/write.

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.

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the
retention category interface pointer requested.

Remarks
This method enables an alternative method of enumerating the retention
categories in the collection.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG Index is less than or greater than the collection count.

Example
IRetentionCategories retCats = (IRetentionCategories) new
RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
1);
Retention API 397
IRetentionCategories :: DirectoryDNSAlias

IRetentionCategories :: DirectoryDNSAlias
This property is used to identify a computer running an Enterprise Vault
Directory Service, in order to retrieve information from the Enterprise Vault
Directory.
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
The Id of an Enterprise Vault Site can be found in the following registry entry on
an Enterprise Vault server:
HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID
The Id of an archive can be found in the Enterprise Vault Administration
Console, in the properties dialog for an archive.
Similarly, the Id of a vault store can be found in the Administration Console, in
the properties dialog for a vault store.
If you do not set DirectoryDNSAlias, then connection to the local computer is
assumed.

Return value

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.


398 Retention API
IRetentionCategories :: DirectoryDNSAlias

SiteIdNotFound bstrValue does not identify an existing site.

Examples
The following example sets a value for DirectoryDNSAlias in order to list
retention categories on a remote Enterprise Vault server.
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")

if Err.Number <> 0 then


MsgBox(Err.Description)
else
oRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"
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 399
IRetentionCategories :: Lookup

IRetentionCategories :: Lookup
This method is used to obtain details of a retention category when the Name or
Id of the retention category is known.
As this method does not return all available retention category properties, we
recommend that you use the Get method instead.

Syntax
HRESULT Lookup([in] BSTR NameOrId,
[out] VARIANT *Period,
[out] VARIANT *Units,
[out] VARIANT *IsVisible,
[out] VARIANT* Id,
[out] VARIANT* RCName,
[out, retval] VARIANT* RCFound);

Parameters

.[in] BSTR NameOrId String containing name or Id of the retention


category.

[out] VARIANT *Period Value of Period for the retention category. This
is the number of retention units an item is to be
retained.

[out] VARIANT *Units Value of Units for the retention category. This
is the type of retention units (days, weeks,
months, years).

[out] VARIANT *IsVisible Value of IsVisible for the retention category.


Describes whether the retention category is to
be displayed to end users.

[out] VARIANT* Id Identifier of the retention category.

[out] VARIANT* RCName Name of the retention category. Identifies the


retention category to the end user and the
administrator.

[out, retval] VARIANT* RCFound A boolean return value that indicates whether
or not the lookup was successful.
400 Retention API
IRetentionCategories :: Lookup

Return value

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

Examples
The following example Visual Basic script looks up the values assigned to the
Public retention category.
Dim oAPI
Dim msg

Set oAPI = CreateObject("EnterpriseVault.RetentionCategories")

Dim id, name, units, period, isvisible

oAPI.Lookup "Public", period, units, isvisible, id, name


set oAPI = Nothing

msg = msg & " name = " & name


msg = msg & " period = " & period
msg = msg & " units = " & units
msg = msg & " isvisible = " & isvisible
msg = msg & " id = " & id

Msgbox(msg)
Retention API 401
IRetentionCategories :: Create

IRetentionCategories :: Create
This method is used to create a new retention category.
As this method does not allow the specification of all available retention
category properties, we recommend that you use the Add method instead.

Syntax
HRESULT Create([in] BSTR Name,
[in] LONG Period,
[in] RetentionUnits Units,
[in] VARIANT_BOOL IsVisible,
[in] BSTR Description,
[out,retval] BSTR* Id);

Parameters

.[in] BSTR Name The name of the retention category.

[in] LONG Period Number of retention units items are to be


retained.

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


(days, weeks, months, years).
See “Retention Units enumeration” on
page 389.

[in] VARIANT_BOOL IsVisible Determines whether or not the retention


category will be available to users for selection
in manual archive operations.

[in] BSTR Description Description of the retention category.

[out,retval] BSTR* Id Retention category Id.

Remarks
If the value of Period is 999999, and the value of Units is Years, the retention
period is “forever”.
If IsVisible is false, the retention category is still visible in the Enterprise Vault
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.
402 Retention API
IRetentionCategories :: Create

Return value

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

E_INVALIDARG One of the parameters is incorrect.

RetentionCategoryAlreadyExists A retention category with the same name already exists

Example
IRetentionCategories retCats = (IRetentionCategories) new
RetentionCategoriesClass();

retCats.Create(“New business”,10, RetentionUnits.Months, false,


“New business correspondence”);
Retention API 403
IRetentionCategories :: Add

IRetentionCategories :: Add
This is the preferred method for creating a new retention category and adding it
to the collection object.

Syntax
HRESULT Add([in] IUnknown* RetentionCategory);

Parameters

.[in] IUnknown* RetentionCategory A reference to a RetentionCategory object.

Remarks
An error will be returned if a retention category already exists with the same
name.
If the value of Period is 999999, and the value of Units is Years, the retention
period is “for ever”.

Return value

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

E_INVALIDARG One of the properties of the IRentionCategory pointer is


invalid.

E_NOINTERFACE There is a problem with the IRetentionCategory pointer


passed into the method.

RetentionCategoryAlreadyExists A retention category with the same name already exists

Examples
The following example Visual Basic script adds two new retention categories:
Finance and Legal.
Dim oRCS
Dim oRC

Set oRCS = CreateObject("EnterpriseVault.RetentionCategories")


404 Retention API
IRetentionCategories :: Add

'Create a Retention Category

Set oRC = Nothing


Set oRC = CreateObject("EnterpriseVault.RetentionCategory")

oRC.Name = "Finance"
oRC.Description = "For finance dept items"
oRC.Units = 3
oRC.Period = 6
oRC.IsVisible = True
oRC.OnHold = False
oRC.Locked = False

oRCS.Add(oRC)

msgbox(oRC.identifier)

'Create another Retention Category

Set oRC = Nothing


Set oRC = CreateObject("EnterpriseVault.RetentionCategory")

oRC.Name = "Legal"
oRC.Description = "For legal department items"
oRC.Units = 3
oRC.Period = 7
oRC.IsVisible = False
oRC.OnHold = True
oRC.Locked = True

oRCS.Add(oRC)

msgbox(oRC.identifier)
Retention API 405
IRetentionCategories :: Update

IRetentionCategories :: Update
This method is used to change an existing retention category.

Syntax
HRESULT Update([in] IUnknown* RetentionCategory);

Parameters

.[in] IUnknown* RetentionCategory Reference to the RetentionCategory object to


be updated.

Remarks
Any changes that you make to a retention category will be retrospective, and be
applied to unexpired items that have been archived with the retention category.
An error will be returned if the retention category specified does not exist.

Return value

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

E_INVALIDARG One of the properties of the IRetentionCategory pointer


passed as a parameter is invalid.

RetentionCategoryNotExist The retention category does not exist.

Examples
The following example updates details of retention categories on a remote
computer and sets all the retention categories on hold.
Dim oRCs
Dim oRC
Dim sNames
Dim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")

if Err.Number <> 0 then


MsgBox(Err.Description)
406 Retention API
IRetentionCategories :: Update

else
oRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"
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)
oRC.OnHold = true
oRCs.Update(oRC)
sNames = sNames & " " & oRC.Name
Next
set oRCS = Nothing
MsgBox("The list is: " & sNames)
end if
Retention API 407
IRetentionCategories2 :: Get

IRetentionCategories2 :: Get
This is the preferred method for obtaining details of a retention category. It
returns a populated instance of the RetentionCategory object.

Syntax
HRESULT Get([in] BSTR NameOrId,
[out, retval] IUnknown** RetentionCategory);

Parameters

[in] BSTR NameOrId String containing name or Id of the retention


category.

Remarks
This method supercedes the Lookup method as it enables the retrieval of all
available retention category properties, including the ExpiryBasis property.

Return value

S_OK Success.

E_INVALIDARG NameOrId is NULL or RetentionCategory is NULL.

E_UNEXPECTED An unexpected error has occurred.

RetentionCategoryNotExist A Retention Category with the given NameOrId value does


not exist.

Example
IRetentionCategories2 retCats2 = (IRetentionCategories2) new
RetentionCategoriesClass();

IRetentionCategory retcat =
(IRetentionCategory)retCats2.Get(“Business”);
408 Retention API
RetentionCategory object

RetentionCategory object
The RetentionCategory object implements the following interfaces:
■ IRetentionCategory
■ IRetentionCategory2 (default)
The interfaces maintain a set of properties for a RetentionCategory object. The
IRetentionCategory2 interface inherits the properties and methods of the
IRetentionCategory interface, and also provides the ExpiryBasis property.

Syntax
interface IRetentionCategory : IDispatch
interface IRetentionCategory2 : IRetentionCategory

Member summary

Table 6-4 IRetentionCategory properties

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.

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


end user and the administrator.

Description read/write This property describes the retention category to the


administrator.

OnHold read/write This property describes whether archived items with


a particular retention category can be deleted or
expired. This protection applies during the retention
period, and also after the retention period has
expired.
This retention category hold is different from the
Legal Hold API.
Retention API 409
RetentionCategory object

Table 6-4 IRetentionCategory properties

Property Read/Write Description

Locked read/write This property enables a lock to be put on a retention


category. This prevents an administrator from
inadvertently modifying the retention category.

Table 6-5 IRetentionCategory2 property

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
410 Retention API
IRetentionCategory :: Period

IRetentionCategory :: Period
This property describes the number of retention units (days, weeks, months,
years) an item is to be retained.
The property is read/write.

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
If the value of Period is 999999, and the value of Units is Years, the retention
period is “for ever”.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range (1 -


999999)

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new


RetentionCategoryClass();
Retention API 411
IRetentionCategory :: Period

retcat.Name = “Finance”;
retcat.Description = “For finance depts”;
retcat.Identifier = “xyz”;
retcat.Units = RetentionUnits.Months;
retcat.Period = 10;
retcat.IsVisible = true;
retcat.OnHold = true;
retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
1);

string name = retCat.Name;


string descr = retCat.Description;
string ident = retCat.Identifier;
RetentionUnits ru = retCat.Units;
long period = retCat.Period;
bool isVis = retCat.IsVisible;
bool onHold = retCat.OnHold;
bool locked = retCat. Locked;
412 Retention API
IRetentionCategory :: Units

IRetentionCategory :: Units
This property describes whether the period is expressed in days, weeks, months
or years.
The property is read/write.

Syntax
HRESULT Units([out, retval] RetentionUnits* pVal);
HRESULT Units([in] RetentionUnits newVal);

Parameters

[out, retval] RetentionUnits* pVal Enumerated value for type of retention


units (days, weeks, months, years).
See “Retention Units enumeration” on
page 389.

[in] RetentionUnits newVal RetentionUnits enumerated value.

Remarks
If the value of Period is 999999, and the value of Units is Years, the retention
period is “for ever”.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range (1 -


999999)

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;
Retention API 413
IRetentionCategory :: Units

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;
retcat.OnHold = true;
retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
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;
414 Retention API
IRetentionCategory :: IsVisible

IRetentionCategory :: IsVisible
This property describes whether the retention category is to be displayed to end
users.
The property is read/write.

Syntax
HRESULT IsVisible([out, retval] VARIANT_BOOL* pVal);
HRESULT IsVisible([in] VARIANT_BOOL newVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Reference to current value.

[in] VARIANT_BOOL newVal New value.

Remarks
All retention categories are visible to administrators in the Administration
Console, even if this the value of this property is FALSE.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range (1 -


999999)

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new


RetentionCategoryClass();

retcat.Name = “Finance”;
Retention API 415
IRetentionCategory :: IsVisible

retcat.Description = “For finance depts”;


retcat.Identifier = “xyz”;
retcat.Units = RetentionUnits.Months;
retcat.Period = 10;
retcat.IsVisible = true;
retcat.OnHold = true;
retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
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;
416 Retention API
IRetentionCategory :: Identifier

IRetentionCategory :: Identifier
This parameter uniquely identifies the retention category.
The property is read/write.

Syntax
HRESULT Identifier([out, retval] BSTR* pVal);
HRESULT Identifier([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to a string containing the retention category
Id.

[in] BSTR newVal String containing retention category Id (up to 250


Unicode characters).

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

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;
retcat.OnHold = true;
retcat.Locked = true;

retCats.Add(retCat);
Retention API 417
IRetentionCategory :: Identifier

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
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;
418 Retention API
IRetentionCategory :: Name

IRetentionCategory :: Name
This parameter identifies the retention category to end users and the
administrator.
The property is read/write.

Syntax
HRESULT Name([out, retval] BSTR* pVal);
HRESULT Name([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal The current retention category name.

[in] BSTR newVal New retention category name.


Maximum length is 32 unicode characters.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

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;
retcat.OnHold = true;
retcat.Locked = true;
Retention API 419
IRetentionCategory :: Name

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
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;
420 Retention API
IRetentionCategory :: Description

IRetentionCategory :: Description
This property describes the retention category to the administrator.
The property is read/write.

Syntax
HRESULT Description([out, retval] BSTR* pVal);
HRESULT Description([in] BSTR newVal);

Parameters

[out, retval] BSTR* pVal Pointer to description of retention category.

[in] BSTR newVal New description of retention category.


Maximum length is 127 unicode characters.

Remarks
When creating a retention category, this property must be set. The value cannot
be an empty string.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is either an empty string or is greater than 127


characters in length.
Retention API 421
IRetentionCategory :: OnHold

IRetentionCategory :: OnHold
This property describes whether archived items with a particular retention
category can be deleted or expired. This protection applies during the retention
period, and also after the retention period has expired.
While this property remains true, neither users nor Enterprise Vault storage
expiry can delete items that have been stored using this retention category.
The property is read/write.

Syntax
HRESULT OnHold([out, retval] VARIANT_BOOL* pVal);
HRESULT OnHold([in] VARIANT_BOOL newVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL containing


the current value.

[in] VARIANT_BOOL newVal New value.

Remarks
This retention category hold is different from the Legal Hold feature described
in “About Legal Hold” on page 313.

Return value

S_OK Success.

E_POINTER pVal is an invalid pointer.

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new


RetentionCategoryClass();
422 Retention API
IRetentionCategory :: OnHold

retcat.Name = “Finance”;
retcat.Description = “For finance depts”;
retcat.Identifier = “xyz”;
retcat.Units = RetentionUnits.Months;
retcat.Period = 10;
retcat.IsVisible = true;
retcat.OnHold = true;
retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
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;
Retention API 423
IRetentionCategory :: Locked

IRetentionCategory :: Locked
This property enables a lock to be put on a retention category. This prevents an
administrator from inadvertently modifying the retention category.
The property is read/write.

Syntax
HRESULT Locked([out, retval] VARIANT_BOOL* pVal);
HRESULT Locked([in] VARIANT_BOOL newVal);

Parameters

[out, retval] VARIANT_BOOL* pVal Pointer to current value.

[in] VARIANT_BOOL newVal 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 pVal is an invalid pointer.

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new


RetentionCategoryClass();

retcat.Name = “Finance”;
retcat.Description = “For finance depts”;
retcat.Identifier = “xyz”;
retcat.Units = RetentionUnits.Months;
424 Retention API
IRetentionCategory :: Locked

retcat.Period = 10;
retcat.IsVisible = true;
retcat.OnHold = true;
retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i +
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;
Retention API 425
IRetentionCategory2 :: ExpiryBasis

IRetentionCategory2 :: ExpiryBasis
This property indicates the date from which storage expiry is calculated.
The property is read/write.

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
enumeration” on page 389.

[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 pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range.

Example
[in]

IRetentionCategories retcats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;
426 Retention API
IRetentionCategory2 :: ExpiryBasis

IRetentionCategory2 retcat2 = (IRetentionCategory2) new


RetentionCategoryClass();

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;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new


RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++)


{
IRetentionCategory2 retCat = (IRetentionCategory2)retcats.Item(i
+ 1);

string name = retCat2.Name;


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

About the Filtering APIs


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

■ Exchange Journaling task


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

Exchange Filtering API


The Exchange Filtering API provides a mechanism for COM components to be
loaded by the appropriate Exchange archiving task, and called on a per-message
basis during the archiving process.

Figure 7-1 Overview of Exchange filtering

The figure, “Overview of Exchange filtering”, illustrates how Enterprise Vault


implements Exchange external filters:
■ If the registry settings are configured to enable filtering for the Exchange
Mailbox, Journaling or Public Folder tasks, the task calls the task filter
controller when processing a message.
■ The task filter controller invokes the first external filter, which implements
the IExternalFilter interface.
■ The external filter calls the IArchivingControl3 interface, which is
implemented by the task filter controller, to retrieve information about the
message.
430 Filtering APIs
Exchange Filtering API

■ The filter processes the message synchronously, using the methods and
properties of the IArchivingControl3 interface to set properties that define
how the Exchange archiving task is to process the message.
■ Provided the stopFiltering parameter is not set to TRUE, each filter is
applied in turn to the message.
■ After the message has been processed by all of the registered filters, the task
filter controller then invokes the FilteringComplete method for each filter.
This enables the filter to tidy up and release any resources used while
processing the message.
■ The Exchange archiving task then completes archiving the message, as
modified by the external filters and also taking account of any archiving
actions set by the external filters.

Developing Exchange external filters

Note: External filters for Exchange filtering must be developed in unmanaged


code. This is because the Enterprise Vault Exchange archiving tasks are written
in an unmanaged language and Microsoft has not implemented a managed
(.NET) MAPI library.

A filter should be implemented as an apartment-threaded, in-process COM


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

Exchange filtering registry settings


Filtering for Enterprise Vault Exchange Mailbox, Journaling, and Public Folder
tasks is enabled using registry settings under the following registry key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
You add a new key to specify the type of archiving task that is to perform the
filtering. The key can be one of the following:
■ Mailbox
■ Journaling
Filtering APIs 431
Exchange Filtering API

■ PublicFolder
For example, to add filtering for the Exchange Mailbox archiving tasks, you add
the Mailbox key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
You then add a string value to the Mailbox key for each of the required external
filters. For the name of each filter entry, use the values, 1, 2, 3 and so on. If there
are multiple filters, the filter names should form an unbroken numerical
sequence. The filters are applied in numerical order. If one number is missing,
no further filters are applied.

Note: When configuring filtering for Exchange journaling tasks, if the


Compliance Accelerator Journaling Connector filter exists, it must be last in the
sequence.

For the value of each filter entry give the ProgID (that is, the
ProjectName.ClassName of the COM class implementing IExternalFilter for
this particular filter). For example, the value for the generic Enterprise Vault
filter for Exchange Server filtering is EnterpriseVault.CustomFilter.
The following example shows three external filters that have been configured
for the Exchange Mailbox archiving tasks.
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
1 = ACompany.Filter1
2 = ACompany.Filter2
4 = ACompany.Filter3
In this case, filter 1 is applied and then filter 2. However, filter processing stops
after filter 2 because the filter name sequence is broken.
The following optional DWORD values can also be created to control filtering:
■ Override — This setting has the following effect:
■ Exchange Journaling tasks. If created under the Journaling key, and
given the value, 1, this setting forces the Exchange Journaling tasks to
retry messages that were marked as MARK_DO_NOT_ARCHIVE by a
previous filter.
432 Filtering APIs
Exchange Filtering API

If the value is 0, or the setting does not exist, the Exchange Journaling
tasks do not retry messages that are marked as
MARK_DO_NOT_ARCHIVE.
■ Exchange Mailbox and Public Folder tasks. If created under the Maibox
or PublicFolder keys, and given the value, 1, this setting turns off
custom filtering.
If the value is 0, or the setting does not exist, the archiving tasks
implement the configured custom filters.
■ MoveOnFilterFailure — This can be set for Exchange Journaling tasks or
Exchange Mailbox tasks. If this setting has the value 1, and an unhandled
error occurs in the external filter, the message involved is moved to the
folder, Failed external filter. This folder is created automatically if it does
not exist.
If the value is 0, or the setting does not exist, the archiving tasks take the
following action:
■ Exchange Journaling task. When an unhandled error occurs in the
external filter, the task moves the associated messages to the folder,
Enterprise Vault Journaling Service\Invalid Journal Report
in the journal mailbox.
■ Exchange Mailbox task. When an unhandled error occurs in the
external filter, the archiving task does not move the associated
messages. The task tries to process the messages during each archiving
run
In the following example, the Override and MoveOnFilterFailure settings
have been created under the Mailbox registry key:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\External Filtering
\Mailbox
1 = ACompany.Filter1
2 = ACompany.Filter2
Override = 0
MoveOnFilterFailure = 1
If you make changes to the custom filtering registry settings, restart the
associated archiving tasks to implement the changes.
For further details of the filtering registry settings, see the Configuring custom
filtering chapter in the the manual, Setting Up Exchange Server Archiving.
Filtering APIs 433
Enumerations (Exchange filtering)

Enumerations (Exchange filtering)


This section lists the enumerations for the Exchange Filtering API.

EV_ACTION enumeration
The following enumeration values are defined for EV_ACTION:
enum EV_ACTION
{
NO_ACTION = 0,
ARCHIVE_ITEM = 1,
MARK_DO_NOT_ARCHIVE = 2,
MOVE_DELETED_ITEMS = 3,
HARD_DELETE = 4,
REQUEST_SHUTDOWN = 5
};
The default value is ARCHIVE_ITEM.
When the task is running in report mode the action is ignored.

EV_ATTACHMENT_ACTION enumeration
The following enumeration values are defined for EV_ATTACHMENT_ACTION:
enum EV_ATTACHMENT_ACTION
{
NO_ATTACHMENT_ACTION = 0,
DELETE_ATTACHMENT = 1,
REPLACE_ATTACHMENT = 2
};
If the attachment action is to replace attachments, users will see a file called
Deleted Attachments.txt attached to messages that have had
attachments deleted by the filter. When they open this file, it contains a list of
the names of files that have been deleted.
The contents of this file are taken from the file,
CF_Replace_Attachment.txt, in the Enterprise Vault program folder
(typically, C:\Program Files\Enterprise Vault). If required, you can
modify the text of this file. For example, you may want to localize the
descriptive text.

EV_RETRY_STATUS enumeration
The following enumeration values are defined for EV_RETRY_STATUS:
enum EV_RETRY_STATUS
{
UNKNOWN_IF_RETRY = 0,
IS_NOT_RETRY = 1,
IS_A_RETRY = 2
434 Filtering APIs
Enumerations (Exchange filtering)

};
UNKNOWN_IF_RETRY does not indicate an error; it indicates that the task
could not determine if the status was a retry. For example, this may be returned
if the archiving task does not support detecting retries. Filters should interpret
an UNKNOWN_IF_RETRY status as IS_NOT_RETRY.

EV_REARCHIVE_STATUS enumeration
The following enumeration values are defined for EV_REARCHIVE_STATUS:
enum EV_REARCHIVE_STATUS
{
UNKNOWN_IF_REARCHIVE = 0,
IS_NOT_REARCHIVE = 1,
IS_A_REARCHIVE = 2
};
UNKNOWN_IF_REARCHIVE does not indicate an error; it indicates that the task
could not determine if the status was a re-archive. For example, this may be
returned if the archiving task does not support detecting re-archives. Filters
should interpret an UNKNOWN_IF_REARCHIVE status as IS_NOT_REARCHIVE.

Message direction enumeration


The following enumeration values are defined for MSG_DIRECTION:
public enum MSG_DIRECTION
{
DIRECTION_UNDEFINED = 0,
DIRECTION_INTERNAL = 1,
DIRECTION_EXTERNAL_IN = 2,
DIRECTION_EXTERNAL_OUT = 3
}
Filtering APIs 435
IExternalFilter interface

IExternalFilter interface
An external filter implements the following interface:
■ IExternalFilter

Syntax
interface IExternalFilter : IDispatch

Member summary

Method Description

Initialize This method is called during Exchange archiving task initialization.

ProcessFilter This method is called per-message during the archiving process. The
ProcessFilter method is where you process the message to your
requirements.

FilteringComplete This method is called after all filters have been processed for the
current item.

Remarks
The external filter must implement the COM interface, IExternalFilter, which is
called by the task filter controller.
All methods must be implemented, even if they return only S_OK.
If the filter makes changes to the message, and the changes are to be reflected in
the Exchange Server store or the Enterprise Vault archive or both, then call the
IArchivingControl2 :: MAPISaveChanges method at the end of the method
(ProcessFilter or FilteringComplete) that made the changes to the message.
Making a change to the message in ProcessFilter and delaying the
MAPISaveChanges call to FilteringComplete is not regarded as good practice.
436 Filtering APIs
IExternalFilter :: Initialize

IExternalFilter :: Initialize
This method is called during Exchange archiving task initialization.

Syntax
HRESULT Initialize([in] IDispatch *pArchivingControl);

Parameters

[in] IDispatch *pArchivingControl Reference to the IArchvingControl interface.

Remarks
Filters are instantiated at task startup and released at task shutdown.
The filter should perform any necessary initialization before message
processing begins. The interface does not define a corresponding “Uninitialize”
method, so any resources created or opened in this method should be released
on the final release of the filter implementing the interface.
Filtering APIs 437
IExternalFilter :: ProcessFilter

IExternalFilter :: ProcessFilter
This method is called per-message during the archiving process. The
ProcessFilter method is where you process the message to your requirements.

Syntax
HRESULT ProcessFilter([out, retval] VARIANT_BOOL *bStopFiltering);

Parameters

[out, retval] VARIANT_BOOL *bStopFiltering Value of true stops the filter


controller from processing any
more filters on the current item.

Remarks
To get a reference to the message, use the IArchivingControl :: MAPIMessage
property.
To find or change the current action to be taken on the message, use the
IArchivingControl :: Action property.
Similarly to change the retention category or archive for the item, use the
currentRetentionCategoryId and currentVaultId properties on the
IArchivingControl interface.
The external filter must be written to handle concurrent calls. If the filter
accesses a shared resource, it must use appropriate concurrency protection.

See also
■ “IArchivingControl :: MAPIMessage” on page 450.
■ “IArchivingControl :: Action” on page 448.
■ “IArchivingControl :: currentVaultId” on page 443.
■ “IArchivingControl :: currentRetentionCategoryId” on page 444.
438 Filtering APIs
IExternalFilter :: FilteringComplete

IExternalFilter :: FilteringComplete
This method is called after all filters have been processed for the current item. It
can be used to clean up item-specific resources, such as memory or object
handles.

Syntax
HRESULT FilteringComplete();

Remarks
After processing has been completed, the properties on the IArchivingControl
interface are read-only. The properties can still be examined so that the filter
can determine the final state of the item.
Filtering APIs 439
IArchivingControl interface for Exchange filtering

IArchivingControl interface for Exchange filtering


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

Syntax
interface IArchivingControl3 : IArchivingControl2 :
IArchivingControl : IDispatch

Member summary

Table 7-1 IArchivingControl properties

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.

defaultRetentionCategoryId Read only The Id of the default retention


category for the Enterprise Vault
Site.

deleteOriginalItem Read/Write Whether the item is to be deleted


from the original location after it
has been archived.
440 Filtering APIs
IArchivingControl interface for Exchange filtering

Table 7-1 IArchivingControl properties

Property Read/Write Description

createShortcutToItem Read/Write Whether a shortcut is created in


the original location after the
item has been archived.

Action Read/Write The action to be taken by the


archiving task when the filtering
process is complete.

MAPISession Read only Gets a MAPI session.

MAPIMessage Read only A pointer to the current MAPI


message.

IndexedPropertiesSet Read only Lists the properties that have


been added using
AddIndexedProperty.

TransactionID Read only Identifies archiving action.

AgentType Read only Identifies the type of archiving


task using the filter.

AgentAssignedRetentionCategoryId Read only Identifies the original retention


category assigned.

AgentAssignedVaultId Read only Identifies the original destination


archive.

AttachmentAction Read/Write Defines action to be taken when


processing message attachments.

RetryStatus Read only Indicates if current archiving


action is a retry.

ReArchiveStatus Read only Indicates if current archiving


action is rearchiving an item that
has been restored from the
archive.
Filtering APIs 441
IArchivingControl interface for Exchange filtering

Table 7-2 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 7-3 IArchivingControl methods

Method Description

AddIndexedProperty Adds metadata to the item. The metadata will be indexed.

AddIndexPropertyToSet Adds custom properties to a named custom property set.

AddIndexPropertySet Adds a named custom property set.

GetFilterProperty Retrieves value of variable set using PutFilterProperty by another


filter.

PutFilterProperty Sets a variable that can be queried by other filters.

Table 7-4 IArchivingControl2 method

Method Description

MAPISaveChanges Enables changes to the current message to be saved.


442 Filtering APIs
IArchivingControl interface for Exchange filtering

Table 7-5 IArchivingControl3 properties

Method Description

SenderRecipientXML Retrieves an XML document containing the sender


and recipient information for the current message.

EnvelopeSenderRecipientXML Retrieves an XML document containing the sender


and recipient information taken from the envelope
message.

MessageDirection Indicates the direction in whish the message was


travelling (in relation to the domain defined as
internal).

Version information
■ IArchivingControl2 properties and method are available in Enterprise Vault
7.0 and later. MessageClass and MAPISaveChanges are also available in
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.
Filtering APIs 443
IArchivingControl :: currentVaultId

IArchivingControl :: currentVaultId
The Id of the archive associated with the current item.
This property is read/write.

Syntax
HRESULT currentVaultId([in] BSTR newVal);
HRESULT currentVaultId([out, retval] BSTR *pVal);

Parameters

[in] BSTR newVal Id of archive to be assigned.

[out, retval] BSTR *pVal Id of archive assigned.

Remarks
The currentVaultId property enables an external filter to control the archive (or
folder) in which the item is stored. Although a subsequent filter may actually
redefine this value. The value originally assigned can be retrieved using the
AgentAssignedVaultId property.
An example value is:
190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1
444 Filtering APIs
IArchivingControl :: currentRetentionCategoryId

IArchivingControl :: currentRetentionCategoryId
The Enterprise Vault retention category to be assigned to the current item.
This property is read/write.

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.
An example value is:
18306BF113C2C444096279660836252821b10000EVArchiveSite1
Use the Retention API to retrieve details of retention categories, and create new
retention categories.
See “Retention API” on page 387.
Filtering APIs 445
IArchivingControl :: defaultRetentionCategoryId

IArchivingControl :: defaultRetentionCategoryId
The default retention category for the Enterprise Vault Site.
This property is read only.

Syntax
HRESULT defaultRetentionCategoryId([out, retval] BSTR *pVal);

Parameters

[out, retval] BSTR *pVal Id of default retention category for site.

Remarks
The defaultRetentionCategoryId property enables the external filter to get the
default retention category for the Enterprise Vault Site.
446 Filtering APIs
IArchivingControl :: deleteOriginalItem

IArchivingControl :: deleteOriginalItem
This property indicates whether the item is to be deleted from the original
location after it has been archived.
This property is read/write.

Syntax
HRESULT deleteOriginalItem([in] BOOL newVal);
HRESULT deleteOriginalItem([out, retval] BOOL *pVal);

Parameters

[in] BOOL newVal New value.

[out, retval] BOOL *pVal Pointer to current value.

Remarks
When the archiving task is running in report mode, the action is ignored.
Filtering APIs 447
IArchivingControl :: createShortcutToItem

IArchivingControl :: createShortcutToItem
This property indicates whether a shortcut is created in the original location
after the item has been archived.
This property is read/write.

Syntax
HRESULT createShortcutToItem([in] BOOL newVal);
HRESULT createShortcutToItem([out, retval] BOOL *pVal);

Parameters

[in] BOOL newVal New value.

[out, retval] BOOL *pVal Pointer to current value.

Remarks
When the task is running in report mode the action is ignored.
448 Filtering APIs
IArchivingControl :: Action

IArchivingControl :: Action
This property indicates the action to be taken by the archiving task when the
filtering process is complete.
This property is read/write.

Syntax
HRESULT Action([in] EV_ACTION newVal);
HRESULT Action([out, retval] EV_ACTION *pVal);

Parameters

[in] EV_ACTION newVal EV_ACTION enumeration value.

[out, retval] EV_ACTION *pVal Current EV_ACTION enumeration value.

Remarks
For EV_ACTION enumeration values, see “EV_ACTION enumeration” on
page 433.
The default action is to archive the item (ARCHIVE_ITEM enumeration value).
Filtering APIs 449
IArchivingControl :: MAPISession

IArchivingControl :: MAPISession
This property returns a MAPI session for the current message.
This property is read only.

Syntax
HRESULT MAPISession([out, retval] IUnknown **pUnkVal);

Parameters

[out, retval] IUnknown **pUnkVal Pointer to MAPI session.


450 Filtering APIs
IArchivingControl :: MAPIMessage

IArchivingControl :: MAPIMessage
This property provides a pointer to the current MAPI message (P2).
This property is read only.

Syntax
HRESULT MAPIMessage([out, retval] IUnknown **pUnkVal);

Parameters

[out, retval] IUnknown **pUnkVal Pointer to MAPI message.

Remarks
The properties of the message can be accessed and updated using standard
MAPI calls. Any changes should be persisted using MAPISaveChanges at the end
of the method (ProcessFilter or FilteringComplete) that made the changes to the
message.
As MAPISaveChanges does not save changes made to attachments of P2
messages, these will have to be saved first by the caller.

See also
■ “IArchivingControl2 :: MAPISaveChanges” on page 467.
Filtering APIs 451
IArchivingControl :: AddIndexedProperty

IArchivingControl :: AddIndexedProperty
This method enables you to add a property to the custom index metadata for the
item.

Syntax
HRESULT AddIndexedProperty([in] BSTR propname,
[in] BSTR value);

Parameters

[in] BSTR propname Property name.

[in] BSTR value Property value.

Remarks
Using this method adds the property to the default property set.
Properties added using this method are always searchable and retrievable.
To avoid property name clashes, you are recommended to use
AddIndexPropertyToSet to add the property to a named property set. This will
also enable you to control whether the property is searchable and retrievable.
452 Filtering APIs
IArchivingControl :: IndexedPropertiesSet

IArchivingControl :: IndexedPropertiesSet
This property lists the properties that have been added to the custom index
metadata of the item using AddIndexedProperty.
The property is read only.

Syntax
HRESULT IndexedPropertiesSet([out, retval] BSTR *pVal);

Parameters

[out, retval] BSTR *pVal Pointer to the XML list of properties.

Remarks
This property enables the filter to find out the custom index metadata that has
been added to the item using AddIndexedProperty method.
The properties are returned as XML which can be loaded into an
ISimpleIndexMetadata object using the FromXML method.
See “ISimpleIndexMetadata :: FromXML” on page 290.
Filtering APIs 453
IArchivingControl :: AddIndexPropertyToSet

IArchivingControl :: AddIndexPropertyToSet
This method adds a custom index metadata property to a named property set.

Syntax
HRESULT AddIndexPropertyToSet([in] BSTR setname,
[in] BSTR propname,
[in] BSTR propvalue);

Parameters

[in] BSTR setname Name of property set.

[in] BSTR propname Name of property.

[in] BSTR propvalue Value of property.

Remarks
The searchable and retrievable settings for the property set will define how the
property is handled.
If the property set exists, the property will be added to that property set. If it
does not exist, the property set will be created first.
If a property set is created "by default", it will have the default attributes of
searchable ="true" and retrievable ="false".
If a property needs to be retrievable, the property set needs to be created using
the AddIndexPropertySet method, where the values for searchable and
retrievable can be set explicitly.
Properties can be multi-valued. When adding a property, the existence of that
property within the specified set is checked and, if present, the value is added as
an element of that property.
454 Filtering APIs
IArchivingControl :: AddIndexPropertySet

IArchivingControl :: AddIndexPropertySet
This method adds a named custom property set. Custom index metadata
properties can be added to this set using AddIndexPropertyToSet method.

Syntax
HRESULT AddIndexPropertySet([in] BSTR setname,
[in] BOOL searchable,
[in] BOOL retrievable);

Parameters

[in] BSTR setname The name of the property set. Suitable names would be your
company name or the filter application name.

[in] BOOL searchable Setting the value to “true” means that properties in the set
will be indexed.

[in] BOOL retrievable Setting the value to “true” means that property values can be
returned as part of the search results.
The default is “false”.

Remarks
Properties added can be grouped in named property sets. It is good practice to
use a named property sets in order to avoid name clashes with other filter
additions. The property set names, Vault, EnterpriseVault, KVS, Veritas, and
Symantec are reserved.
Properties defined as Searchable will be indexed and can be searched for using
the Search API. Properties defined as Retrievable can be retrieved and displayed
later with the item. Each property set can be marked as Searchable or
Retrievable or both.
See “SimpleIndexMetadata object” on page 277.
Property sets do not need to be created before properties are added to them.
Filtering APIs 455
IArchivingControl :: TransactionID

IArchivingControl :: TransactionID
This property is the unique identifier that will be assigned to the archived item.
The property is read only.

Syntax
HRESULT TransactionID([out, retval] BSTR* pTransactionID);

Parameters

[out, retval] BSTR* pTransactionID Transaction Id.

Remarks
This property can be used as the IItem :: Id value in the Content Management
API to subsequently fetch the archived item.

See also
■ “IArchivingControl :: RetryStatus” on page 462.
■ “IArchivingControl :: ReArchiveStatus” on page 463.
456 Filtering APIs
IArchivingControl :: AgentType

IArchivingControl :: AgentType
This property identifies the type of the current archiving task.
The property is read only.

Syntax
HRESULT AgentType([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Current archiving task type.

Remarks
The value can be one of the following:
■ Mailbox
■ Journaling
■ PublicFolder
Filtering APIs 457
IArchivingControl :: AgentAssignedRetentionCategoryId

IArchivingControl ::
AgentAssignedRetentionCategoryId
This property identifies the original retention category assigned, in case other
filters have assigned a different retention category.
The property is read only.

Syntax
HRESULT AgentAssignedRetentionCategoryId([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Retention category Id.

Remarks
Use the Retention API to retrieve details of retention categories, and create new
retention categories.
See “Retention API” on page 387.
458 Filtering APIs
IArchivingControl :: AgentAssignedVaultId

IArchivingControl :: AgentAssignedVaultId
This property identifies the original destination archive, in case other filters
have redirected the message to an alternative archive.
The property is read only.

Syntax
HRESULT AgentAssignedVaultId([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Archive Id.


Filtering APIs 459
IArchivingControl :: GetFilterProperty

IArchivingControl :: GetFilterProperty
This method enables communication between filters; a filter property can be set
by one filter and queried by another.

Syntax
HRESULT GetFilterProperty([in] BSTR Key);
HRESULT GetFilterProperty([out, retval] BSTR *pVal);

Parameters

[in] BSTR Key Key for property used by PutFilterProperty.

[out, retval] BSTR *pVal Pointer to a string containing the value of Setting (set
with PutFilterProperty).

Remarks
The GetFilterProperty and PutFilterProperty methods facilitate communication
between filters; a filter may set a property value which a later filter can then
query. Once a property value is set, it will be passed down to each filter.
The method uses the Key, (used by PutFilterProperty), to retrieve the Setting
value that was set with PutFilterProperty method.
The setting can be set by separate filters, so the order in which they are called is
important.
If called with a Key that has not been set, then it will return an empty string, but
will not return an error.
460 Filtering APIs
IArchivingControl :: PutFilterProperty

IArchivingControl :: PutFilterProperty
This method is used to set a filter property that is passed on to subsequent
filters.

Syntax
HRESULT PutFilterProperty ([in] BSTR Key,
[in] BSTR Setting);

Parameters

[in] BSTR Key Key for filter property.

[in] BSTR Setting Value of filter property.

Remarks
The caller supplies a unique name (Key) for each setting that can then be
retrieved using GetFilterProperty.
The property values exist until filtering is completed for the current item.
Settings can be updated by calling PutFilterProperty a second time, suppling the
same key. The keys are case insensitive.
Its not possible to delete filter settings, but they can be set to empty.
Filtering APIs 461
IArchivingControl :: AttachmentAction

IArchivingControl :: AttachmentAction
This property defines the action to be taken when processing attachments to
messages.
This property is read/write.

Syntax
HRESULT AttachmentAction([in] EV_ATTACHMENT_ACTION newVal);
HRESULT AttachmentAction([out, retval] EV_ATTACHMENT_ACTION *pVal);

Parameters

[in] EV_ATTACHMENT_ACTION newVal The new value to set.

[out, retval] EV_ATTACHMENT_ACTION *pVal Pointer to an


EV_ATTACHMENT_ACTION type
that contains the current value.

Remarks
This property is not currently supported.
With Exchange server filtering, if the message attributes satisfy a rule, any
attachments are then evaluated using attachment attributes. When an
attachment matches a rule, the action specified by ATTACHMENT_ACTION is
applied to the attachment.
For EV_ATTACHMENT_ACTION enumeration values, see
“EV_ATTACHMENT_ACTION enumeration” on page 433.
462 Filtering APIs
IArchivingControl :: RetryStatus

IArchivingControl :: RetryStatus
This property enables the caller to determine if the current attempt to archive
an item is a retry.
The property is read only.

Syntax
HRESULT RetryStatus([out, retval] EV_RETRY_STATUS* pRetryStatus

Parameters

[out, retval] EV_RETRY_STATUS* pRetryStatus Pointer to an


EV_RETRY_STATUS type
containing the current value.

Remarks
Sometimes when an item fails to be archived, the item will be subsequently
retried by the archiving task. In this case, the item will also be refiltered.
If this is a retry, the transactionID will typically be the same as the previous
attempt.
This property can be used to avoid the following when processing retries:
■ Counting the same transaction multiple times.
■ Storing the same transaction (for example, in a database) multiple times.
For EV_RETRY_STATUS enumeration values, see “EV_RETRY_STATUS
enumeration” on page 433.

See also
■ “IArchivingControl :: TransactionID” on page 455.
■ “IArchivingControl :: ReArchiveStatus” on page 463.
Filtering APIs 463
IArchivingControl :: ReArchiveStatus

IArchivingControl :: ReArchiveStatus
If an item has been restored and is being rearchived, this property enables the
caller to determine if the current item is being rearchived.
The property is read only.

Syntax
HRESULT ReArchiveStatus([out, retval] EV_REARCHIVE_STATUS*
pReArchiveStatus);

Parameters

[out, retval] EV_REARCHIVE_STATUS* pReArchiveStatus Pointer to an


EV_REARCHIVE_
STATUS type
containing the current
value.

Remarks
If this is a rearchive, the transactionID will typically be the same as the previous
archive transaction.
This property can be used to avoid the following when processing rearchive
transactions:
■ Counting the same transaction multiple times.
■ Storing the same transaction (for example, in a database) multiple times.
For EV_REARCHIVE_STATUS enumeration values, see
“EV_REARCHIVE_STATUS enumeration” on page 434.
464 Filtering APIs
IArchivingControl2 :: BrowserViewURL

IArchivingControl2 :: BrowserViewURL
This property returns a string containing the URL that should be entered into a
web browser (for example) to view the item.
The property is read only.

Syntax
HRESULT BrowserViewURL([out,retval] BSTR* pVal)

Parameters

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the URL.

Remarks
This property will return an error if the archive Id and the saveset Id have not
been set previously.
The URL returned includes the IIS virtual directory for the Enterprise Vault
Web access application, but not a specific Web server name. Enterprise Vault
dynamically generates the full URL as needed, with the appropriate server name
for each caller.
This form of URL is compatible with Enterprise Vault Building Blocks architec-
ture.

Return value

S_OK Success.

E_FAIL An unexpected error has occurred.

E_INVALIDARG Either the archive Id or saveset Id have not been set or the
saveset Id is invalid.

Example
The following is an example value of BrowserViewURL:
http://webserver1.EXAMPLE.COM/EnterpriseVault/viewmessage.asp?Vault
ID=12B72E5122E1D714893C625CEF3A762311110000sv1.example.com&SavesetI
D=430D7CD1EA644810ADF10D71CF39063&Format=WEB
Filtering APIs 465
IArchivingControl2 :: NativeItemURL

IArchivingControl2 :: NativeItemURL
The URL downloads the item that was archived and attempts to open the item
using the default application for the type of the item.
This property is read only.

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.
The URL returned includes the IIS virtual directory for the Enterprise Vault
Web access application, but not a specific Web server name. Enterprise Vault
dynamically generates the full URL as needed, with the appropriate server name
for each caller.
This form of URL is compatible with Enterprise Vault Building Blocks architec-
ture.

Return Value

S_OK Success.

E_INVALIDARG Either the item Id or archive Id have not been set.

E_POINTER An invalid pointer has been passed as an argument and it is


not possible to return the current value of this property.

Example
The following is an example value of NativeItemURL:
http://webserver1.EXAMPLE.COM/EnterpriseVault/download.asp?VaultID=
12B72E5122E1D714893C625CEF3A762311110000sv1.example.com&SavesetID=4
30D7CD1EA644810ADF10D71CF39063&Request=NativeItem
466 Filtering APIs
IArchivingControl2 :: MessageClass

IArchivingControl2 :: MessageClass
This property returns the MAPI Message Class for the current item.
This property is read only.

Syntax
HRESULT MessageClass([out, retval] BSTR *pVal);

Parameters

[out, retval] BSTR *pVal Pointer to a string containing the MAPI message
class.

Remarks
The value of the MAPI property, OriginalMessageClass, is returned if it
exists. Otherwise the value of PR_MESSAGE_CLASS is returned.
If the current item is an envelope journal message (P1), then the Message Class
is returned from the P2 message.

Example
An example of a MAPI Message Class is:
IPM.Note
Filtering APIs 467
IArchivingControl2 :: MAPISaveChanges

IArchivingControl2 :: MAPISaveChanges
This method persists changes to the current message.

Syntax
HRESULT MAPISaveChanges();

Remarks
If the external filter makes changes to the message or message envelope, save
the changes by calling the MAPISaveChanges method at the end of the method
(ProcessFilter or FilteringComplete) that made the changes to the message. The
changes are saved in the Exchange Store. If the item is then archived, the
changes are also saved in the archive. It is not possible to save changes in the
archive but not in the Exchange Store.
MAPISaveChanges saves changes made to the following:
■ The P2 message.
■ Any attachment to the P1 message.
■ The P1 message.
As MAPISaveChanges does not save changes made to attachments of P2
messages, these will have to be saved first by the caller.
468 Filtering APIs
IArchivingControl3 :: SenderRecipientXML

IArchivingControl3 :: SenderRecipientXML
This property retrieves an XML document containing the sender and recipient
information for the current message.
The property is read only.

Syntax
HRESULT SenderRecipientXML([out, retval] IUnknown **ppStream);

Remarks
For Exchange Journaling tasks any distribution lists are expanded, regardless of
the setting of the Expand distribution lists setting on the Advanced page of the
Exchange Journaling policy in the Enterprise Vault Administration Console.
The property value is an XML document representing the sender and recipient
information for the current message, including expanded distribution lists.
For Exchange envelope journal items this information is extracted from the P2
message and is just a representation of the sender and recipient information as
taken from the MAPI message.
The return object implements IStream and can be loaded into an
XMLDOMDocument. The only available IStream methods available are
IStream :: CopyTo, IStream :: Read, IStream :: Seek and IStream :: Stat. All other
methods return E_NOTIMPL.

Example
<?xml version="1.0" encoding="UTF-16"?>
<ARCHIVED_ITEM xmlns:o="urn:kvsplc-com:archived_item"
version="1.0">
<MSG>
<RECP>
<TO>
<RC>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</RC>
<DL>
<DN>Distribution List Display Name</DN>
<EA>Distribution List SMTP Email Address</EA>
<TIME>2007-09-03T23:36:28</TIME>
<RC>
<DN>User1</DN>
<EA>SMTP Email Address</EA>
</RC>
</DL>
Filtering APIs 469
IArchivingControl3 :: SenderRecipientXML

</TO>
<CC/>
<BCC/>
</RECP>
<AUTH>
<FROM>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</FROM>
</AUTH>
</MSG>
</ARCHIVED_ITEM>
470 Filtering APIs
IArchivingControl3 :: EnvelopeSenderRecipientXML

IArchivingControl3 :: EnvelopeSenderRecipientXML
This property retrieves an XML document containing the sender and recipient
information taken from the envelope message.
The property is read only.

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.
The property value is an XML document representing the sender and recipient
information for the current message, including expanded distribution lists. The
recipient information as taken from the envelope report and does not contain
information from the P2 message.
The return object implements IStream and can be loaded into an
XMLDOMDocument. The only available IStream methods available are
IStream :: CopyTo, IStream :: Read, IStream :: Seek and IStream :: Stat. All other
methods return E_NOTIMPL.

Example
<?xml version="1.0" encoding="UTF-16"?>
<ARCHIVED_ITEM xmlns:o="urn:kvsplc-com:archived_item"
version="1.0">
<MSG>
<RECP P1="true">
<TO>
<RC>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</RC>
<DL>
<DN>Distribution List Display Name</DN>
<EA>Distribution List SMTP Email Address</EA>
<RC>
<DN>User1</DN>
<EA>SMTP Email Address</EA>
</RC>
</DL>
Filtering APIs 471
IArchivingControl3 :: EnvelopeSenderRecipientXML

</TO>
<CC/>
<BCC>
<RC>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</RC>
</BCC>
<ENV>
<RC>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</RC>
</ENV>
</RECP>
<AUTH P1=”true”>
<FROM>
<DN>Display Name</DN>
<EA>SMTP Email Address</EA>
</FROM>
</AUTH>
</MSG>
</ARCHIVED_ITEM>

Note: EnvelopeSenderRecipientXML for Exchange 2007 envelope items will not


contain any <DN> (Display Name) tags as the display name does not exist in the
P1 envelope report.
472 Filtering APIs
IArchivingControl3 :: MessageDirection

IArchivingControl3 :: MessageDirection
This property indicates the direction in which the message was travelling (in
relation to the domain defined as internal).

Syntax
HRESULT MessageDirection([out, retval] MSG_DIRECTION
*Msg_Direction);

Remarks
The property value is an enumerated value. For MSG_DIRECTION enumerated
values, see “Message direction enumeration” on page 434.
This property is read only.
Filtering APIs 473
Domino Filtering API

Domino Filtering API


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

About the Domino Filtering API


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

Figure 7-2 Overview of Domino filtering

The figure, “Overview of Domino filtering”, illustrates how Enterprise Vault


implements Domino journal filters:
■ If the registry settings are configured to enable filtering for the Domino
Journaling tasks, the Domino Journaling task calls the task filter controller
when processing a message in the Domino journal database.
474 Filtering APIs
Domino Filtering API

■ The task filter controller invokes the first external filter, which implements
the IExternalFilter interface.
■ The filter uses the methods and properties on the ILotusArchivingControl
interface to retrieve information about the message.
■ The filter then processes the message. Methods and properties on the
ILotusArchivingControl interface enable you to define how the Domino
Journaling task is to process the message.
■ If there are several filters, each external filter is applied in turn to the
message, provided the stopFiltering parameter is not set to TRUE.
■ After all the filters have been applied, the FilteringComplete method for
each filter is called to perform any clean up tasks.
■ The Domino Journaling task then processes the message according to the
properties set by the external filters.

Developing external filters

Note: If you plan to supply data to your external filters using XML, be aware that
Microsoft does not support the use of MSXML (Microsoft’s COM-based XML
parser) in .NET applications. This is described in the knowledge base article, KB
815112.

Filters developed using the Domino Filtering API must reference the .NET
assembly:
■ KVS.EnterpriseVault.LotusDominoInterfaces.DLL
You can develop external filters in the programming language of your choice.
For clarity, definitions are given using C#.NET syntax.

For Domino filters, if you want to use the Lotus C API for Lotus Notes/Domino to
access the note, we recommend that you use managed C++. The Lotus C API for
Lotus Notes/Domino is shipped with the Lotus Notes client.
To develop an external filter for Domino journaling, you need to obtain and
install an Enterprise Vault Lotus Domino Journaling license.

Domino filtering registry settings


Filtering for Enterprise Vault Domino Journaling tasks is enabled using registry
settings under the External Filtering key:
Filtering APIs 475
Domino Filtering API

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

Enumerations (Domino filtering)


This section lists the enumerations for the Domino Filtering API.

Message direction enumeration


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

Domino action enumeration


The following enumeration values are defined for DominoAction:
public enum DominoAction
{
NO_ACTION = 0,
ARCHIVE_ITEM = 1,
MARK_DO_NOT_ARCHIVE = 2,
HARD_DELETE = 4,
REQUEST_SHUTDOWN = 5
}

Table 7-6 DominoAction enumeration values

Value Action

NO_ACTION Do not archive, delete or mark the item.

ARCHIVE_ITEM (Default) Archive the item according to the


assigned policy.

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


The Domino Journaling task does not reexamine
marked messages unless the Override setting is
configured.
See “Domino filtering registry settings” on
page 474

HARD_DELETE Hard delete the item without archiving it.


Note that this option requires Enterprise Vault
8.0 SP5 or later.

REQUEST_SHUTDOWN Shut down the archiving task.


Filtering APIs 477
Enumerations (Domino filtering)
478 Filtering APIs
IExternalFilter interface

IExternalFilter interface
The external filter must implement the IExternalFilter interface, which is called
by the archiving task filter controller:
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntax
public interface IExternalFilter

Member summary

Method Description

Initialize Called during the archiving task initialization. The filter should
perform any necessary initialization before item processing begins.

ProcessFilter Called per-item during the archiving process. The ProcessFilter


method is where you process the item to your requirements.

FilteringComplete Called after all filters have been processed for the current item.

Shutdown Called during the archiving task shutdown. The filter should
perform any necessary clean-up tasks.

Requirements
Filtering APIs 479
IExternalFilter :: Initialize

IExternalFilter :: Initialize
This method is called during archiving task initialization.

Syntax
void Initialize();

Remarks
Filters are instantiated at task startup and released at task shutdown.
The filter should perform any necessary initialization before item processing
begins.
480 Filtering APIs
IExternalFilter :: ProcessFilter

IExternalFilter :: ProcessFilter
This method is called per-item during the archiving process. The ProcessFilter
method is where you process the item to your requirements.

Syntax
void ProcessFilter(IArchivingControl archivingControl,
ref bool stopFiltering);

Parameters

IArchivingControl archivingControl Reference to the LotusArchivingControl


interface.

ref bool stopFiltering True value prevents any further filters


from being processed for the current item.

Remarks
The archivingControl reference is used by the filter in the callback to obtain
information about the current item and take appropriate actions.
As the archiving task runs in multiple threads, the external filter must be
written to handle concurrent calls. If the filter accesses a shared resource, it
must use appropriate concurrency protection.

See also
■ “IArchivingControl interface” on page 483
■ “ILotusArchivingControl interface” on page 490
Filtering APIs 481
IExternalFilter :: FilteringComplete

IExternalFilter :: FilteringComplete
This method is called after all filters have been processed.

Syntax
void FilteringComplete();

Remarks
This method can be used to clean up resources used to filter the item.
482 Filtering APIs
IExternalFilter :: Shutdown

IExternalFilter :: Shutdown
This method is called during archiving task shutdown.

Syntax
void Shutdown();

Remarks
The filter should perform any necessary clean-up tasks.
Filtering APIs 483
IArchivingControl interface

IArchivingControl interface
This task filter controller implements the following interfaces:
■ IArchivingControl
■ ILotusArchivingControl
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL
The methods properties of the interfaces enable an external filter to retrieve
and modify properties on the current item.
The ILotusArchivingControl interface is implemented by the Domino archiving
task filter controller, and is passed to the filter on a per-message basis during
the ProcessFilter call. It extends the IArchivingControl interface to provide
access to Domino messages from Domino filters.
See “ILotusArchivingControl interface” on page 490

Syntax
public interface ILotusArchivingControl : IArchivingControl

Member summary

Table 7-7 IArchivingControl properties

Property Read/Write Description

OriginalVaultID Read only Original archive for the current


item.

CurrentVaultID Read/Write Target archive for the current


item.

OriginalRetentionCategoryID Read only Original retention category for


the current item.

CurrentRetentionCategoryID Read/Write Retention category assigned to


current item.

IndexData Read only Metadata added, or to be added,


to the current item.

FilterProperties Read only A collection of properties for the


current item.
484 Filtering APIs
IArchivingControl :: OriginalVaultID

IArchivingControl :: OriginalVaultID
Retrieves the original archive ID for the current item.
This property is read-only.

Syntax
string OriginalVaultID {get;}

Remarks
This property holds the archive ID originally assigned by the archiving task
before any filters where processed. If a filter changes the target archive for the
item, this property will remain unchanged.
Filtering APIs 485
IArchivingControl :: CurrentVaultID

IArchivingControl :: CurrentVaultID
This property retrieves or sets the ID of the archive in which the current item
will be stored.
This property is read/write.

Syntax
string CurrentVaultID {get; set;}

Example
An example value for this property is:
190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1
486 Filtering APIs
IArchivingControl :: OriginalRetentionCategoryID

IArchivingControl :: OriginalRetentionCategoryID
This property holds the original retention category ID for the current item.
This property is read-only.

Syntax
string OriginalRetentionCategoryID {get;}

Remarks
This property holds the Id of the retention category originally assigned by the
archiving task, before any filters where processed. If a filter changes the
retention category for the item, this property will remain unchanged.
Filtering APIs 487
IArchivingControl :: CurrentRetentionCategoryID

IArchivingControl :: CurrentRetentionCategoryID
This property defines the retention category for the current item.
This property is read/write.

Syntax
string CurrentRetentionCategoryID {get; set;}

Remarks
Use this property to set or retrieve the ID of the retention category assigned to
the current item.
An example value is:
18306BF113C2C444096279660836252821b10000EVArchiveSite1
488 Filtering APIs
IArchivingControl :: IndexData

IArchivingControl :: IndexData
This property is an instance of the IIndexMetadata interface, and enables access
to the custom index metadata for the current item.
The property is read only.

Syntax
IIndexMetadata IndexData {get;}

Remarks

See also
■ “IIndexMetadata interface” on page 499.
Filtering APIs 489
IArchivingControl :: FilterProperties

IArchivingControl :: FilterProperties
This property is an instance of the IKeyedList interface, and enables
communication between multiple filters. For example, a filter property can be
set by one filter and queried by another.
The property is read only.

Syntax
IKeyedList FilterProperties {get;}

Remarks
The properties listed are shared across all filters. These properties are not
stored in Enterprise Vault or reset by Enterprise Vault. The properties can be
maintained across multiple messages, if required.

See also
■ “IKeyedList interface” on page 513.
490 Filtering APIs
ILotusArchivingControl interface

ILotusArchivingControl interface
ILotusArchivingControl is derived from the IArchivingControl interface, and
extends the interface to enable filters to access Domino messages.
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL
For details of the properties on the IArchivingControl interface, see
“IArchivingControl interface” on page 483

Member summary

Table 7-8 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).


Filtering APIs 491
ILotusArchivingControl :: Action

ILotusArchivingControl :: Action
This property defines the filtering action for the current message.
The property is read/write.

Syntax
DominoAction Action {get; set;}

Remarks
The filtering action is defined by the DominoAction enumeration. For
DominoAction enumerated values, see
“Domino action enumeration” on page 476.
The default action is to archive the item (ARCHIVE_ITEM enumeration value).
492 Filtering APIs
ILotusArchivingControl :: NoteHandle

ILotusArchivingControl :: NoteHandle
This property retrieves the Lotus C API for Lotus Notes/Domino handle to the
current message.
The property is read only.

Syntax
IntPtr NoteHandle {get;}

Remarks
This handle must not be closed by the filter.
Filtering APIs 493
ILotusArchivingControl :: DatabaseHandle

ILotusArchivingControl :: DatabaseHandle
This property retrieves the Lotus C API for Lotus Notes/Domino handle to the
current database.
The property is read only.

Syntax
IntPtr DatabaseHandle {get;}

Remarks
This handle must not be closed by the filter.
494 Filtering APIs
ILotusArchivingControl :: DatabaseName

ILotusArchivingControl :: DatabaseName
This property retrieves the current Domino journal database path.
The property is read only.

Syntax
string DatabaseName {get;}

Remarks
This path is relative to the Data folder.
Filtering APIs 495
ILotusArchivingControl :: SenderRecipientXML

ILotusArchivingControl :: SenderRecipientXML
This property retrieves an XML document containing the sender and recipient
information for the current message.
The property is read only.

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.
The property value is an XML document representing the sender and recipient
information for the current message, including expanded distribution lists.
This document is described by the following DTD:
<!ELEMENT MSG (RECP, AUTH)>
<!ELEMENT RECP (TO, CC, BCC)>
<!ELEMENT TO (RC*, DL*)>
<!ELEMENT CC (RC*, DL*)>
<!ELEMENT BCC (RC*, DL*)>
<!ELEMENT RC (DN, EA+)>
<!ELEMENT DN (#PCDATA)>
<!ELEMENT EA (#PCDATA)>
<!ELEMENT DL (DN, EA, RC*)>
<!ELEMENT AUTH (FROM, PP)>
<!ELEMENT FROM (DN, EA)>
<!ELEMENT PP (DN?, EA?)>
<!ATTLIST EA TYPE CDATA #REQUIRED>

Example
The following is an example of the SenderRecipientXML document:
<!--The <RECP> element lists all the message recipients in TO, CC,
BCC fields. If distribution lists are present, the name and address
of the distribution list is given in the <DL> element and member
addresses are listed in <RC> elements -->
<MSG>
<RECP>
<TO>
<RC>
<DN>Display Name</DN>
<EA TYPE="SMTP">SMTP_address</EA>
<EA TYPE="NOTES">LotusNotes_address</EA>
</RC>
496 Filtering APIs
ILotusArchivingControl :: SenderRecipientXML

<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>
<!--The <AUTH> element gives the display name, SMTP and Lotus Notes
format addresses for the message author. If the message was sent by
a delegate, the principal person is defined in the <PP> element -->
<AUTH>
<FROM>
<DN>Display Name</DN>
<EA TYPE="NOTES">LotusNotes_address</EA>
</FROM>
<PP/>
</AUTH>
</MSG>
Filtering APIs 497
ILotusArchivingControl :: StoreIdentifier

ILotusArchivingControl :: StoreIdentifier
This property uniquely identifies the message.
The property is read only.

Syntax
string StoreIdentifier {get;}

Remarks
The property is derived from the Universal Note ID (UNID) and Originator ID
(OID) that are assigned by the Domino server.
The UNID and OID are defined as follows:

UNID (Universal Note ID) Identifies all the copies of a note, regardless of
location or time. Every copy of a note has the same
UNID, and the UNID does not change when a note is
modified.

OID (Originator ID) Identifies a particular revision of a note, regardless of


location. Every copy of a note has the same OID, but
the OID changes when the note is modified.
498 Filtering APIs
ILotusArchivingControl :: Direction

ILotusArchivingControl :: Direction
This property indicates the direction in which the message was travelling (in
relation to the domain defined as internal).

Syntax
MSG_DIRECTION Direction {get;}

Remarks
The property value is an enumerated value. For MSG_DIRECTION enumerated
values, see “Message direction enumeration” on page 476.
Filtering APIs 499
IIndexMetadata interface

IIndexMetadata interface
This interface enables the external filter to add properties to the custom index
metadata for the current item, and retrieve additional properties that have been
previously added to the index using Add ().
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntax
public interface IIndexMetadata : IEnumerable

Member summary

Table 7-9 IIndexMetadata properties

Property Read/Write Description

DateTimeUTC Read/Write Whether date and time properties are UTC or local
system time.

Table 7-10 IIndexMetadata methods

Method Description

Count Returns the current count of properties.

Add Add a custom index metadata property to the current item.

Clear Remove all custom index metadata properties from the current item.

ToXML Persists the custom index metadata to XML.

FromXML Loads the custom index metadata from XML.

Remarks
The IIndexMetadata interface inherits from the IEnumerable interface and
hence supports standard enumeration support for the collection of properties.
When enumerating, each property is returned as an instance of the
IIndexProperty interface.
See “IIndexProperty interface” on page 507.
500 Filtering APIs
IIndexMetadata :: ToXML

IIndexMetadata :: ToXML
This method returns the custom index metadata as an XML document.

Syntax
string ToXML(bool formattedLayout);

Parameters

bool formattedLayout If true, the XML returned will be formatted in lines and
indented appropriately.

Remarks
The XML can be loaded into an ISimpleIndexMetadata object, as defined in the
Content Management API.
See “SimpleIndexMetadata object” on page 277.
Filtering APIs 501
IIndexMetadata :: FromXML

IIndexMetadata :: FromXML
This method loads the custom index metadata from an XML document.

Syntax
void FromXML(string xmlIndexMetadata);

Parameters

[in] BSTR xmlIndexMetadata The XML stream to input.

Remarks
Use the Add method to add item specific values.
The XML schema is not published, as the Add method should always be used to
add metadata properties.
Do not change the structure of the XML.
502 Filtering APIs
IIndexMetadata :: Add

IIndexMetadata :: Add
This method adds a property to the custom index metadata for the current item.
The custom index metadata will be added to the archive's item once the item has
been archived.

Syntax
void Add(string propertySet, string propertyName,
string propertyValue, bool propertySearchable,
bool propertyRetrievable);

void Add(string propertySet, string propertyName,


DateTime propertyValue, bool propertySearchable,
bool propertyRetrievable);

void Add(string propertySet, string propertyName,


long propertyValue, bool propertySearchable,
bool propertyRetrievable);

void Add(string propertySet, string propertyName,


ulong propertyValue, bool propertySearchable,
bool propertyRetrievable);

Parameters

string propertySet Name of the property set.

string propertyName Name of the property.

string propertyValue Property value.


DateTime propertyValue
long propertyValue
ulong propertyValue

bool propertySearchable Whether property can be searched for using Search API.

bool propertyRetrievable Whether property can be retrieved and displayed in


search results.

Remarks
The Add method can be called repeatedly to add multiple properties to the
index.
The overloads of the Add method allow the addition of strings, integers or
DateTime values.
Filtering APIs 503
IIndexMetadata :: Add

Properties can be multi-valued. When adding a property, the existence of that


property within the specified property set is checked and, if present, the value is
added as an element of that property.
If the Searchable property is true, the property will be indexed.
If the Retrievable property is true, the property is stored with the item in the
archive. The property information can then be retrieved and displayed later
with the item in search results. The default value is false.
It is good practice to use a named property set in order to avoid name clashes
with other external filter additions. Suitable names would be your company
name or the filter application name. The following property set names are
reserved:
■ Vault
■ EnterpriseVault
■ KVS
■ Veritas
■ Symantec
Property sets do not need to be created before properties are added to them.
When you use Add() to add a property to the index, the property will be added to
the property set specified by propertySet, if the property set exists. If the set
does not exist, it will be created first.
504 Filtering APIs
IIndexMetadata :: Clear

IIndexMetadata :: Clear
This method clears all properties from the IIndexMetadata object for the current
item.

Syntax
void Clear();
Filtering APIs 505
IIndexMetadata :: Count

IIndexMetadata :: Count
This method retrieves the number of properties in the IndexMetadata object for
the current item.

Syntax
int Count();
506 Filtering APIs
IIndexMetadata :: DateTimesUTC

IIndexMetadata :: DateTimesUTC
This property sets or retrieves whether the date and time properties are input
and output in UTC or local system time.

Syntax
bool DateTimeUTC {get; set;}

Remarks
This property sets or retrieves whether the date and time properties are input
and output in UTC or local system time.
Filtering APIs 507
IIndexProperty interface

IIndexProperty interface
The IIndexProperty interface details a a custom index metadata property within
an IIndexMetadata collection.
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntax
public interface IIndexProperty

Member summary

Table 7-11 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);
}
}
508 Filtering APIs
IIndexProperty :: Set

IIndexProperty :: Set
This property holds the name of the property set.
The property is read only.

Syntax
string Set {get;}
Filtering APIs 509
IIndexProperty :: Name

IIndexProperty :: Name
This property holds the name of the custom index property.
The property is read only.

Syntax
string Name {get;}
510 Filtering APIs
IIndexProperty :: Value

IIndexProperty :: Value
This property holds the value of the index property.
The property is read only.

Syntax
System.Object Value {get;}

Remarks
The object will be a string, integer, or date/time value.

Example

C#
IIndexMetadata custProps = archivingControl.IndexMetadata;

foreach(IIndexProperty prop in custProps)


{
if (prop.Searchable && (prop.Value.GetType() ==
typeof(DateTime)))
{
searchableDateProps.Add(prop.Set, prop.Name,
(DateTime)prop.Value);
}
}
Filtering APIs 511
IIndexProperty :: Searchable

IIndexProperty :: Searchable
This property indicates whether the property can be returned in search results
when using the Search API.
The property is read only.

Syntax
bool Searchable {get;}
512 Filtering APIs
IIndexProperty :: Retrievable

IIndexProperty :: Retrievable
This property indicates whether the index property can be retrieved and
displayed with search results when using the Search API.
The property is read only.

Syntax
bool Retrievable {get;}
Filtering APIs 513
IKeyedList interface

IKeyedList interface
This interface enables multiple filters to access a list of filter properties. The
collection allows both random access by index and keyed access using a key
value.
Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntax
public interface IKeyedList : ICollection, IDictionary, IEnumerable

Member summary

Table 7-12 IKeyedList methods

Method Description

Insert Inserts a filter property into the list at the specified position.

RemoveAt Removes a filter property from the specified position in the list.

See also
■ “IArchivingControl :: FilterProperties” on page 489.
514 Filtering APIs
IKeyedList :: Insert

IKeyedList :: Insert
Inserts a filter property into the list at the specified position.

Syntax
void Insert(System.Int32 index, System.Object key,
System.Object value);

Parameters

System.Int32 index The position to insert into the list.

System.Object key The key for the filter property.

System.Object value The value of the filter property.

Remarks
The elements that follow the insertion point are moved down to accommodate
the new element.
If index equals the number of items in the list, then the value is appended at the
end of the list.
An exception is reported if the specified index is out of range.
Filtering APIs 515
IKeyedList :: RemoveAt

IKeyedList :: RemoveAt
Removes a filter property from the list at the specified position.

Syntax
void RemoveAt(Int32 index);

Parameter

Int32 index The position in the list.

Remarks
The elements that follow the removed element move up to occupy the vacated
spot.
An exception is reported if the index is out of range.
516 Filtering APIs
IKeyedList :: RemoveAt
Chapter 8
Search API
This chapter describes the Search API which enables third-party applications to
search the indexes of Enterprise Vault archives.

Introduction to storing and indexing


The Enterprise Vault Storage service accepts items for archiving from the
archiving tasks. If possible, it generates a text or HTML version of each item,
which the Indexing service uses to compile indexing data for the item. The
Storage service compresses and stores the items (and the text or HTML
versions) as savesets in the appropriate archives. Information about each item
that is archived is stored in the vault store database. The Storage service also
responds to requests from the retrieval tasks to restore items.
The Indexing service manages the indexes of archived data to enable users to
search for archived items that they want to retrieve. The role of the Indexing
service can be summarized as follows:
■ On instruction from the Storage service, the Indexing service indexes items
as they are archived. There can be one to many indexes (index volumes) per
archive.
The locations of index files are specified in the Indexing service properties
in the Enterprise Vault Administration Console.
■ In response to search requests from the Enterprise Vault Web access
components, or third-party search applications using the Search API, the
Indexing service searches these indexes and returns information about the
archived items that match the search criteria.
■ The Indexing service ensures that indexes are complete and up to date. If an
index is out of date, the Indexing service automatically updates the index.
In Enterprise Vault you can set the required level of indexing. If required,
different levels can be set for different groups of users. There are three levels of
518 Search API
Introduction to storing and indexing

indexing: brief, medium and full. Each level extends the searches that users can
perform:
■ Brief indexing. This enables users to search on attributes of an archived
item such as Author, Subject, Recipients, Created Date, File Extension,
Retention Category and so on. With brief indexing, the content of the item
is not indexed.
■ Medium indexing. This enables users to search attributes, as for brief
indexing, as well as searching content. It does not provide phrase searching
in content.
■ Full indexing. This enables users to search as for medium indexing, and also
provides searching for phrases in content.
Obviously, the more information that is indexed, the more disk space is required
for the index.
For example, for brief indexing, the index size is approximately 3% of the size of
the data that is indexed. For medium indexing, the figure is approximately 8%
and for full it is approximately 12% (depending on the type of documents).
The level of indexing, and when an item is indexed for a particular archive can
be controlled using the Content Management API.
See “IArchive :: IndexLevel” on page 136.
See “IArchive :: IndexUrgency” on page 134.
The content and attachments are indexed if there is a content converter
available for the file type, and the converted content does not exceed the
configured size limits (by default, 30 MB after conversion to HTML or text).
If the content cannot be indexed, a 'content missing' reason is indexed using the
"comr" property.
See “System properties” on page 664.
See “ETruncationReason enumeration” on page 536.

Enterprise Vault indexes


Each archive index comprises one or more sequential index volume sets. An
index volume set contains an index volume. (Currently, an index volume set can
contain only one index volume). Each index volume contains index entries for
the items stored in the archive. Each Enterprise Vault archive can have one or
more associated index volumes.
When an index volume is full, the Enterprise Vault Indexing service
automatically creates a new index volume (in a new index volume set). The
Enterprise Vault administrator uses the Enterprise Vault Administration
Console to configure the physical locations to be used by the Indexing service
when creating new indexes and index volumes.
Search API 519
Using the Search API

Figure 8-1 An archive index

Typically, user mailbox indexes require only a single volume. Indexes for larger
archives, such as file system archives and journal archives, are quite likely to
have multiple volumes.
When a user or application performs a search on an archive, the search is
performed on index volumes associated with the archive, not the archive itself.
For more information on Enterprise Vault indexes, see “About index volume sets
and volumes” on page 659.

Using the Search API


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

■ IndexVolumeSets object enables access to a collection of IndexVolumeSet


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

Constructing a search query


Take for example the following query expressed in words:
The email Author is John Doe or Alan Smith, and its Subject contains the
phrase “Financial Reports”, and its Document Date is earlier than 17 May
2001.
This query can be broken down into its constituent parts.
There are three properties (in a SQL query, these would be the fields or columns
in a table):
■ Author
■ Subject
■ Document Date
Search API 521
Using the Search API

In order to find the correct emails, we need to attach search conditions to each
of these properties:
■ Author - is either John Doe or Alan Smith
■ Subject - this must contain the phrase "Financial Reports"
■ Document Date - this must be earlier than 17th May 2001
The words in italics are the operators within the query.
The Search API does not have a "less than" or "greater than" operator so it will
be necessary to use a Range for the Document Date:
■ Document Date - this must be between 1st January 1900 and 16th May 2001
The query can now be rewritten as follows:
Find All emails where Author = ("Fred Bloggs" or "John Smith") and (Subject
contains the phrase "Financial Reports") and (Document Date is between
"1st January 1900 and 17th May 2001")
The property name, for example, Author, would normally be one of the
Enterprise Vault system index property names.
“System properties” on page 664.
In addition to system property names, custom properties defined by the user can
also be used.
Any number of terms can be added to a SearchQuery object. By default, they are
all combined using the AND operator. Different operators can be specified using
the Combine, AddOp, or AddQuery methods:
■ Combine takes two SearchQuery objects, each containing one or more terms
and an operator. The method creates a new search query containing all the
terms in both objects, combined with the specified operator. This new query
can be used in a further Combine operation to create searches of arbitrary
complexity.
■ AddQuery is similar to Combine, but instead of taking two SearchQuery
objects and combining them to create a third, it incorporates the second
object into the first.
■ AddOp combines one or more of the terms previously added to the
SearchQuery object with the specified operator.
All three methods can be used interchangeably, and at different stages in the
construction of a single search query. Which approach you use depends solely
on your preference.
To start to construct the earlier example query, you use the AddTerm method of
the ISearchQuery interface. AddTerm has the parameters: property, value,
search query flag. If SetTerm is used, it clears out any previous query.
522 Search API
Using the Search API

The search query flag determines how to process individual terms added to a
search query.
See “ESearchQueryFlags enumeration” on page 533.
The first term could be added to the query as follows:
AddTerm(IndexPropAUTH, "John Doe", ESQPhrase);
Then the second term could be added to the query as follows:
AddTerm(IndexPropAUTH, "Alan Smith", ESQPhrase);
Now the above terms need to be combined using the OR operator. This is done
using the AddOp method:
AddOp(ESQor, ESQBinary)
The query is built up using a reverse polish system; the operator is applied to the
previous x 'objects' to create a new one, where x is determined by the value of the
second parameter to AppOp, the search object scope.
See “ISearchQuery :: AddOp” on page 554.
The operator itself can be obtained from the ESearchQueryOperators
enumeration.
See “ESearchQueryOperators enumeration” on page 534.
In the example query, two more terms can now be added; the Subject term and
the date range term:
AddTerm(IndexPropSubj, "Financial Results", ESQPhrase)
AddRange(IndexPropDate, 1st January 1900, 16th May 2001, ESQany)
(In reality, you would use the appropriate DateTime object for the programming
language being used).
The three parts of the query need to be combined using the AND operator. (The
first part is the result of the first call to AddOp. The second and third parts are
the terms being added in this operation):
AppOp(ESQand, ESQQternary)
The resulting query now represents the original query that was expressed in
words. The constructed query can be used by the Search method of the
IndexSearch2 interface to search the index of an archive.
The search query operator, ESQfilter, is a special operator for performing
complex searches, such as those required by the Enterprise Vault Compliance
and Discovery Accelerator products.
See “ESQfilter searches” on page 522.

ESQfilter searches
ESQfilter is similar to ESQ but more powerful. The following summarizes how
this operator works:
Search API 523
Using the Search API

■ A search is performed using the first query. This searches top-level items
only. (For example, this term could specify a date range to be searched).
■ A separate search is performed using subsequent queries. This searches
both top-level items and attachments. (For example, words in message
subject or content).
■ The results are compared and any result from the second search which has
an associated top-level item that matches a result from the first query
search is added to the results.
Only top-level items are returned in results; if a search query is satisfied in an
attachment, the associated top-level item is returned in results.
Note that the Options setting of the Search method is ignored if the search uses
the operator ESQfilter.
This type of search is particularly efficient for compliance or discovery type
searches. For optimum performance, it should be used together with the
ItemGranularityOnly index schema.
See “About index schemas” on page 660.

Special characters in search queries


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

There must be at least three other characters before a wildcard.


Finally, words like "and" and "or" have no special meaning in query values (and
cannot be given any special meaning). They will be searched for like any other
word. So, for example, to search for documents containing both "financial" and
"hint", search for the string "financial hint" using ESQall.

Performing a search
The index is searched using the methods and properties of the IIndexSearch2
interface.
Before initiating the search, set requirements for the search and search results
using methods and properties of the IIndexSearch2 interface:
■ SelectArchive method. Use this to specify the index to search. The index is
identified using the Id of the associated archive.
You can use the vault store and archive enumeration functionality in the
Content Management API to find the target archive.
The Id of an archive can also be discovered using the Enterprise Vault
Administration Console:
■ In the Enterprise Vault Administration Console, double-click the
archive to display the properties dialog and click the Advanced tab. The
archive Id is displayed on the advanced properties page.
■ SelectIndexVolumeSet method. If you do not want Enterprise Vault to
perform a federated search across multiple index volumes, use this method
to set the Id of the archive's index volume set to search.
See “Searching indexes with multiple volume sets” on page 525
■ Options property. Use this to set the required granularity of the search:
■ roItemGranularity. Only top-level items are searched, not attachments.
■ roAttachmentGranularity. Both top-level items and attachments are
searched.
Note that the Options setting is ignored if the search uses the operator
ESQfilter.
See “ESQfilter searches” on page 522
■ AdditionalResultsProperties property. Use this to set the required
properties to be returned in results. (Use AdditionalResultsProperties in
preference to the ResultsPropertySet property).
■ SortBy property. Use this to specify the required sort order of the results.
After setting the required properties, you initiate the search using the Search
method.
Search API 525
Using the Search API

The query is passed to this method as a query string. In most cases this query
string is created using the methods of ISearchQuery2 interface. The Query
property returns the string that has been constructed and can be passed to the
Search method.
Use the Search method parameters, startResult and maximumResults to specify
the number of results to return at one time. This enables you to "page" through
the results.
The output from a search is a pointer to a SearchResults object, which provides a
structured way to access the results. The object provides standard collection
support enabling iterative operations on the results in the collection, such as
"for each" in Visual Basic, and .NET managed code.

Concurrent searches
To optimize performance, applications using multiple search threads should
search different archives or index volume sets.

Searching indexes that are changing during the search


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

Searching indexes with multiple volume sets


Enterprise Vault automatically performs a federated search across multiple
index volumes if the following criteria are met:
■ An index volume set is not selected using SelectIndexVolumeSet.
526 Search API
Using the Search API

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

Creating multiple index volume sets for testing


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

Setting Setting Content Description


name location

AVSMaxLoc HKEY_LOCAL_MACHINE DWORD. Maximum location value


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

To create multiple volume index sets for testing


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

Processing the search results


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

■ The search query includes the ESQfilter operator. Attachments are


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

Enterprise Vault index properties


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

Search API Example


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

of search results. If the search is not a federated search, then this second
parameter is zero.

void SearchArchive(string archId, int maxSearchResults)


{

IIndexSearch2 search = (IIndexSearch2) new IndexSearch2();

//First select the archive


search.SelectArchive(archId);

//although the prefered approach is to do a non-federated search this sample


//code will demonstrate both non-federated and federated
//first get the IndexVolumeSets for the archive
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;

long count = volSets.Count;

//use this count value to see which approach to take


if (count > search.MaxSearchIndexVolumeSets)
{
//do non-federated search
foreach (IIndexVolumeSet volSet in volSets)
{
search.SelectIndexVolumeSet(volSet.Identity);
DoSearch(search, 0);
}
}
else
{
DoSearch(search, maxSearchResults);
}
Marshal.FinalReleaseCOMObject(search);
}

The DoSearch method, called from 'SearchArchive' performs the actual search
on the entire archive, or the specifed Index Volume Set, depending on whether
or not the search is a federated search.
The search will filter on a range of archived dates, a phrase in the subject,
greater than zero attachments and the author.
The retrieved properties are created date, content (first 150 characters only),
saveset Id, number of attachments, subject, TO:recipient, CC:recipient,
BCC:recipient.
Typically the property values in the query would be supplied using a GUI or a
command line. However, for the purposes of this example, they are supplied in
the code.
530 Search API
Using the Search API

void DoSearch(IIndexSearch2 search, int maxSearchResults)


{

ISearchQuery2 query = (ISearchQuery2) new SearchQuery2();

DateTime dtFrom = new DateTime(2007, 1, 1);


DateTime dtTo = new DateTime(2007, 12, 31);

query.SetRange("adat", dtFrom, dtTo, (int)ESearchQueryFlags.ESQany);


query.AddRange("natc", 0, 10000, (int)ESearchQueryFlags.ESQany);
query.AddTerm("subj", "a phrase in the subject",
(int)ESearchQueryFlags.ESQphrase);
query.AddTerm("auth", "joe.user", (int)ESearchQueryFlags.ESQexact);
query.AddOp((int)ESearchQueryOperators.ESQand, 4);

search.SortBy = "snum";

//if this is a federated search then set the maximum number of search
//results per index volume set
//if this is not a federated search then 'maxSearchResults' will be 0 and
'MaxSearchResultsPerVolumeSet' will not be used.
if (maxSearchResults > 0)
search.MaxSearchResultsPerVolumeSet = maxSearchResults;

//we are going to search top level items only


search.Options = (int)EOptionsFlags.roItemGranularity;

//As the preferred method is to explicitly state which properties to


//retrieve, first set IIndexSearch2::ResultsPropertySet to Empty.
search.ResultsPropertySet = (int)EPropertySet.psEmpty;
search.AdditionalResultsProperties = "date ssid natc subj cont
reto recc rbcc";

int start = 1; //this is the index number into the results from which to
start returning the result set
int count = 0;

ISearchResults2 results = null;

do
{
results = (ISearchResults2)search.Search(query.Query, start, 500, "");

if (results.InSync == true)
{

if (results.TruncationReason == ETruncationReason.trNone)
{
//make sure that date time properties are returned as local
//system time not UTC
results.DateTimesUTC = false;
Search API 531
Using the Search API

foreach (ISearchResult2 result in results)


{
DateTime createdDate = (DateTime)result.Prop("date");
string ssid = (string)result.Prop("ssid");
int numAttach = (int)result.Prop("natc");
string subj = (string)result.Prop("subj");
string reto = (string)result.Prop("reto");
string rbcc = (string)result.Prop("rbcc");

//do something with the results


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

start += 500;
}
while (count != 0);

Marshal.FinalReleaseCOMObject(query);

}
Search API 533
Constants and enumerations

Constants and enumerations


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

Index Property constants


When using the Search API, Enterprise Vault property names are defined as
constants, where IndexPropXXXX is the constant for the property name, xxxx, in
Table B-1 on page 664. For example, IndexPropSUBJ is the constant for the
Enterprise Vault defined property, "subj", and IndexPropRCAT is the constant
for the Enterprise Vault system property, "rcat".

ESearchQueryFlags enumeration
ESearchQueryFlags specify how to process individual terms added to a search
query (for example, using AddTerm).

Note: From Enterprise Vault 10, the Search API will not support the following
search operators for newly indexed items:

ESQBeginany begins with any of

ESQBegins begins with phrase

ESQExactany is exactly any of

ESQEndsany ends with any of

ESQEnds ends with phrase

ESQAutowild automatically add wildcard to end of all words

Using these search operators against items that were indexed using Enterprise
Vault 9 or earlier will continue to be supported.

enum ESearchQueryFlags
{
// Exactly one of these must be present (default is ESQany)
ESQany = 0, // Contains any of the words
ESQall = 1, // Contains all the words
ESQallnear = 2, // Contains all the words, near each other
(within 10 words)
ESQphrase = 3, // Contains all the words, in order (a phrase)
ESQbeginany = 4, // Begins with any of the words
ESQbegins = 5, // Begins with all the words in order (a phrase)
ESQexactany = 6, // Field exactly matches any of the words
ESQexact = 7, // Field exactly matches all the words, in order
534 Search API
Constants and enumerations

ESQendsany = 8, // Ends with any of the words


ESQends = 9, // Ends with all the words in order (a phrase)
ESQmatchmask = 15, // Mask to isolate above values from
flags below
// Zero or more of the following may be present
ESQrank = 64, // Use words for results ranking
ESQusermask = 1048575 // User must not set bits outside this mask
};
By default indexes are built so that they do not support case sensitive searching.
This is to minimize the index storage footprint.
The specified operator applies to the terms or ranges already present in the
object, using a Reverse Polish scheme. Conceptually, the specified number of
terms is removed from the query, and replaced with the result of combining all
the terms with the specified operator. This result can then be combined with
other terms or intermediate results by a subsequent AddOp method.

ESearchQueryOperators enumeration
ESearchQueryOperators specify the operator to use. These operators can be
used with the AddOp, Combine and AddQuery methods.
enum ESearchQueryOperators
{
ESQand = 0,
ESQor = 1,
ESQandnot = 2,
ESQfilter = 3
};
Using ESQfilter will only return hits on top-level documents. The search finds
items that match the first query and which also match, or have a cover note or
attachment that matches, all the other queries.

ESearchOperatorScope enumeration
ESearchOperatorScope defines the number of operands on which an operation
is to be performed.
enum ESearchOperatorScope
{
ESQdefault = 0,
ESQscopeall = 1,
ESQbinary = 2,
ESQternary = 3
};
If no value is given, the default is for the operator to be binary (two operands).
The ESearchOperatorScope is a useful extension to the "Reverse Polish" scheme
used by the AddOp method, enabling a single operator to have more than two
Search API 535
Constants and enumerations

operands. For more than three operands, there are no symbolic constants, so the
required number should be specified.
Note the value of the scope is the number of operands, not the number of
operations (which, when thinking of conventional binary operators, would be
one less than the number of operands).

EOptionsFlags enumeration
EOptionsFlags defines the granularity of searches.
enum EOptionsFlags
{
roItemGranularity = 0x00000000,// default
roAttachmentGranularity = 0x00000001,
};
This setting is ignored if the search uses the operator ESQfilter.
Using roItemGranularity, only top-level items are searched (not attachments).
Using roAttachmentGranularity, both top-level items and attachments are
searched.

EPropertySets enumeration
EPropertySets are the predefined property sets that can be requested in search
results.
As the predefined property sets may change at future releases, we recommend
that you set this property to 0 (psEmpty) and use “IIndexSearch2 ::
AddAdditionalResultsProperty” and “IIndexSearch2 ::
AddAdditionalResultsCustomProperty” to set the required properties to be
returned in the results set.
enum EPropertySets
{
psEmpty = 0,
psWABrief = 1,// default
psWAMedium = 2,
psWAFull = 3,
psAEMailbox = 4,
psAEFSA = 5,
psAESPS = 6,
psAEMultiFolders = 7,
psCompliance = 8,
psItemIds = 9,// Min set of ids needed to retrieve the item.
psAEShared = 10,
psAEJournal = 11,
psAEPublicFolder = 12,
psAESharePoint = 13
};
536 Search API
Constants and enumerations

ETruncationReason enumeration
ETruncationReason explains why not all search results have been returned.
enum ETruncationReason
{
trNone = 0,
trResultLimitExceeded = 1,
trTimeoutExpired = 2,
trAdminResultLimitExceeded = 4,
trAdminTimeoutExpired = 8,
trNotSearchedOrFailedVolumes = 16,
trItemsOrContentMissing = 32,
trWidthNormalizationRequired = 64
};
trNotSearchedOrFailedVolumes applies to federated searches only. The
index contents for the whole archive cannot be listed. This can occur when one
or more of the index volume sets are in a failed state; they could be, for example,
offline or corrupt.
trItemsOrContentMissing indicates that index entries are missing for items
or content in archive.
trWidthNormalizationRequired is set for old indexes where character
width normalization was not applied to East Asian languages.
See http://entsupport.symantec.com/docs/289566

EXMLResultsFormatOptions enumeration
EXMLResultsFormatOptions enumerates the XML format option values.
Currently there is only one value:
enum EXMLResultsFormatOptions
{
xoNone = 0x00000000// default
};
Search API 537
SearchQuery object

SearchQuery object
The SearchQuery object implements the following interfaces:
■ ISearchQuery
■ ISearchQuery2 (default)
These interfaces are used to build up a search query. Some additional methods
have been introduced in ISearchQuery2, which inherits from ISearchQuery.
You need to get a pointer to an instance of ISearchQuery2, as this is marked as
the default.

Syntax
interface ISearchQuery2 : ISearchQuery : IDispatch

Member summary

Property Read/Write Description

ISearchQuery :: Query Read/Write The search query string.

Method Description

ISearchQuery :: Clear Discards the query currently being constructed in


the object (if any), and resets the object so that it is
ready for a new query.

ISearchQuery :: SetTerm Implements Clear, followed by AddTerm.

ISearchQuery :: AddTerm Adds a search term to the query.

ISearchQuery :: SetRange Implements Clear followed by AddRange.

ISearchQuery :: AddRange Adds a date or integer range to the query.

ISearchQuery :: SetProperty Implements Clear followed by AddProperty.

ISearchQuery :: AddProperty Adds a property to the query.

ISearchQuery :: AddOp Adds an operation to the query.

ISearchQuery :: Combine Combines two search queries with an operator.

ISearchQuery :: AddQuery Similar to combine, but combines a query with the


query already in the object.
538 Search API
SearchQuery object

Method Description

ISearchQuery2 :: SetPropertyRange Equivalent of SetRange method. Enables use of


date and integer ranges for custom properties in
queries.

ISearchQuery2 :: AddPropertyRange Custom property equivalent of AddRange method.


Enables use of date and integer ranges for custom
properties in queries.

Remarks
As these interfaces are ultimately derived from IDispatch, they can be used by
scripting languages.
Use the methods to create a query that can be used to search the index of an
archive, and return the values of specified properties as results.
A query consists of a number of terms, combined with different operators.
The Query property enables the query to be returned as a string (so that it can
then be used by the Search method), or to be set using a text string.

Requirements
See “Programming notes” on page 46.

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 KVS.EnterpriseVault.Interop

Example
The object 'query' constructed here will be used in the most of the following
examples. It is shown here as a private class data member.
Search API 539
SearchQuery object

C#
public class SampleSearchClass
{
private ISearchQuery2 query = (ISearchQuery2)
new SearchQuery();
//rest of the class
540 Search API
ISearchQuery :: Query

ISearchQuery :: Query
The Query property is the default property. It returns a string containing the
query previously constructed.
The property is read/write.

Syntax
HRESULT Query([out, retval] BSTR* pbsQuery);
HRESULT Query([in] BSTR bsQuery);

Parameters

[out, retval] BSTR* pbsQuery Pointer to a string (BSTR) that will contain the
query held in this object.

[in, string] BSTR bsQuery String (BSTR) containing the query with which
to initialize the object.

Remarks
This property returns the query string that has been constructed using the
other ISearchQuery2 methods.

Return value

rvS_OK Success.

Example
This method is often used in conjunction with IIndexSearch2::Search where it
provides the value for the first parameter, the search query.

C#
ISearchResults2 results2 = (ISearchResults2)search.Search(query.Query, 1, 100, "");
Search API 541
ISearchQuery :: Clear

ISearchQuery :: Clear
This method discards the query currently being constructed in the object (if
any), and resets the object so that it is ready to build a new query.

Syntax
HRESULT Clear([out, retval] BSTR* pbsQuery);

Parameters

[out, retval] BSTR* pbsQuery A pointer to a string (BSTR) that contains the
contents of the query string before it was cleared
out.

Remarks
Clears out the string containing the query that has been constructed so far.

Return value

rvS_OK Success.

Example
In this example the previous query is stored in the string 'oldQuery'.

C#
//save the query that is being cleared out
string oldQuery = query.Clear();
542 Search API
ISearchQuery :: SetTerm

ISearchQuery :: SetTerm
This method is used to clear the current query object, reset it and add a new
term (property) to the query. This is equivalent to calling the Clear method and
then calling the AddTerm method.

Syntax
HRESULT SetTerm([in, string] const BSTR bsProp,
[in] VARIANT vVal,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsProp The name of the property to be


searched for.

[in] VARIANT vVal VARIANT containing value for which


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

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the terms added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string (BSTR) that contains


the current value of the query string
after this method has returned.

Remarks
If the bsProp parameter is left empty, then all indexed properties are searched
for the value. This is really only useful for string values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. This would be specified using the format:
propertySet.propertyName
If the custom index property is a member of the global property set, then the
property set name is omitted.
The parameter lFlags must contain one value from “ESearchQueryFlags
enumeration” on page 533. This value may be bitwise OR'd (C++ operator ‘|’)
with one or more values from the extended values.
Search API 543
ISearchQuery :: SetTerm

Return value

rvS_OK Success.

Example
In this example a query is constructed that will find all items where the subject
contains the phrase 'some subject', and the number of attachments is 1. In this
example the return value is not used.

C#
//search for an item where the subject contains the phrase "some subject"
query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);
//search for an item with 1 attachment
query.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);
//now we AND the 2 terms so that both terms must be satisfied before returning a result
query.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

See also
■ “ISearchQuery :: AddTerm” on page 544
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
544 Search API
ISearchQuery :: AddTerm

ISearchQuery :: AddTerm
This method is used to add a new term (property) to the query.

Syntax
HRESULT AddTerm([in, string] const BSTR bsProp,
[in] VARIANT vVal,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

Table 8-1 AddTerm method parameters

Parameter Description

[in, string] const BSTR bsProp The name of the property in which to
search for the value.

[in] VARIANT vVal VARIANT containing value for which to


search. This can be a string, date or
integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the terms added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the


current value of the query string after
this method has returned.

Remarks
If the bsProp parameter is left empty, than all indexed properties are searched
for the value. This is really only useful for string values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. This would be specified using the format:
property_set_name.property_name
If the custom index property is a member of the global property set, then the
property set name is omitted.
Search API 545
ISearchQuery :: AddTerm

The parameter lFlags must contain one value from table “ESearchQueryFlags
enumeration” on page 533, this value may be bitwise or'd (C++ operator ‘|’) with
one or more values from the extended values.

Return value

rvS_OK Success.

Example
In this example a query is constructed that will find all items where the subject
contains the phrase 'some subject' and the number of attachments is 1. In this
example the return value is not used.

C#
//search for an item where the subject contains the phrase "some subject"
query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);
//search for an item with 1 attachment
query.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);
//now we AND the two terms so that both terms must be satisfied before returning a
result
query.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

See also
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
■ “ISearchQuery :: SetTerm” on page 542
■ “ISearchQuery :: AddProperty” on page 552
546 Search API
ISearchQuery :: SetRange

ISearchQuery :: SetRange
This method is used to delete all queries in the query object, reset the object and
add a date or numeric (integer) range to the query being built in the object. This
is equivalent to calling Clear then AddRange.

Syntax
HRESULT SetRange([in, string] const BSTR bsProp,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsProp The name of the property in which to
search for the value.

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

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the range added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the


current value of the query string after
this method has returned.

Remarks
This method can only be used with date or integer values. Currently date values
are always treated as local system date/time values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. This would be specified using the format:
propertySet.propertyName
If the custom index property is a member of the global property set, then the
property set name is omitted.
Search API 547
ISearchQuery :: SetRange

vVal1 and vVal2 must be the same type.


The parameter lFlags must contain one value from “ESearchQueryFlags
enumeration” on page 533. Currently, however, none of the Search Query Flags
has any effect on range searches.

Return value

rvS_OK Success.

Example
This example builds a query that will find items archived between 01/01/2008
and 21/10/2008 inclusive, or that have less than five attachments.

C#
//search for all items archived between 01/01/2008 and 31/10/2008 inclusive
DateTime from = new DateTime(2008, 1, 1);
DateTime to = new DateTime(2008, 10, 31);
query.SetRange("adat", from, to, (int)ESearchQueryFlags.ESQany);
//search for items with less than 5 attachments
query.AddRange("natc", 0, 4, (int)ESearchQueryFlags.ESQany);
//OR the 2 terms together so the result set will contain items that fall into one or
the other (or both) ranges
query. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);

See also
■ “ISearchQuery :: AddRange” on page 548.
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
548 Search API
ISearchQuery :: AddRange

ISearchQuery :: AddRange
This method is used to add a date or numeric integer range to the query being
built in the object.

Syntax
HRESULT AddRange([in, string] const BSTR bsProp,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsProp The name of the property in which to
search for the value.

[in] VARIANT vVal1 The upper or lower boundary of the


range. This can be date or integer.

[in] VARIANT vVal2 The upper or lower boundary of the


range. This can be date or integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the range added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the


current value of the query string after
this method has returned.

Remarks
This method can only be used with date/time or integer values.
Currently, date values are always treated as local system date/time values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. This would be specified using the format:
property_set_name.property_name
If the custom index property is a member of the global property set, then the
property set name is omitted.
vVal1 and vVal2 must be the same type.
Search API 549
ISearchQuery :: AddRange

The parameter lFlags must contain one value from “ESearchQueryFlags


enumeration” on page 533. Currently, however, none of the Search Query Flags
has any effect on range searches.

Return value

rvS_OK Success.

Example
This example builds a query that will find items archived between 01/01/2008
and 21/10/2008 inclusive, or that have less than five attachments.

C#
//search for all items archived between 01/01/2008 and 31/10/2008 inclusive
DateTime from = new DateTime(2008, 1, 1);
DateTime to = new DateTime(2008, 10, 31);
query.SetRange("adat", from, to, (int)ESearchQueryFlags.ESQany);
//search for items with less than 5 attachments
query.AddRange("natc", 0, 4, (int)ESearchQueryFlags.ESQany);
//OR the 2 terms together so the result set will contain items that fall into one or
the other (or both) ranges
query. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);

See also
■ “ISearchQuery :: SetRange” on page 546.
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
550 Search API
ISearchQuery :: SetProperty

ISearchQuery :: SetProperty
This method clears all queries from the query object, resets the object, and adds
a custom property that can be used for searching.
This is equivalent to calling Clear then AddProperty.

Syntax
HRESULT SetProperty([in, string] const BSTR bsPropSet,
[in, string] const BSTR bsProp,
[in] VARIANT vVal,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsPropSet Name of the property set.

[in, string] const BSTR bsProp The name of the custom property to
search for.

[in] VARIANT vVal VARIANT containing value to search for.


This can be a string, date or integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the range added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string containing the query


as it stands after this method returns.

Remarks
Note that SetTerm can also be used to set a term for a custom property using the
propertySet.propertyName format.
SetProperty method is very similar to SetTerm, but as it requires both a
property set and property name, it can only be used to add custom properties.

Return value

rvS_OK Success.
Search API 551
ISearchQuery :: SetProperty

Example
It is assumed that a custom property "Type", belonging to the property set
"Instrument", has been added to archived items.
Two queries are constructed in this sample; the first searches for all queries
with the custom property Instrument.Type = 'Guitar. The second searches for
all items where the retention category = 'Business'.
The two queries are combined to form one query that searches for all items
where Instrument.Type is 'Guitar' and retention category is not 'Business'.

C#

//search for items with custom property value `Guitar'


string qry1 = query.SetProperty("Instrument", "Type", "Guitar", (int)
ESearchQueryFlags.ESQexact);
//search for items with a retention category of "Business"
string qry2 = query.SetTerm("rcat", "Business", (int)(ESearchQueryFlags.ESQexact);
//combine the 2 queries so that the result set contains items that contain `Guitar' in
the custom property Instrument.Type and that have a retention category that is not
`Business'
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);

See also
■ “ISearchQuery :: SetTerm” on page 542.
■ “ISearchQuery :: AddProperty” on page 552.
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
552 Search API
ISearchQuery :: AddProperty

ISearchQuery :: AddProperty
This method adds a custom property to the query being built in the object and
which can be used for searching.

Syntax
HRESULT AddProperty([in, string] const BSTR bsPropSet,
[in, string] const BSTR bsProp,
[in] VARIANT vVal,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsPropSet Name of the property set.

[in, string] const BSTR bsProp The name of the custom property to
search for.

[in] VARIANT vVal VARIANT containing value for which for


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

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the range added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string containing the query


as it stands after this method returns.

Remarks
This method is very similar to AddTerm, but with both a property set and
property name being included as parameters. This means that it can only be
used to add custom properties.

Return value

rvS_OK Success.
Search API 553
ISearchQuery :: AddProperty

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)(
ESearchQueryFlags.ESQexact);
//combine the 2 queries so that the result set contains items that contain `Guitar' in
the custom property Instrument.Type and "red" in Instrument.Colour"
query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQand);

See also
■ “ISearchQuery :: AddTerm” on page 544.
■ “ISearchQuery :: SetProperty” on page 550.
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
554 Search API
ISearchQuery :: AddOp

ISearchQuery :: AddOp
This method is used to add an operator to the query in order to combine
previously defined terms.

Syntax
HRESULT AddOp([in] const long lOp,
[in, defaultvalue(0)] const long lScope,
[out, retval] BSTR* pbsQuery);

Parameters

[in] const long lOp The operator to use.


See “ESearchQueryOperators
enumeration” on page 534.

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


See “ESearchOperatorScope
enumeration” on page 534.

[out, retval] BSTR* pbsQuery Pointer to string that will contain the
value of the query after this operator
has been added.

Remarks
This method combines the previous x properties by using the operator defined
in the first parameter, where x is the value given in the second parameter.
An example of an operator is 'AND' or 'OR'.
This method does not check the validity of the value passed to the first
parameter, so an error will only be reported when Search is called.
This method can be called successively in order to build up the query.

Return value

rvS_OK Success.
Search API 555
ISearchQuery :: AddOp

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"
query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);
//search for an item with 1 attachment
query.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);
//now we AND the 2 terms so that both terms must be satisfied before returning a result
query.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);
556 Search API
ISearchQuery :: Combine

ISearchQuery :: Combine
This method clears the current query in the object and then adds queries from
two other query objects. These are combined using the specified operator.

Syntax
HRESULT Combine([in, string] const BSTR bsQuery1,
[in, string] const BSTR bsQuery2,
[in] const long lOp,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsQuery1 First query to add.

[in, string] const BSTR bsQuery2 Second query to add.

[in] const long lOp The operator to use.


See “ESearchQueryOperators enumeration”
on page 534.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the query that
results from this method.

Remarks
This method combines two search queries. Each of the search queries is the
Query property of another SearchQuery object.
No check is made to ensure that the two strings are correctly-formed query
strings. Similarly, the lOp parameter is not checked to make sure that it is a
valid operator.
If any of these parameters are incorrect, an error is not reported until the query
string is parsed.

Return value

rvS_OK Success.
Search API 557
ISearchQuery :: Combine

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)(
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);
558 Search API
ISearchQuery :: AddQuery

ISearchQuery :: AddQuery
This method is used to combine a query from another query object with the
query in the current object, using the specified operator.

Syntax
HRESULT AddQuery([in, string] const BSTR bsQuery1,
[in] const long lOp,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsQuery1 String containing the query to combine with the
one in the current object.

[in] const long lOp The operator to use.


See “ESearchQueryOperators enumeration” on
page 534.

[out, retval] BSTR* pbsQuery Pointer to a string that will contain the resulting
query string.

Remarks
Combines a search query, which is assumed to be the Query property of another
SearchQuery object, with the query string of this object.
No check is made to ensure that the new string is correctly formed. Similarly,
the lOp parameter is not checked to ensure that it is a valid operator.
If any of these parameters are incorrect, an error is not reported until the query
string is parsed.

Return value

rvS_OK Success.

Example
In this example it is assumed there is already a populated ISearchQuery object,
query2.
This example adds a new query string to this existing query.
Search API 559
ISearchQuery :: AddQuery

C#
string qry = query.SetTerm("cont", "-white blue.red",
(int)ESearchQueryFlags.ESQany);
query2.AddQuery(qry, (int)ESearchQueryOperators.ESQand);
560 Search API
ISearchQuery2 :: SetPropertyRange

ISearchQuery2 :: SetPropertyRange
This method is used to add a date or integer range to a query that specifies a
custom index property. The method deletes any queries in the current object,
resets it, and adds the specified information as part of a new query.
Custom index properties can be added to index entries using the
SimpleIndexMetadata API.
“SimpleIndexMetadata object” on page 277.

Syntax
HRESULT SetPropertyRange([in, string] const BSTR bsPropSet,
[in, string] const BSTR bsProp,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsPropSet String containing the name of the
property set.

[in, string] const BSTR bsProp String that contains the property name.

[in] VARIANT vVal1 VARIANT specifying the first value in the


range.

[in] VARIANT vVal2 VARIANT specifying the second value in


the range.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the range added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that will contain the
query string formed by this method.

Remarks
This method can only be used with date or integer values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. bsPropSet specifies the property set.
Search API 561
ISearchQuery2 :: SetPropertyRange

vVal1 and vVal2 must be the same type.


The parameter lFlags must contain one value from table “ESearchQueryFlags
enumeration” on page 533. Currently, however, none of the Search Query Flags
has any effect on range searches.
Note that SetRange can also be used with custom properties, using the
propertySet.propertyName format.

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,
(int)ESearchQueryFlags.ESQany);

See also
■ “Adding custom index metadata” on page 55
■ “ISearchQuery :: SetRange” on page 546
■ “ISearchQuery :: AddRange” on page 548
■ “ISearchQuery2 :: AddPropertyRange” on page 562
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
562 Search API
ISearchQuery2 :: AddPropertyRange

ISearchQuery2 :: AddPropertyRange
This method is used to add a date or integer range to a query that specifies a
custom index property.
Custom index properties can be added to index entries using the
SimpleIndexMetadata API.
“SimpleIndexMetadata object” on page 277.

Syntax
HRESULT AddPropertyRange([in, string] const BSTR bsPropSet,
[in, string] const BSTR bsProp,
[in] VARIANT vVal1,
[in] VARIANT vVal2,
[in, defaultvalue(0)] const long lFlags,
[out, retval] BSTR* pbsQuery);

Parameters

[in, string] const BSTR bsPropSet String containing the name of the
property set.

[in, string] const BSTR bsProp String containing the property name.

[in] VARIANT vVal1 VARIANT specifying the first value in


the range.

[in] VARIANT vVal2 VARIANT specifying the second value


in the range.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to
process the range added to the search
query.
See “ESearchQueryFlags enumeration”
on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that will contain the
query string formed by this method.

Remarks
This method can only be used with date or integer values.
bsProp can be a custom index property that has been added using the
SimpleIndexMetadata API. bsPropSet specifies the property set.
Search API 563
ISearchQuery2 :: AddPropertyRange

vVal1 and vVal2 must be the same type.


The parameter lFlags must contain one value from table “ESearchQueryFlags
enumeration” on page 533. Currently, however, none of the Search Query Flags
has any effect on range searches.
Note that AddRange can also be used with custom properties, using the
propertySet.propertyName format.

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,
(int)ESearchQueryFlags.ESQany);

See also
■ “Adding custom index metadata” on page 55
■ “ISearchQuery :: SetRange” on page 546
■ “ISearchQuery :: AddRange” on page 548
■ “ISearchQuery2 :: SetPropertyRange” on page 560
■ “System properties” on page 664.
■ “SimpleIndexMetadata object” on page 277.
564 Search API
IndexSearch object

IndexSearch object
IndexSearch object implements the following interface:
■ IIndexSearch2
IIndexSearch2 provides properties and methods that can be used to enable the
user to search an archive using a query that has been built using the methods of
ISearchQuery2.
The output from a search is a pointer to an ISearchResults2 interface, the
implementation of which contains a collection of ISearchResult2 pointers.

Syntax
interface IIndexSearch2 : IDispatch

Member summary

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 535.
See “Remarks” on page 566.

AdditionalResultsProperties Read/Write A space separated list of


properties returned in the search
results in addition to those in the
selected results property set.
Search API 565
IndexSearch object

Property Read/Write Description

Timeout Read/Write Gets or sets the timeout period, in


seconds, applied to federated
search requests (that is, searches
across multiple index volume
sets).

ArchiveEntryId Read only Gets the Id of the currently


selected archive.

ArchiveName Read only Gets the name of the currently


selected archive.

HasFolders Read only Returns true if the currently


selected archive contains folders.

IndexVolumeSetIdentity Read only Gets the identity of the currently


selected index volume set.

IndexVolumeIdentity Read only The identity of the currently


selected index volume.

IndexVolumeSetCount Read only Gets the number of index volume


sets for the currently selected
archive.

MaxSearchIndexVolumeSets Read/Write For federated searches, gets or


sets the current maximum
number of volume sets to search.
The default value is 5. If number
of volumes is above this, the
search application must select the
specific VolumeSet to search (see
SelectIndexVolumeSet).

MaxSearchResultsPerVolumeSet Read/Write For federated searches only, gets


or sets the current value of the
maximum number of results to be
returned per volume set. Default
is 1000.

Method Description

SelectArchive Sets the Id of the archive to be searched.


566 Search API
IndexSearch object

Method Description

ListIndexVolumeSets Returns as an XML document the index volume


set collection for the selected archive.

SelectIndexVolumeSet Set the Id of the archive's index volume set to


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

SelectIndexVolume This property should not be used.


As Enterprise Vault only supports one volume per
volume set, use SelectIndexVolumeSet to select a
specific index volume to search.
See “Remarks” on page 566.

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


AdditionalResultsProperties list.

Reset Reset the object properties to their default values.

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

IIndexSearch2 provides a method that returns a collection of index volume sets.


This collection is accessed by methods and properties of the returned
IIndexVolumeSet pointer.
If the number index volume sets is greater than the number set by
MaxSearchIndexVolumeSets (5 is the default), then it is necessary to specify the
archive Id and also the index volume sets to search, otherwise an error is
returned, rvINDEXING_E_TOO_MANY_VOLUMES.
Currently, the index volume set is limited to one index volume. However, in a
future release, index volume sets may contain more than one index volume. To
prevent any confusion, all new applications should use methods and properties
that specify index volume sets, as errors could occur if those that refer to index
volumes (such as, IIndexSearch2 :: IndexVolumeIdentity) are used.

Example
The object, 'search', constructed in this example will be used in the most of the
subsequent examples. It is shown here as a private class data member.

C#
public class SampleSearchClass
{
private IIndexSearch2 search = (IIndexSearch2)
new IndexSearch2();
//rest of the class

See also
■ “IndexVolumeSets object” on page 605
■ “IndexVolumeSet object” on page 615
568 Search API
IIndexSearch2 :: IndexVolumeSets

IIndexSearch2 :: IndexVolumeSets
This property returns a pointer to an IndexVolumeSets collection object. The
collection can be accessed using the properties and methods of the returned
interface pointer. The property is read only.

Syntax
HRESULT IndexVolumeSets([out,retval] IUnknown**
volumeSetsCollection);

Parameters

[out,retval] IUnknown** volumeSetsCollection Pointer to an IUnknown pointer


that can be QI'd (or cast) to
obtain an IIndexVolumeSets
pointer.

Remarks
This property must not be used before SelectArchive has been called.
The returned data should not be persisted, as the collection of index volume sets
associated with an archive may change over time. Also when indexes are rebuilt
the set of index volumes will change.
See “IndexVolumeSets object” on page 605 for details of index volume sets.

Return value

rvS_OK Success.

rvE_POINTER An invalid pointer has been received.

rvINDEXING_W_ARCHIVE_NOT_SET The archive to search has not been set.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;
foreach (IIndexVolumeSet volSet in volSets)
{
Search API 569
IIndexSearch2 :: IndexVolumeSets

search.SelectIndexVolumeSet(volSet.Identity);
DoSearch(search);
}
570 Search API
IIndexSearch2 :: Options

IIndexSearch2 :: Options
This property sets or returns search option flags that define the granularity of
search results.
The property is read/write.

Syntax
HRESULT Options([in] long options,
[out,retval] long* options);

Parameters

[in] long options EOptionsFlags value defining required granularity of


search results.
“EOptionsFlags enumeration” on page 535.

[out,retval] long* options Pointer to a long integer that will contain the current
value.

Remarks
Both messages and their attachments are searched, but the granularity of
search results (Option) defines whether attachments are returned in search
results or only the top-level items.
See “EOptionsFlags enumeration” on page 535.

Return value

rvS_OK Success.

rvE_POINTER An invalid pointer has been received.

Example

C#
[in]
search.Options = (int)EOptionsFlags.roItemGranularity;
[out]
EOptionsFlags eof = (EOptionsFlags )search.Options;
Search API 571
IIndexSearch2 :: Options

if (eof == EOptionsFlags.roAttachmentGranularity)
{
//do something
}
else //do something else
572 Search API
IIndexSearch2 :: SortBy

IIndexSearch2 :: SortBy
This property is used to order the returned search results.
The property is read/write.

Syntax
HRESULT SortBy([in] BSTR sortProperties,
[out,retval] BSTR* sortProperties);

Parameters

[in] BSTR sortProperties String containing the properties by which


to sort search results.

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


current properties used for sorting.

Remarks
sortProperties can be none or one index property.
The sort order is normally ascending, but you can reverse the order by preceding
the property with a minus sign (-), for example:
search.SortBy = "-" + "adat";

Return value

rvS_OK Success.

rvE_POINTER The pointer passed in to receive the current value is invalid.

Example
This example shows how to sort by archived date, in descending order.

C#
[in]
//sort by archived date descending
search.SortBy = "-" + "adat";
[out]
string sortBy = search.SortBy;
Search API 573
IIndexSearch2 :: ResultsPropertySet

IIndexSearch2 :: ResultsPropertySet
This property can be used to specify a predefined set of properties returned in
search results.
See “Remarks” for important comments on using this property.
The property is read/write.

Syntax
HRESULT ResultsPropertySet([in] long propertySet,
[out,retval] long* propertySet);

Parameters

[in] long propertySet Long integer containing the EPropertySets


value to be set.
See “EPropertySets enumeration” on page 535.

[out,retval] long* propertySet Pointer to a long integer that will receive the
current value.

Remarks
“EPropertySets enumeration” on page 535 lists the values for the predefined
property sets.
As the predefined property sets may change in future releases, we strongly
recommend that you set this property to psEmpty, and use the
AdditionalResultsProperties property and/or AddAdditionalResultsProperty
and AddAdditionalResultsCustomProperty to set the required properties to be
found in the result set.
See “EPropertySets enumeration” on page 535.

Return value

rvS_OK Success.

rvE_POINTER The long pointer passed in to receive the current value is


invalid.

rvE_INVALIDARG The value being set is less than 0.


574 Search API
IIndexSearch2 :: ResultsPropertySet

Example
As this property is no longer the recommended way of setting the returned
properties, it is set to ‘empty'.

C#
[in]
search.ResultPropertySet = (int)EPropertySets.psEmpty;
[out]
if (search.ResultPropertySet != 0)
{
search.ResultPropertySet = 0; // (psEmpty)
}

See also
■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575
■ “IIndexSearch2 :: AddAdditionalResultsProperty” on page 601
■ “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 602.
Search API 575
IIndexSearch2 :: AdditionalResultsProperties

IIndexSearch2 :: AdditionalResultsProperties
This property is the recommended way to define the properties returned in
search results.
The property is read/write.

Syntax
HRESULT AdditionalResultsProperties([in] BSTR propertiesList);
HRESULT AdditionalResultsProperties([out,retval] BSTR*
propertiesList);

Parameters

[in] BSTR propertiesList String containing a space separated list of


properties to be returned in the search
results.

[out,retval] BSTR* propertiesList Pointer to a string that will receive a list of


the current properties.

Remarks
The properties added must be in the format of a space delimited list.
Properties you define using this property should be in addition to those found in
the predefined property sets. It is recommended that the empty
ResultPropertySet is selected.
See “EPropertySets enumeration” on page 535.

Return value

rvS_OK Success.

rvE_POINTER The string pointer passed in to receive the current value is


invalid.

Example
Note that as IIndexSearch2::ResultPropertySet is no longer a preferred method,
it is set 'empty' as a precaution.
576 Search API
IIndexSearch2 :: AdditionalResultsProperties

C#
[in]
search.ResultPropertySet = (int)EPropertySets.psEmpty; //set empty
search.AdditionalResultsProperties = "ssid adat natc";
[out]
string props = search.AdditionalResultsProperties;
if (props.Contains("ssid"))
{
//do something

See also
■ “IIndexSearch2 :: AddAdditionalResultsProperty” on page 601
■ “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 602
■ “IIndexSearch2 :: ResultsPropertySet” on page 573
Search API 577
IIndexSearch2 :: Timeout

IIndexSearch2 :: Timeout
This property defines the timeout period applied to federated search requests.
The property is read/write.

Syntax
HRESULT Timeout([in] long seconds,
[out,retval] long* seconds);

Parameters

[in] long seconds Long integer containing number of seconds to wait before
the search times out. The default value is 60 seconds.

[out,retval] long* seconds Pointer to a long integer that will receive the current
value.

Remarks
Defines the period in seconds before a search request times out - the default
value is 60 seconds.
This property applies to federated searches only.

Return value

rvS_OK Success.

rvE_POINTER The new value being set is equal to or less than zero.

rvE_INVALIDARG The long integer pointer passed in to receive the current


value is incorrect.

Example

C#
[in][out]
if (search.Timeout < 60)
{
search.Timeout = 60;
}
578 Search API
IIndexSearch2 :: ArchiveEntryId

IIndexSearch2 :: ArchiveEntryId
This property returns the ID of the archive that is currently selected for
searching.
The property is read only.

Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value)

Parameters

[out,retval] BSTR* value Pointer to a string that will receive the current value.

Remarks
This method will only return a valid Id after SelectArchive has been called.

Return value

rvS_OK Success.

rvE_POINTER The BSTR pointer passed in to receive the current value is


invalid.

rvS_FALSE The archive has not been selected yet.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
//do something
string aeid = search.ArchiveEntryId;
Search API 579
IIndexSearch2 :: ArchiveName

IIndexSearch2 :: ArchiveName
This property returns the name of the archive that is currently selected for
searching.
The property is read only.

Syntax
HRESULT ArchiveName([out,retval] BSTR* value);

Parameters

[out,retval] BSTR* value Pointer to a string that will contain the current
value.

Remarks
This method will only return a valid archive name after SelectArchive has been
called.
If the archive has not been selected, then the return value will be S_FALSE.
If tested in one of the C++ SUCCEEDED or FAILED macros, this will register as
true. It is therefore advisable to test that the value acquired is as expected.

Return value

rvS_OK Success.

rvE_POINTER The BSTR pointer passed in to receive the current value is


invalid.

rvS_FALSE The archive has not been selected.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
//display the archive name in a textbox.
textBoxArchId.Text = search.ArchiveName;
580 Search API
IIndexSearch2 :: HasFolders

IIndexSearch2 :: HasFolders
This property indicates whether the currently selected archive contains a folder
structure.
The property is read only.

Syntax
HRESULT HasFolders([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive


the current value.

Remarks
This method will only return a valid result after SelectArchive has been called.

Return value

rvS_OK Success.

rvE_POINTER Value is an invalid pointer.

rvS_FALSE The archive has not been selected.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
//do something
if (search.HasFolders == true)
{
//do something
Search API 581
IIndexSearch2 :: IndexVolumeSetIdentity

IIndexSearch2 :: IndexVolumeSetIdentity
This property identifies the volume set of the index volume to search.
The property is read only.

Syntax
HRESULT IndexVolumeSetIdentity([out,retval] long* value);

Parameters

[out,retval] long* value Pointer to a long that will receive the current value.

Remarks
This property will return a valid Id after SelectArchive has been called.
It returns -1 and S_FALSE if SelectArchive has not been called, or the selected
archive has multiple index volume sets and SelectIndexVolumeSet has not been
called.

Return value

rvS_OK Success.

rvE_POINTER The long integer pointer passed in to receive the current


value is invalid.

rvS_FALSE Either SelectArchive has not been called, or there is an


invalid value for the Index Volume.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
//do something
long id = search.IndexVolumeSetIdentity;
if (id == -1)
MessageBox.Show("This archive has multiple Index Volume Sets -
please select one", "Multiple Index Volume Sets", MB_OK);
582 Search API
IIndexSearch2 :: IndexVolumeIdentity

IIndexSearch2 :: IndexVolumeIdentity
This property should not be used: it is currently available for Enterprise Vault
internal purposes only.
The property is read only.

Syntax
HRESULT IndexVolumeIdentity([out,retval] long* value);

Parameters

[out,retval] long* value Pointer to a long integer that will hold the current value.

Remarks
This property should not be used.
This property returns the IndexVolumeIdentity as selected by the search
application.
See “Remarks” on page 566.

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 Value is an invalid pointer.


Search API 583
IIndexSearch2 :: IndexVolumeSetCount

IIndexSearch2 :: IndexVolumeSetCount
This property returns the number of index volume sets in the archive’s index.
The property is read only.

Syntax
HRESULT IndexVolumeSetCount([out,retval] long* value);

Parameters

[out,retval] long* value Pointer to a long integer that will receive the current value.

Remarks
This property should not be used before SelectArchive has been called.

Return value

rvS_OK Success.

rvS_FALSE SelectArchive has not been called.

rvE_POINTER The long integer pointer passed in to receive the current


value is invalid.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
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
{
//do non-federated search
}
584 Search API
IIndexSearch2 :: MaxSearchIndexVolumeSets

IIndexSearch2 :: MaxSearchIndexVolumeSets
This property specifies the maximum number of index volume sets that can be
searched by a federated search (that is, a search across multiple index volume
sets).
The property is read/write.

Syntax
HRESULT MaxSearchIndexVolumeSets([out, retval] LONG* pVal,
[in] LONG newVal);

Parameters

[out, retval] LONG* pVal Pointer to a long integer that will receive the
maximum number of index volume sets that
can be searched. The default is 5.

[in] LONG newVal Long integer containing the new value to set.

Remarks
This property should not be used before SelectArchive has been called.
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 The long pointer passed in to receive the current value is


invalid.
Search API 585
IIndexSearch2 :: MaxSearchIndexVolumeSets

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
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
{
//do non-federated search
586 Search API
IIndexSearch2 :: MaxSearchResultsPerVolumeSet

IIndexSearch2 :: MaxSearchResultsPerVolumeSet
This property indicates the maximum number of search results that can be
returned per volume set by a federated search (that is, a search across multiple
index volume sets).
The property is read/write.

Syntax
HRESULT MaxSearchResultsPerVolumeSet([out, retval] LONG* pVal,
[in] LONG newVal);

Parameters

[out, retval] LONG* pVal Pointer to a long integer that will receive the current
value.

[in] LONG newVal Long integer that sets the new value required.

Remarks
This property should not be used before SelectArchive has been called.
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 The long pointer passed in to receive the current value is


invalid.
Search API 587
IIndexSearch2 :: MaxSearchResultsPerVolumeSet

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
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;
search.MaxsearchResultsPerVolumeSet = 500;
//carry on with search
}
else
{
//do non-federated search
588 Search API
IIndexSearch2 :: SelectArchive

IIndexSearch2 :: SelectArchive
This method is used to select an archive to search.

Syntax
HRESULT SelectArchive([in]BSTR archiveEID);

Parameters

[in]BSTR archiveEID String containing the Id of the archive to search.

Remarks
The SelectArchive method specifies the archive to search in subsequent calls to
Search or SearchToXML. The archive must be selected before attempting to list
index volume sets associated with the index, or search the index.
See “Performing a search” on page 524 for ways of finding out the ID of an
archive.

Return value

rvS_OK Success.

rvE_INVALIDARG Either a zero length string has been passed or


the archive entry specified could not be found.

rvINDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_INDEXDISABLED Indexing has been disabled for this archive;


the archive status is
INDEX_ITEMS_DEFERRED_INDEFINITELY.

Example

C#
Assume there is a populated IArchives object, 'archives'.
foreach (IArchive archive in archives)
{
search.SelectArchive(archive.Id);
Search API 589
IIndexSearch2 :: SelectArchive

DoSearch(search, 500);
}

See also
■ “IIndexSearch2 :: Search” on page 595
■ “IIndexSearch2 :: SearchToXML” on page 598
590 Search API
IIndexSearch2 :: ListIndexVolumeSets

IIndexSearch2 :: ListIndexVolumeSets
This method is used to list the index volume set collection for the selected
archive as an XML document.

Syntax
HRESULT ListIndexVolumeSets([in] BSTR processingInstruction,
[out,retval] BSTR* volumeSetsList);

Parameters

[in] BSTR processingInstruction String containing an optional parameter that


enables the caller to specify an XML processing
instruction. This is added to the XML following
the XML declaration. For example, an XSL style
sheet reference can be specified with the
following string:
xml-stylesheet
href="indexvolumesets.xsl"
type="text/xsl"
(XML processing instruction delimiters are
added by the method).

[out,retval] BSTR* volumeSetsList Pointer to a string that will receive the XML
document.

Remarks
An archive must have been selected using SelectArchive.
This method is an alternative to using the IndexVolumeSets property.
IndexVolumeSets returns a pointer to an enumerated collection of
IIndexVolumeSet interface pointers, which can be accessed using the properties
and methods of the returned interface pointer.

Return value

rvS_OK Success.

rvE_POINTER The parameter volumeSetList is a NULL pointer.

rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.


Search API 591
IIndexSearch2 :: ListIndexVolumeSets

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
string volSetsXML = search.ListIndexVolumeSets("xml-stylesheet
href='indexvolumesets.xsl' type='text/xsl'");
//do something with the XML
The following gives an example of the XML returned by the
ListIndexVolumeSets method.
For the last index volume set, all elements except FirstItemSequenceNumber are
optional, since it may represent a new index volume that has not yet been
committed to disk.
<?xml version="1.0" encoding="utf-16" ?>
<IndexVolumeSets xmlns="urn:kvsinc-com:EnterpriseVault"
ArchiveEntryId="12234E1CE26421C45A096DD3CA06527071110000evsvr"
ArchiveName="John Smith"
HasFolders="True">
<IndexVolumeSet Identity="20">
<FirstItemSequenceNumber>1</FirstItemSequenceNumber>
<OldestArchivedDate>2002-03-13T12:50:38Z</OldestArchivedDate>
<YoungestArchivedDate>2004-04-18T06:49:44Z</YoungestArchivedDate>
<OldestItemDate>1998-03-26T05:34:02Z</OldestItemDate>
<YoungestItemDate>2004-03-02T22:22:23Z</YoungestItemDate>
</IndexVolumeSet>
<IndexVolumeSet Identity="29">
<FirstItemSequenceNumber>16666344</FirstItemSequenceNumber>
<OldestArchivedDate>2004-04-18T06:49:50Z</OldestArchivedDate>
<YoungestArchivedDate>2004-04-25T07:02:44Z</YoungestArchivedDate>
<OldestItemDate>2004-03-12T20:12:03Z</OldestItemDate>
<YoungestItemDate>2004-03-13T22:06:16Z</YoungestItemDate>
</IndexVolumeSet>
</IndexVolumeSets>

See also
■ “IIndexSearch2 :: IndexVolumeSets” on page 568
■ “IndexVolumeSets object” on page 605
■ “IndexVolumeSet object” on page 615
592 Search API
IIndexSearch2 :: SelectIndexVolumeSet

IIndexSearch2 :: SelectIndexVolumeSet
This method selects an index volume set when searching an index with multiple
index volume sets.

Syntax
HRESULT SelectIndexVolumeSet([in] long volumeSetIdentity);

Parameters

[in] long volumeSetIdentity Long integer containing the Id of the index volume set.

Remarks
An archive must have been selected using SelectArchive.
For an index with a single index volume set, that index volume set is selected by
default.
Unless this property is set to specify an index volume set to search, then a feder-
ated search will be carried out across all index volume sets in the archive. How-
ever, if the number of index volume sets exceeds the number set by
MaxSearchIndexVolumeSets (default is 5), this property must be set to deter-
mine which index volume set to search, otherwise the Search API will return an
error, rvINDEXING_E_TOO_MANY_VOLUMES.
Index volume set Ids can be obtained using the ListIndexVolumeSets method.

Return value

rvS_OK Success.

rvE_INVALIDARG

rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET The volume set specified does not


exist.

rvINDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_UNABLE_FAILED_VOLUME A volume in the set is known to have


failed - no reason specified.
Search API 593
IIndexSearch2 :: SelectIndexVolumeSet

rvINDEXING_E_UNABLE_OFFLINE_VOLUME A volume in the set is known to be


offline.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
//set up the search
ISearchResults2 results = null;
if (search.IndexVolumeSetCount > search.MaxSearchIndexVolumeSets)
{
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;
foreach (IIndexVolumeSet volSet in volSets)
{
search.SelectIndexVolumeSet(volSet.Identity);
//do the search etc.
results = (ISearchResults2)search.Search(query.Query, 1, 100, "");
}
}
else results = (ISearchResults2)search.Search(query.Query, 1, 100, "");
594 Search API
IIndexSearch2 :: SelectIndexVolume

IIndexSearch2 :: SelectIndexVolume
This method is used to select a specific index volume of the archive to search.

Syntax
HRESULT SelectIndexVolume([in] long volumeIdentity);

Parameters

[in] long volumeIdentity

Remarks
This method should not be used. An Index Volume Set is considered the smallest
element of an archive's index. The ability to select individual index volumes may
be removed in a future release.
See “Remarks” on page 566.

Return value

rvS_OK Success.

rvE_INVALIDARG An unexpected error has occurred.

rvINDEXING_W_UNKNOWN_INDEX_VOLUME

rvINDEXING_W_ARCHIVE_NOT_SET

rvINDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_UNABLE_FAILED_VOLUME

rvINDEXING_E_UNABLE_OFFLINE_VOLUME
Search API 595
IIndexSearch2 :: Search

IIndexSearch2 :: Search
This method submits the search request and returns a search results object.
See “SearchResults object” on page 627.

Syntax
HRESULT Search([in] BSTR bsQuery,
[in] long startResult,
[in] long maximumResults,
[in] BSTR reserved,
[out, retval] IUnknown** resultsSet);

Parameters

[in] BSTR bsQuery String containing the query. This is


normally the Query property of a
SearchQuery object.

[in] long startResult Long integer containing the number of the


first result. This can be 1 up to the total
number of possible results.

[in] long maximumResults Long integer containing the maximum


number of results to return.

[in] BSTR reserved This parameter must be "".

[out, retval] IUnknown** resultsSet Pointer to an IUnknown pointer. On return,


the resulting IUnknown pointer can be QI'd
(or cast) to obtain the required
ISearchResults2 pointer.

Remarks
An empty query causes a full wildcard search, which matches all entries in the
index. As maximum results will probably be exceeded, it is unlikely to return all
the items in the index.
To ensure a well formed query is passed to this method, obtain an
ISearchQuery2 interface pointer and construct a query using the properties and
methods of this interface.
See “SearchQuery object” on page 537.
Each search starts a new search in the Indexing server.
The startResult and maximumResults arguments enable paging through search
results.
596 Search API
IIndexSearch2 :: Search

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.
See “ESearchQueryFlags enumeration” on page 533.
■ Otherwise, in order of addition to the index.
See “Performing a search” on page 524 for more information and
recommendations for performing searches.

Return value

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer


passed is the fourth parameter is
invalid.

rvE_ACCESSDENIED

rvE_NOINTERFACE

rvE_SERVER_UNAVAILABLE

rvINDEXING_SERVER_STOPPING

rvINDEXING_E_SERVICE_STOPPING

rvINDEXING_E_ARCHIVE_NOT_SET

INDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_ARCHIVE_BEING_DELETED

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET

rvINDEXING_W_UNKNOWN_INDEX_VOLUME The selected index volume is not


known.

rvINDEXING_W_UNABLE_FAILED_VOLUME

rvINDEXING_E_UNABLE_OFFLINE_VOLUME

rvINDEXING_W_SEARCH_WOULD_BLOCK

rvINDEXING_W_SEARCH_TIMEDOUT
Search API 597
IIndexSearch2 :: Search

rvINDEXING_E_TOO_MANY_RESULTS

rvINDEXING_E_TOO_MANY_VOLUMES

rvINDEXING_E_INVALID_QUERY

rvINDEXING_E_ILLEGAL_WILDCARD_QUERY

rvINDEXING_E_FAILED_SEARCH_REQUEST

rvINDEXING_E_INDEX_SEARCH_FAILED

Example
In this example it is assumed that an ISearchQuery2 object, ‘query', has been
created and populated.

C#
//select the archive and set up the search query etc
//return a results set that starts from the first item found up to a
total of 100 items.
ISearchResults2 results = (ISearchResults2)search(query.Query, 1,
100, "");
Note the fourth parameter must be "".

See also
■ “SearchQuery object” on page 537
■ “ESearchQueryFlags enumeration” on page 533
598 Search API
IIndexSearch2 :: SearchToXML

IIndexSearch2 :: SearchToXML
This method is used to search the selected index volume set or index volume and
return the results as XML. This method is similar to Search, but it returns XML
not an interface pointer.

Syntax
HRESULT SearchToXML([in] BSTR bsQuery,
[in] long startResult,
[in] long maximumResults,
[in] BSTR reserved,
[in] BSTR processingInstruction,
[in] long xmlFormatOptions,
[out,retval] VARIANT* xmlResults);

Parameters

[in] BSTR bsQuery String containing the query, this is normally the
Query property of a SearchQuery object.

[in] long startResult Long integer containing the number of the first
result. This can be 1 up to the total number of
possible results.

[in] long maximumResults Long integer containing the maximum number of


results to return.

[in] BSTR reserved This parameter must be "".

[in] BSTR processingInstruction String containing an XML processing instruction


which will be inserted into the returned XML. For
example, xml-stylesheet type="test/xsl"
href="results.xsl"

[in] long xmlFormatOptions Long integer containing a flag from the


EXMLResultsFormatOptions. Currently the only
available value is 0.

[out,retval] VARIANT* xmlResults Pointer to a VARIANT containing the search


results.

Remarks
EXMLResultsFormatOptions enumerates the XML format option values.
Currently there is only the following default value:
xoNone = 0x00000000
Search API 599
IIndexSearch2 :: SearchToXML

An empty query causes a full wildcard search, which matches all entries in the
index. As maximum results will probably be exceeded, it is unlikely to return all
the items in the index.
To ensure a well formed query is passed to this method, obtain an
ISearchQuery2 interface pointer and construct a query using the properties and
methods of this interface.
See “SearchQuery object” on page 537.
Each search starts a new search in the Indexing server.
The startResults and maximumResults arguments enable paging through
search results.
Results are numbered, in order, after sorting. Search results are ordered as
follows:
■ Using the index property specified with the SortBy property, if any.
■ Otherwise, for those terms where the ESQRank flag was specified in the
search term, by relevance to the words used in the search query.
See “ESearchQueryFlags enumeration” on page 533.
■ Otherwise, in order of addition to the index.
See “Performing a search” on page 524 for more information and
recommendations for performing searches.

Return value

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed is the fifth


parameter is invalid.

rvE_ACCESSDENIED

rvE_NOINTERFACE

rvE_SERVER_UNAVAILABLE

rvINDEXING_SERVER_STOPPING

rvINDEXING_E_SERVICE_STOPPING

rvINDEXING_E_ARCHIVE_NOT_SET

INDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_ARCHIVE_BEING_DELETED
600 Search API
IIndexSearch2 :: SearchToXML

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET

rvINDEXING_W_UNKNOWN_INDEX_VOLUME

rvINDEXING_W_UNABLE_FAILED_VOLUME

rvINDEXING_E_UNABLE_OFFLINE_VOLUME

rvINDEXING_W_SEARCH_WOULD_BLOCK

rvINDEXING_W_SEARCH_TIMEDOUT

rvINDEXING_E_TOO_MANY_RESULTS

rvINDEXING_E_TOO_MANY_VOLUMES

rvINDEXING_E_INVALID_QUERY

rvINDEXING_E_ILLEGAL_WILDCARD_QUERY

rvINDEXING_E_FAILED_SEARCH_REQUEST

rvINDEXING_E_INDEX_SEARCH_FAILED

Example
In this example it is assumed that an ISearchQuery2 object, ’query', has been
created and populated.

C#
//select the archive and set up the search query etc
byte[] res = (byte[])search.SearchToXML(query.Query, 1, 100, "",
"", 0);
Search API 601
IIndexSearch2 :: AddAdditionalResultsProperty

IIndexSearch2 :: AddAdditionalResultsProperty
This method is used to add a single property to the AdditionalResultsProperties
list. Using the AdditionalResultsProperty list is now the preferred way of
specifying properties required in the results set.

Syntax
HRESULT AddAdditionalResultsProperty([in] BSTR propertyName);

Parameters

[in] BSTR propertyName String containing the property to add to the list of
properties returned in results.

Remarks
In conjunction with AdditionalResultsProperties, this is now the preferred way
to set up a list of properties to be returned. A custom property can be specified
using the propertySet.propertyName format.

Return value

rvS_OK Success.

rvE_POINTER

rvE_INVALIDARG A property name has not been specified

Example

C#
search.AddAdditionalResultsProperty ("natc");

See also
■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575
602 Search API
IIndexSearch2 :: AddAdditionalResultsCustomProperty

IIndexSearch2 ::
AddAdditionalResultsCustomProperty
This method is used to add a single custom property to the
AdditionalResultsProperties list.

Syntax
HRESULT AddAdditionalResultsCustomProperty([in] BSTR propertySet,
[in] BSTR propertyName);

Parameters

[in] BSTR propertySet String containing the name of the property set.

[in] BSTR propertyName String containing the name of the property.

Remarks
If the property is in the global property set, then the propertySet parameter
should be set to NULL.
Custom properties can be added at the time of storage using the
ISimpleIndexMetaData interface.

Return value

rvS_OK Success.

rvE_POINTER A property name has not been specified.

rvE_INVALIDARG A property name has not been specified.

Example

C#
search.AddAdditionalResultsCustomProperty("custpropset",
"custpropname");
Search API 603
IIndexSearch2 :: AddAdditionalResultsCustomProperty

See also
■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575
■ “SimpleIndexMetadata object” on page 277
604 Search API
IIndexSearch2 :: Reset

IIndexSearch2 :: Reset
This method is used to reset the object properties to their default values.

Syntax
HRESULT Reset();

Remarks
This method is used to reset the object properties to their default values.

Return value

rvS_OK Success.

Example

C#
private void resetButton_Click(object sender, EventArgs e)
{
//reset button pressed so reset all object properties to default
search.Reset();
}
Search API 605
IndexVolumeSets object

IndexVolumeSets object
This object implements the following interface:
■ IIndexVolumeSets
This interface provides a set of properties than can used to manage a collection
of index volume sets.

Syntax
interface IIndexVolumeSets : IDispatch

Member summary

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.
606 Search API
IndexVolumeSets object

Example
Note that IIndexSearch2::SelectArchive must be called before using
IIndexSearch2::IndexVolumeSets.

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;

See also
■ “IIndexSearch2 :: IndexVolumeSets” on page 568
■ “IIndexSearch2 :: ListIndexVolumeSets” on page 590
■ “IIndexVolumeSet :: FirstItemIndexSequenceNumber” on page 620
■ “IIndexVolumeSet :: OldestArchivedDate” on page 621
■ “IIndexVolumeSet :: YoungestArchivedDate” on page 622
■ “IIndexVolumeSets :: Item” on page 613
■ “IIndexVolumeSets :: _NewEnum” on page 611
Search API 607
IIndexVolumeSets :: ArchiveEntryId

IIndexVolumeSets :: ArchiveEntryId
This property returns the archive Id of the archive to which the index volume
set belongs.
The property is read only.

Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value);

Parameters

[out,retval] BSTR* value Pointer to a string that will hold the currently selected
archive Id.

Remarks
Gets the ArchiveEntryId associated with the current index volume sets.
SelectArchive must be called prior to using this property.

Return value

rvS_OK Success.

rvE_POINTER The pointer passed in to receive the current value is invalid.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
IIndexVolumeSets volSets =
(IIndexVolumeSets)search.IndexVolumeSets;
string aeid = volSets.ArchiveEntryId;
608 Search API
IIndexVolumeSets :: ArchiveName

IIndexVolumeSets :: ArchiveName
This property returns the name of the archive to which the index volume set
belongs.
The property is read only.

Syntax
HRESULT ArchiveName([out,retval] BSTR* value);

Parameters

[out,retval] BSTR* value Pointer to a string that will contain current name.

Remarks
SelectArchive must be called prior to using this property.

Return value

rvS_OK Success.

rvE_POINTER The pointer to a string passed to the property is invalid.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;
string archName = volSets.ArchiveName;
Search API 609
IIndexVolumeSets :: HasFolders

IIndexVolumeSets :: HasFolders
This property indicates whether the archive contains a folder structure.
The property is read only.

Syntax
HRESULT HasFolders([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain


a true value if the archive contains a folder
structure.

Remarks
SelectArchive must be called prior to using this property.

Return value

rvS_OK Success.

rvE_POINTER The pointer to a string passed in to receive the current value is invalid.

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;
if (volSets.HasFolders == true)
{
//do something
610 Search API
IIndexVolumeSets :: Count

IIndexVolumeSets :: Count
This property returns the number of index volume sets associated with the
currently selected archive.
The property is read only.

Syntax
HRESULT Count([out,retval] long* value);

Parameters

[out,retval] long* value Long pointer to receive the current number of index
volume sets for the current archive.

Remarks
SelectArchive must be called prior to using this property.

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#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");
IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;
for (int i = 1; i <= volSets.Count; i++)
{
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i);
//do something
Search API 611
IIndexVolumeSets :: _NewEnum

IIndexVolumeSets :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the collection. This property is hidden in 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#,
VBScript.
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.

Examples
The following examples show how to enumerate the Index Volume Sets in an
Index Search object.

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
IIndexVolumeSets volSets =
(IIndexVolumeSets)search.IndexVolumeSets;
foreach (IIndexVolumeSet volSet in volSets)
{
//do something
612 Search API
IIndexVolumeSets :: _NewEnum

See also
“IIndexVolumeSets :: Item” on page 613
Search API 613
IIndexVolumeSets :: Item

IIndexVolumeSets :: Item
This property returns an index volume set instance from the collection, based
on the index value passed to it.
The property is read only.

Syntax
HRESULT Item([in] long index,
[out,retval] IUnknown** indexVolumeSet);

Parameters

[in] long index The 1-based index of index volume sets


in the collection.

[out,retval] IUnknown** indexVolumeSet Returns an IUnknown interface to the


index volume set object.

Remarks
This property provides an alternative method to _NewEnum for accessing the
IIndexVolumeSet pointers contained in the collection.
IIndexSearch2::SelectArchive must be called prior to using this property.

Return value

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed to the property


is invalid.

rvE_INVALIDARG

Example

C#
search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit
e1");
614 Search API
IIndexVolumeSets :: Item

IIndexVolumeSets volSets =
(IIndexVolumeSets)search.IndexVolumeSets;

for (int i = 1; i <= volSets.Count; i++)


{
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i);
//do something

C++
#import "IndexClient.dll"
using namespace EVIndexClient;

long volSetCount = 0;
IIndexVolumeSetsPtr volSets;
IIndexVolumeSetPtr volumeSet;

indexSearch.SelectArchive(archiveId);

volSets = indexSearch.IndexVolumeSets();
volSetCount = volSets.Count();

for(long i = 1; i <= volSetCount; ++i)


{
volumeSet = volSets.Item(i);

// Display the volume set details, ensure date time values


are returned and displayed in local system time
volumeSet.PutDateTimesUTC(VARIANT_FALSE);
DisplayVolumeSet(volumeSet);
}

See also
■ “IndexVolumeSet object” on page 615
■ “IIndexVolumeSets :: _NewEnum” on page 611
Search API 615
IndexVolumeSet object

IndexVolumeSet object
The IndexVolumeSet object implements the following interface:
■ IIndexVolumeSet
IIndexVolumeSet interface provides a set of properties that can be used to query
a particular index volume set for the current archive.
IndexVolumeSet pointers can be obtained using the IIndexVolumeSets interface
that enables users to iterate through the index volume sets for an archive.

Syntax
interface IIndexVolumeSet : IDispatch

Member summary

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.

YoungestItemDate Read only The youngest date property of the


items indexed in the index volume set.
616 Search API
IndexVolumeSet object

Property Read/Write Description

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.
See “Remarks” on page 605.

Example

C#
The following examples show two ways of obtaining an object of type
IIndexVolumeSet. Both ways assume that an object of type IIndexVolumeSets,
'volSets', has been obtained.
IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(index);
//index is a '1' based index into the collection of IIndexVolumeSets
or
//Use the 'foreach' method with IIndexVolumeSets::_NewEnum:
foreach (IIndexVolumeSet volSet in volSets)
{
//do something

See also
■ “IndexVolumeSets object” on page 605
Search API 617
IIndexVolumeSet :: Identity

IIndexVolumeSet :: Identity
This property returns the Id of the current index volume set.
The property is read only.

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;
foreach (IIndexVolumeSet volSet in volSets)
{
search.SelectIndexVolumeSet(volSet.Identity);
DoSearch(search, 500);
}
618 Search API
IIndexVolumeSet :: ArchiveEntryID

IIndexVolumeSet :: ArchiveEntryID
This property returns the archive Id of the archive to which the index volume
set collection belongs.
The property is read only.

Syntax
HRESULT ArchiveEntryId([out,retval] BSTR* value);

Parameters

[out,retval] BSTR* value Pointer to a string that will contain the current Id.

Return value

rvS_OK Success.

rvE_POINTER The string pointer passed into the property is invalid.

Example

C#
string archId = volSet.ArchiveEntryId;
Search API 619
IIndexVolumeSet :: ArchiveName

IIndexVolumeSet :: ArchiveName
This property returns the name of the archive to which the index volume set
collection belongs.
The property is read only.

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;
620 Search API
IIndexVolumeSet :: FirstItemIndexSequenceNumber

IIndexVolumeSet :: FirstItemIndexSequenceNumber
This property returns the Index Sequence Number (ISN) of the first item in the
index volume set.
The property is read only.

Syntax
HRESULT FirstItemIndexSequenceNumber([out,retval] VARIANT* value);

Parameters

[out,retval] VARIANT* value Pointer to a VARIANT that will receive the index
number.

Remarks
The value of this property determines the order of volume sets in the collection.
The number is returned as a VARIANT and could be either a variant type VT_I4
or VT_I8. In Windows 2000, VT_I8 is not supported, so variant type will be
VT_DECIMAL.

Return value

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed to the property is not valid.

Example

C#
object obj = volSet.FirstIndexSequenceNumber;
Search API 621
IIndexVolumeSet :: OldestArchivedDate

IIndexVolumeSet :: OldestArchivedDate
This property returns the oldest archived date of the items indexed in the index
volume set.
The property is read only.

Syntax
HRESULT OldestArchivedDate([out,retval] VARIANT* value);

Parameters

[out,retval] VARIANT* value Pointer to a VARIANT containing the oldest archived


date in the index volume set.

Remarks
This date value is returned as VARIANT. The variant type will be VT_DATE.

Return value

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed to the property is invalid.

Example

C#
object obj = volSet.OldestArchivedDate;
DateTime dateTime = (DateTime)obj;
622 Search API
IIndexVolumeSet :: YoungestArchivedDate

IIndexVolumeSet :: YoungestArchivedDate
This property returns the youngest archived date of the items indexed in the
index volume set.
The property is read only.

Syntax
HRESULT YoungestArchivedDate([out,retval] VARIANT* value);

Parameters

[out,retval] VARIANT* value Pointer to a VARIANT that will receive the youngest
archived date in the index volume set.

Remarks
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 in to the property is invalid.

Example

C#
object obj = volSet.YoungestArchivedDate;
DateTime dateTime = (DateTime)obj;
Search API 623
IIndexVolumeSet :: OldestItemDate

IIndexVolumeSet :: OldestItemDate
This property returns the oldest item in the index.
The property is read only.

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
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.OldestItemDate;
DateTime dateTime = (DateTime)obj;
624 Search API
IIndexVolumeSet :: YoungestItemDate

IIndexVolumeSet :: YoungestItemDate
This property returns the youngest item in the index.
The property is read only.

Syntax
HRESULT YoungestItemDate([out,retval] VARIANT* value);

Parameters

[out,retval] VARIANT* value Youngest date of items 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.YoungestItemDate;
DateTime dateTime = (DateTime)obj;
Search API 625
IIndexVolumeSet :: DateTimesUTC

IIndexVolumeSet :: DateTimesUTC
This property indicates whether property values of type VT_DATE are returned
as UTC or local system time.
The property is read/write.

Syntax
HRESULT DateTimesUTC([in] VARIANT_BOOL value);
HRESULT DateTimesUTC([out,retval] VARIANT_BOOL* value);

Parameters

[in] VARIANT_BOOL value VARIANT_BOOL containing the new value to


set.

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will


receive the current value.

Return value

rvS_OK Success.

rvE_POINTER The VARIANT_BOOL pointer passed to the property is


invalid.

Example

C#
[in]
IIndexVolumeSets volSets = (IIndexVolumeSets)
search.IndexVolumeSets;
foreach (IIndexVolumeSet volSet in volSets)
{
//make sure we return the datetime in local system time
volSet.DateTimeUTC = false;
object obj = volSet.YoungestItemDate;
DateTime dateTime = (DateTime)obj;
DateTime dt = new DateTime(2006, 12, 31);
if (dateTime > dt)
{
//do something
626 Search API
IIndexVolumeSet :: DateTimesUTC

}
else //do something else
}
[out]
IIndexVolumeSets volSets = (IIndexVolumeSets)
search.IndexVolumeSets;
foreach (IIndexVolumeSet volSet in volSets)
{
bool utc = volSet.DateTimeUTC;
Search API 627
SearchResults object

SearchResults object
The SearchResults object implements the following interfaces:
■ ISearchResults
■ ISearchResults2
These interfaces provide a set of methods and properties that can be used to
query and manage results returned from a search operation. Each result is
represented by an SearchResult object.

Syntax
interface ISearchResults2 :ISearchResults : IDispatch

Member summary

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.

ISearchResults::SortBy Read only Name of the properties used to order the


search results.

ISearchResults::_NewEnum Read only Enumeration for iterating through the


results.
628 Search API
SearchResults object

Method Read/Write Description

ISearchResults::Item Read only Set of results object returned by


enumeration.

ISearchResults2::InSync Read only Indicates whether or not the index is


synchronized with the current
contents of the archive.

ISearchResults2::TruncationReason Read only Reasons for truncated search results.

ISearchResults2::DateTimesUTC Read/Write Whether property values of type


VT_DATE are returned as UTC or local
system time.

ISearchResults2::LoadResults Write only Loads search results XML from


IStream or SAFEARRAY of bytes or a
string (BSTR).

Example
An object of type ISearchResults2 is obtained from a call to
IIndexSearch2::Search, or by creating it directly and initializing it with a set of
pre-existing results.

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
or
ISearchResults2 results = (ISearchResults2) new SearchResults();
//assume we have a set of results in xml, held in the string
xmlResults
results.Results = xmlResults;
Search API 629
ISearchResults :: Results

ISearchResults :: Results
This property gets or sets an XML text string which represents the results
string.
The property is read/write.

Syntax
HRESULT Results([out, retval] BSTR *pbsResults,
[in, string] BSTR bsResults);

Parameters

[out, retval] BSTR *pbsResults Pointer to a string that will receive the XML
results string.

[in, string] BSTR bsResults String that contains an XML results string to
initialize the object.

Remarks
Search results are stored in XML and can be retrieved or set using this property.
If a new string is stored then any previous results will be lost.

Return value

rvS_OK Success.

rvE_POINTER The BSTR pointer passed in to the property is invalid.

rvS_FALSE

vE_INVALIDARG

rvE_NOINTERFACE

Example

C#
[out]
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
630 Search API
ISearchResults :: Results

//get the results in XML


string xmlResults = results.Results;
[in]
//assume that a previous results set has been stored in the string
’xmlResults’
ISearchResults2 src = (ISearchResults2) new SearchResults();
//initialise the new object with some existing results
src.Results = xmlResults;
Search API 631
ISearchResults :: Count

ISearchResults :: Count
This property returns the number of results found by the Search operation.
The property is read only.

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 The long integer pointer passed into the property is invalid.

Example

C#
The following example gives an alternative approach to using 'foreach' to
enumerate the results returned.
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
int num = results.Count;
for (int i = 1; i <= num; i++)
{
ISearchResult2 res = (ISearchResult2)results.Item(i);
632 Search API
ISearchResults :: Total

ISearchResults :: Total
This property returns the total number of results that matched the search
query.
The property is read only.

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 The long integer pointer passed into the property is invalid.

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
long num = results.Count;
long total = results.Total;
if (total < num)
{
//an error has ooccured as the total should be at least equal to
the number results returned
Search API 633
ISearchResults :: Start

ISearchResults :: Start
This property returns the start position in the entire set of results of the first
result in this SearchResults object.
The property is read only.

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#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
long start = results.Start;
634 Search API
ISearchResults :: Options

ISearchResults :: Options
This property returns the value of the Options property of the IndexSearch2
object used to generate this set of results. The property contains search option
flags that define the granularity of search results.
The property is read only.

Syntax
HRESULT Options([out, retval] long *plOptions);

Parameters

[out, retval] long *plOptions Pointer to a long integer that will receive the value.

Remarks
This property retrieves the value that indicates the granularity used to generate
the set of results.
See “IIndexSearch2 :: Options” on page 570.

Return value

rvS_OK Success.

rvE_POINTER The long integer pointer passed into the property is invalid.

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
EOptionsFlags eof = (EOptionsFlags )results.Options;
if (eof == EOptionsFlags.roAttachmentGranularity)
{
//do something
}
else //do something else
Search API 635
ISearchResults :: SortBy

ISearchResults :: SortBy
This property returns the value of the SortBy property of the IndexSearch2
object used to generate this set of results. The property is used to order the
returned search results.
The property is read only.

Syntax
HRESULT SortBy([out, retval] BSTR *pbsSortBy);

Parameters

[out, retval] BSTR *pbsSortBy Pointer to a string that will receive the current
value

Remarks
See “IIndexSearch2 :: SortBy” on page 572.

Return value

rvS_OK Success.

rvE_POINTER The string pointer passed into the property is invalid.

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
string sortBy = results.SortBy;
636 Search API
ISearchResults :: _NewEnum

ISearchResults :: _NewEnum
This property returns an IEnumVARIANT interface on an object that can be
used to enumerate the SearchResults collection. This property is hidden in
VBScript.
The property is read only.

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 foreach construct in C# or
VBScript.
This property provides an alternative to Item for iterating through the
collection.

Return value

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed to the property


is invalid.

Example
This property is not normally called explicitly; it allows the use of ’foreach', as
shown in the following example.

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
Search API 637
ISearchResults :: _NewEnum

//do something
638 Search API
ISearchResults :: Item

ISearchResults :: Item
This method is used to return the specified item in the SearchResult collection
object. The value returned is an ISearchResult interface pointer which provides
properties and methods to allow the user to extract the results data.

Syntax
HRESULT Item([in] long lIndex,
[out, retval] LPVARIANT pvResult);

Parameters

[in] long lIndex The index number of the result required in the
SearchResult collection.

[out, retval] LPVARIANT pvResult Pointer to a VARIANT that will receive the
ISearchResult pointer.

Remarks
This property can be used in place of the _NewEnum property to iterate through
the collection.

Return value

rvS_OK Success.

rvE_POINTER The LPVARIANT passed into the method is invalid.

rvE_INVALIDARG The value of the first parameter, lIndex, is either less than 1
or greater than the number of results returned.

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
int num = results.Count;
for (int i = 1; i <= num; i++)
{
ISearchResult2 res = (ISearchResult2)results.Item(i);
Search API 639
ISearchResults :: Item

See also
■ “SearchResult object” on page 646
640 Search API
ISearchResults2 :: InSync

ISearchResults2 :: InSync
This property indicates whether or not the index is synchronized with the
current contents of the archive.
The property is read only.

Syntax
HRESULT InSync([out,retval] VARIANT_BOOL* value);

Parameters

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will 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#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
bool inSync = results.InSync;
if (inSync == false)
{
MessageBox.Show("It is possible that the index was being updated
as the search was being carried out", "Index not synchronised",
MessageBoxButtons.OK, MessageBoxIcon.Warning);
}
else //carry on as normal
Search API 641
ISearchResults2 :: TruncationReason

ISearchResults2 :: TruncationReason
This property indicates the reason, if any, for incomplete search results.
The property is read only.

Syntax
HRESULT TruncationReason([out,retval] ETruncationReason* value);

Parameters

[out,retval] ETruncationReason* value Pointer to an ETruncationReason value


which contains the reason for
truncation.

Remarks
For the values that ETruncationReason can have, see “ETruncationReason
enumeration” on page 536.

Return value

rvS_OK Success.

rvE_POINTER The ETruncationReason pointer passed into the property is


invalid

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
ETruncationReason tr = (ETruncationReason)results.TruncationReason;
if (tr == ETruncationReason.trNone)
{
//carry on processing
}
else
{
switch (tr)
{
case ETruncationReason.trAdminResultLimitExceeded:
642 Search API
ISearchResults2 :: TruncationReason

//handle the problem


break;
case ETruncationReason.trAdminTimeoutExpired:
//handle the problem
break;
//and so on for the other reasons
Search API 643
ISearchResults2 :: DateTimesUTC

ISearchResults2 :: DateTimesUTC
This property indicates whether date/time property values are returned as UTC
or local system time.
The property is read/write.

Syntax
HRESULT DateTimesUTC([in] VARIANT_BOOL value);
HRESULT DateTimesUTC([out,retval] VARIANT_BOOL* value);

Parameters

[in] VARIANT_BOOL value VARIANT_BOOL that will set a new value.

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will


receive the current value.

Remarks
By default, items are returned as UTC time.

Return value

rvS_OK Success.

rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current


value is invalid.

Example

C#
[in]
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
//make sure date/time values are returned in local system time
results.DateTimesUTC = false;
[out]
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
if (results.DateTimesUTC == true)
{
644 Search API
ISearchResults2 :: DateTimesUTC

//do something
Search API 645
ISearchResults2 :: LoadResults

ISearchResults2 :: LoadResults
This method can be used to load an instance of ISearchResults2 with the XML
results returned by the IIndexSearch2.SearchToXML method.

Syntax
HRESULT LoadResults([in] VARIANT rResultsXML);

Parameters

[in] VARIANT rResultsXML VARIANT containing the XML to load.

Remarks
For information on the XML schema used to return the search results, consult
Symantec support.
If possible, use the SearchResults object rather than processing the XML
directly.
The VARIANT may contain an IStream, byte array (SAFEARRAY) or a string
(BSTR) containing the XML.

Return value

rvS_OK Success.

rvE_INVALIDARG The VT TYPE of the VARIANT is incorrect.

rvS_FALSE The XML is empty or the VT TYPE is VT_EMPTY.

Example

C#
In this example, it is assumed that there is a string holding a set of XML results
from a previous search, called xmlResults.
ISearchResults2 results = (ISearchResults2) new SearchResults();
results.LoadResults(xmlResults);
646 Search API
SearchResult object

SearchResult object
The SearchResult object implements the following interfaces:
■ ISearchResult
■ ISearchResult2
These interfaces provide methods and properties that allow the user to examine
the individual results returned after a call to Search.

Syntax
interface ISearchResult2 : ISearchResult : IDispatch

Member summary

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.

Method Description

ISearchResult::Prop Obtains the value of a specific property from the result.

ISearchResult::Prop2 Obtains the value of a specific custom property from the result.

ISearchResult2::Item Gets the property at the 1-based position in the collection.

Remarks
ISearchResult interface pointers are obtained by using either
ISearchResults::_NewEnum and iterating through the collection, or by using
ISearchResults::Item to obtain a specific pointer from the collection.
Search API 647
SearchResult object

Example

C#
The following examples show two different ways of iterating through results in
a SearchResults collection object. It is assumed there is an ISearchResults2
object, 'results', obtained from a search.
ISearchResult2 res = (ISearchResult2)results.Item(index);
//index is a '1' based index into the collection of ISearchResult's.
or
foreach (ISearchResult2 res in results)
{
648 Search API
ISearchResult :: Result

ISearchResult :: Result
This property is used to get an XML string for this result or to set a new XML
string.

Syntax
HRESULT Result([out, retval] BSTR *pbsResult,
[in, string] BSTR bsResult);

Parameters

[out, retval] BSTR *pbsResult Pointer to a string that will contain the current
string.

[in, string] BSTR bsResult String that contains a new XML string to set.

Remarks
This property is simply the XML string for the search result stored in this result
object, or an empty string if the object is not initialized. It can also be used to
store an XML result. Any previous result will be overwritten.

Return value

rvS_OK Success.

rvE_POINTER The string pointer passed in to receive the current value is


invalid.

rvS_FALSE The XML string passed in is zero length.

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
string xmlResult = res.Result;
//do something
Search API 649
ISearchResult :: Number

ISearchResult :: Number
This property returns the unique identifier for this result.

Syntax
HRESULT Number([out, retval] long *plNumber);

Parameters

[out, retval] long *plNumber Pointer to a long integer that will contain the number.

Remarks
Returns the unique identifier for this result within the collection. The Id is
stored in the NUMBER attribute of each XML result tag.

Return value

rvS_OK Success.

rvE_POINTER The long integer pointer passed in to retrieve the value is


invalid.

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
long number = res.Number;
650 Search API
ISearchResult :: Prop

ISearchResult :: Prop
This method returns the specified property for the current result.

Syntax
HRESULT Prop([in, string] BSTR bsName,
[out, retval] LPVARIANT pvVal);

Parameters

[in, string] BSTR bsName String containing the name of the property.

[out, retval] LPVARIANT pvVal Pointer to a VARIANT that will contain the
property value.

Remarks
The value returned can be either a date, string or integer. If the value is
multi-valued, the returned VARIANT is an array of VARIANTS, each of which
contains a date, string or integer value.
The following VARIANT types may be returned: VT_I4, VT_UI4, VT_I8,
VT_DECIMAL, VT_DATE, VT_BSTR or VT_EMPTY.
The name can be that of a custom property, in the
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#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
Search API 651
ISearchResult :: Prop

{
object obj = res.Prop("ssid");

string ssid = (string)obj;


RetrieveItem(ssid);
652 Search API
ISearchResult :: Prop2

ISearchResult :: Prop2
This method is used to get the value of a specific custom property.

Syntax
HRESULT Prop2([in] BSTR bsName,
[in] BSTR bsPropertySet,
[in] BSTR bsPropertyName,
[out, retval] LPVARIANT pvVal);

Parameters

[in] BSTR bsName This parameter is not currently used.

[in] BSTR bsPropertySet String containing the name of the property set to
which the property belongs.

[in] BSTR bsPropertyName String containing the name of the property.

[out, retval] LPVARIANT pvVal Pointer to a VARIANT that will receive the value of
the property.

Remarks
This method returns the value of a custom property. If the requested property
does not exist, an initialized but empty VARIANT will be returned.
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.

Return value

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed in to receive the value is


invalid.

rvS_FALSE The custom property could not be found.


Search API 653
ISearchResult :: Prop2

Example

C#
This example assumes there is a custom property set, "CustomTags", which has
an integer property, "Importance".
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
int tag = 0;
//the prop we want should be an int but make sure
object obj = res.Prop2("CustomTags", "Importance");
Type type = obj.GetType();
if (type.Name == "Int32")
{
tag = (int)obj;
654 Search API
ISearchResult2 :: Count

ISearchResult2 :: Count
This property returns the number of properties in the current search result.
The property is read only.

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#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
int count = res.Count;
for (int i = 1; i < = count; i++)
{
object objProp = null;
object objVal = null;
res.Item(i, out objProp, out objVal);
if ((string)objProp == "ssid")
{
string ssid = (string)objVal;
//do something
Search API 655
ISearchResult2 :: Item

ISearchResult2 :: Item
This method returns the property name and value of the property at the position
in the index specified by the first parameter.

Syntax
HRESULT Item([in] long index,
[out] LPVARIANT propertyName,
[out] LPVARIANT propertyValue);

Parameters

[in] long index The index position of the required property.

[out] LPVARIANT propertyName Pointer to a VARIANT that contains the name of


the property.

[out] LPVARIANT propertyValue Pointer to a VARIANT that will contain the value
assigned to the property.

Remarks
Use this method to obtain the name and value of a property at a specific position
in the collection. Note that the collection is 1-based not 0-based.
The 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 One of the VARIANT pointers passed to the method is invalid.

rvE_INVALIDARG The index was outside the range 1 to the number of


properties.
656 Search API
ISearchResult2 :: Item

Example

C#
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
int count = res.Count;
for (int i = 1; i < = count; i++)
{
object objProp = null;
object objVal = null;
res.Item(i, out objProp, out objVal);
if ((string)objProp == "ssid")
{
string ssid = (string)objVal;
//do something
Search API 657
ISearchResult2 :: DateTimesUTC

ISearchResult2 :: DateTimesUTC
This property indicates whether property values of type VT_DATE are returned
as UTC or local system time.
The property is read/write.

Syntax
HRESULT DateTimesUTC([in] VARIANT_BOOL value,
[out,retval] VARIANT_BOOL* value);

Parameters

[in] VARIANT_BOOL value VARIANT_BOOL containing the new value to set.

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will receive


the current value.

Remarks
By default, items are always archived using UTC time.

Return value

rvS_OK Success.

rvE_POINTER Value is an invalid pointer.

Example

C#
[in]
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
foreach (ISearchResult2 res in results)
{
//make sure date/times are returned in local system time
res.DateTimesUTC = false;
//do something
[out]
ISearchResults2 results =
(ISearchResults2)search.Search(query.Query, 1, 100, "");
658 Search API
ISearchResult2 :: DateTimesUTC

foreach (ISearchResult2 res in results)


{
bool isUTC = res.DateTimesUTC;
//do something
Appendix A
About Enterprise Vault
indexes
This section provides more detailed information about Enterprise Vault indexes.

About index volume sets and volumes


Each archive index comprises one or more sequential index volume sets. An
index volume set contains an index volume. (Currently, an index volume set can
contain only one index volume). Each index volume contains index entries for
the items stored in the archive.
See Figure 8-1 on page 519.
An index volume can contain approximately three to five million index
documents. The maximum number of index entries for a volume will depend on
the level of indexing set and the number of properties indexed for each item.
When an index volume is full, the Enterprise Vault Indexing service
automatically creates a new index volume set (containing a new index volume).
The Enterprise Vault administrator uses the Enterprise Vault Administration
Console to configure the physical locations to be used by the Indexing service
when creating new indexes for archives.
Typically, user mailbox indexes will require only a single volume. Indexes for
larger archives, such as file system archives and journal archives, are quite
likely to have multiple volumes.

About index properties


Enterprise Vault indexes a set of system properties for each item. The system
properties indexed depend on the level of indexing configured when the item is
archived.
660 About Enterprise Vault indexes
About index schemas

In addition to the system index properties, you can add custom index metadata
properties to the index document for an item. These properties may be required
to enable users or third-party applications to search for particular items.
Custom index metadata can be added in the following ways:
■ Using the SimpleIndexMetadata interface of the Content Management API.
An application that submits items to Enterprise Vault for archiving using
the Content Management API can call the SimpleIndexMetadata methods
and properties to add custom index metadata to the item before it is
archived.
See “SimpleIndexMetadata object” on page 277.
■ Using the External Filtering API.
The IArchivingControl interface can be used to add custom index metadata
properties as required by the external filter as an item is archived.
Note that custom index metadata properties cannot be added for attachments.

About index schemas


The contents of index entries differs depending on the index schema in use. This
affects the way indexes are searched and the results returned.
There are two index schemas available with Enterprise Vault:
■ Default schema
■ Item Granularity Only schema
If you are using the Item Granularity Only schema, then the registry setting,
SchemaType, will have a value of "1". This setting, if configured, is in the
following location:
HKEY_LOCAL_MACHINE
\SOFTWARE
\KVS
\Enterprise Vault
\Indexing
Which schema an installation uses will depend on the type of applications that
will search the indexes. In general, any application that performs complex
searches, such as those performed by Enterprise Vault Compliance and
Discovery Accelerator products, should use the Item Granularity Only schema.
The Item Granularity Only schema enables such searches to be performed
considerably faster than the default schema.
If you have an existing Enterprise Vault environment, you need to consider the
following if you decide to enable the Item Granularity Only schema:
■ After you enable the schema (using the SchemaType registry setting), only
new indexes will be affected. Existing indexes need to be rebuilt in order to
About Enterprise Vault indexes 661
About index schemas

use the new schema. If you have a very large number of archives, this could
take a considerable time.
■ Users will see a difference in the number of results returned when
searching with Enterprise Vault browser search or the Enterprise Vault
search integrated with Outlook. By default, these search applications return
both top-level items and individual attachments, and with the Item
Granularity Only schema, they will not see individual attachments.

Default index schema


With the default index schema, an index document is created for the top-level
item (such as a message), and separate index documents are created for each
attachment; each nested message and attachment is stored in a separate index
document.
When a search is performed, each index document is searched, and all items
that contain a match are returned as individual results; so results may contain
both top-level items and attachments.
For example, a search for “John Doe” AND “Widgets Corp” will return any items
or attachments that contain both “John Doe” and “Widgets Corp” in the same
index document.
With this schema, performing a very complex search could result in a very large
number of active queries in memory, potentially resulting in “out of memory”
errors. For this reason, search query “chunking” settings may be required to
limit the number of active queries in memory.

Item Granularity Only schema


With the Item Granularity Only schema, there is a single index document for the
top-level message and any attachments; this means that the top-level item and
attachments are searched as a single item.
When a search is performed, the single index entity (containing both top-level
items and attachments) is searched, and only top-level items are returned in the
results. Even if the search criteria is only matched in one or more attachments,
only the associated top-level item is returned in the results. Attachments can be
accessed from the top-level items.
As index data for an item and any attachments are stored in the same index
document, searches for terms that are combined using AND may return more
results than are returned with the default schema. For example, a search for
“John Doe” AND “Widgets Corp” may return an item which has “John Doe” in
attachment 1 and “Widgets Corp” in attachment 3.
By combining the information from attachments into the top-level item in the
index, the need to configure query “chunking” for very complex searching is
662 About Enterprise Vault indexes
About index schemas

removed. Complex searches, such as those performed by Enterprise Vault


Compliance and Discovery Accelerator products, are considerably faster if this
index schema is used.
Appendix B
Enterprise Vault
Properties
This section lists the properties that are defined by Enterprise Vault:
■ System properties
■ Defined custom properties
■ Defined custom FSA properties
■ Defined custom SharePoint properties
■ Defined custom properties for Compliance Accelerator.
When processing an item, Enterprise Vault populates properties with
information in the item. This data is then stored with the archived item. Indexed
properties are added to the archive index and can be used in archive searches.
Not all properties are present on every item, and the type library defines many
more properties than are currently used. The data available in search results for
each item is a subset of these properties; any properties that are to be returned
in search results must be defined as retrievable.

Note: If you are using the Search API from a language that cannot access the
string constants that are defined in the type library, any string literals used
instead must match exactly the values from the type library. For example, for
IndexPropSSID use "ssid".

In the following tables:


■ Searchable properties are those that can be used in search queries.
■ Retrievable properties are those that can be returned in search results.
■ Multi-valued properties can have multiple values for a single index entry.
664 Enterprise Vault Properties
System properties

■ Sortable properties are those that can be used to order search results.
Properties marked with are optimized in the index for sorting and
provide the quickest results.

System properties
This section lists the system properties defined in Enterprise Vault.
All properties in this table have defined constants, IndexPropXXXX, where
XXXX is the uppercase form of the property name. For example, IndexPropSUBJ
is the constant for the defined property, “subj”, and IndexPropRCAT is the
constant for the system property, “rcat”.

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Subject/Title subj String

Message Priority prio String Although indexed as a string,


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

Message Importance impo String Although indexed as a string,


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

Message Sensitivity sens String Although indexed as a string,


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

Message Security secu String Currently not populated with


any value.

Message Originator orgn String

Original identifier for iden String


the item.
(e.g. SubmissionId for
a sent message)

Last Modified date of mdat Date Range 1 Jan 1970 to 31 Dec


the item 2148
Enterprise Vault Properties 665
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Original identifier for coid String


this component of
the item

Data type of the item dtyp String E.g. DOC, XLS, MSG

De-duplication fpdd String Can be used to find an exact


fingerprint of item match of a message or a
document.

Content fingerprint fpcn String Can be used to find a match


of item on an attachment or
document content.

Archived Date adat Date Range 1 Jan 1970 to 31 Dec


2148

Original location of locn String A sequence of folders.


the item

Current location of clcn String A sequence of folders.


the item

The last or leaf folder lolf String


of original location

The last or leaf folder cllf String


of current location

Original location lofn String


folder names
(ordered)

Current location clfn String


folder names
(ordered)

The item's Saveset ssid String See “Note 1” on page 676.


identifier Max 72 chars. However, if
you include any attachment
num, as per Note 1, then the
max number of chars is
76 + 1 + 10 => 87 chars.

Shortcut location shct String Not supported from


Enterprise Vault 10.
666 Enterprise Vault Properties
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

User who archived user String Currently not populated.


the item.

Original retention rcat String Max 112 chars.


category Id

Current retention crct String Max 112 chars.


category Id

Original retention rcnm String Max 32 chars


category name

Current retention crcn String Max 32 chars


category name

Index Sequence snum Integer 64-bit integer


Number

VaultEntryId of index vlid String Max 112 chars.


containing the item

Created, date Date Range 1 Jan 1970 to 31 Dec


sent/received or 2148
archivedDate See “Note 2” on page 676

Content cont String Search API: Only the first


120 significant characters
can be retrieved.
Content Management API:
HTML representation to a
max of 5 MB.
See “Note 3” on page 676

Languages lang String Currently not populated.

Categories/Keywords keys String

The size of the item size Integer 32-bit integer


in KB

The number of natc Integer 32-bit integer


attachments

Permission VaultIds pvid String Max 112 chars.


for the item. (Known
as Archive Folder
VaultIds)
Enterprise Vault Properties 667
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Attachment Number anum Integer 32-bit integer


Zero for top-level item.
In ItemGranularity schema,
this property cannot be used
in a query to limit hits on
attachments or top level
documents. This is because
each index document
contains the parent item and
all the attachments.

Expiry date for the edat Date Range 1 Jan 1970 to 31 Dec
item (based on crct) 2148

Number of days to ndte Integer 32-bit integer


expiry for the item
(based on crct)

Rank value of the rank Integer 32-bit integer


item when sorted by
relevance (0 to
10,000)

The item's original msgc String


MAPI Message Class
(e.g. IPM.Note)

Message Flag Status flag Integer 32-bit integer

Reason for missing comr String See “Note 4” on page 677


content Technically no limit,
practically limited to 32-bit
integer max.

Attachments only. taut String Not applicable to items


The author of the indexed using
ItemGranularity schema.
top-level item

Attachments only. tsub String Not applicable to items


The subject/title of indexed using
ItemGranularity schema.
the top-level item

Attachments only. tsiz Integer 32-bit integer


The size of the Not applicable to items
top-level item in KB indexed using
ItemGranularity schema.
668 Enterprise Vault Properties
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Conversation cnid String For MAPI items, a 32


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

Conversation cnhv String For MAPI items, 12


tracking index hexadecimal characters
representing a datetime,
followed by 32 hexadecimal
characters representing a
128-bit GUID, followed by 10
hexadecimal characters for
each reply/forward.
Currently not populated for
other items.

Conversation cntp String Currently only populated for


tracking topic MAPI items.

Index Volume. ivid Integer 32-bit integer


Identity of the
volume containing
the item

Index Volume Set. vsid Integer 32-bit integer


Identity of the
volume set
containing the item

Message Envelope menv String Only present for Exchange


recipient and sender journal messages.
information See “Note 5” on page 677
Retrievable using the
Content Management API
(see “IArchiveMetaData ::
IndexData” on page 253)

Message Envelope jrcp String Only present for Exchange


Recipient. journal messages. The
property values include both
Union of jrto, jrcc,
email addresses and display
jrbc & jren names (where present).

Message Envelope jrto String Only present for Exchange


TO: Recipient journal messages.
See Notes for jrcp.
Enterprise Vault Properties 669
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Message Envelope jrcc String Only present for Exchange


CC: Recipient journal messages.
See Notes for jrcp.

Message Envelope jrbc String Only present for Exchange


BCC: Recipient journal messages.
See Notes for jrcp.

Message Envelope jren String Only present for Exchange


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

Message Envelope jrau String Only present for Exchange


Author journal messages.
Union of jrfm, jrpp & See Notes for jrcp.
jaen

Message Envelope jrfm String Only present for Exchange


FROM: Recipient journal messages.
See Notes for jrcp.

Message Envelope jrpp String Only present for Exchange


PP: Recipient journal messages.
Per Procurationem See Notes for jrcp.
(by delegation to):
person on whose
behalf document has
been written or
message has been
sent

Message Envelope jaen String Only present for Exchange


Other Author journal messages.
See Notes for jrcp.
Used when the author details
are not explicitly identified
as FROM or PP.
670 Enterprise Vault Properties
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Message Sender and sere String See “Note 6” on page 678


Recipient Retrievable using the
Content Management API
(see “IArchiveMetaData ::
IndexData” on page 253)

Message Recipient. recp String


Union of redn, reea,
resm, reot & jrcp

Message Recipient. redn String


Display/friendly
name. Union of rtdn,
rcdn, rbdn & rndn

Message Recipient. reea String


Email address. Union
of rtea, rcea, rbea &
rnea

Message Recipient. resm String


SMTP email address.
Union of rtsm, rcsm,
rbsm & rnsm

Message Recipient. reot String


Other email address.
Union of rtot, rcot,
rbot & rnot

TO: Recipient reto String Max 256 chars.


The retrievable value is the
first few RTDN (or RTSM)
values, up to a maximum of
256 characters.

TO: Recipient. rtdn String


Display/friendly
name

TO: Recipient. rtea String


Email address. Union
of RTSM & RTOT

TO: Recipient. rtsm String


SMTP email address
Enterprise Vault Properties 671
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

TO: Recipient. rtot String


Other email address

CC: Recipient recc String Max 256 chars.


The retrievable value is the
first few RTDN (or RTSM)
values, up to a maximum of
256 characters.

CC: Recipient. rcdn String


Display/friendly
name

CC: Recipient. rcea String


Email address. Union
of rcsm & rcot

CC: Recipient. rcsm String


SMTP email address

CC: Recipient. rcot String


Other email address

BCC: Recipient rbcc String Max 256 chars.


The retrievable value is the
first few RTDN (or RTSM)
values, up to a maximum of
256 characters.

BCC: Recipient. rbdn String


Display/friendly
name

BCC: Recipient. rbea String


Email address. Union
of rbsm & rbot

BCC: Recipient. rbsm String


SMTP email address

BCC: Recipient. rbot String


Other email address
672 Enterprise Vault Properties
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Other Envelope renv String Max 256 chars.


Recipient The retrievable value is the
first few RTDN (or RTSM)
values, up to a maximum of
256 characters.

Other Envelope rndn String


Recipient.
Display/friendly
name

Other Envelope rnea String


Recipient.
Email address. Union
of rnsm & rnot

Other Envelope rnsm String


Recipient.
SMTP email address

Other Envelope rnot String


Recipient.
Other email address

Number of Recipients nrcp Integer 32-bit integer

Number of TO: nrto Integer 32-bit integer


Recipients

Number of CC: nrcc Integer 32-bit integer


Recipients

Number of BCC: nrbc Integer 32-bit integer


Recipients

Number of Other nren Integer 32-bit integer


Envelope Recipients

Author. Union of auth String


audn, auea, ausm,
auot, writ, from, ppgn
& jrau
Enterprise Vault Properties 673
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Author. audn String


Display/friendly
name. Union of wrdn,
frdn, ppdn

Author. auea String


Email address. Union
of ausm, auot and
wrea

Author. ausm String


SMTP email address.
Union of wrsm, frsm
ppsm

Author. auot String


Other email address.
Union of wrot, frot,
ppot

Writer. writ String


Union of wrdn, wrea,
wrsm, wrot

Writer. wrdn String


Display/friendly
name

Writer. wrea String


Email address. Union
of wrsm & wrot

Writer. wrsm String


SMTP email address

Writer. wrot String


Other email address

FROM: from String


Union of frdn, frea,
frsm, frot

FROM: frdn String


Display/friendly
name
674 Enterprise Vault Properties
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

FROM: frea String


Email address. Union
of frsm & frot

FROM: SMTP e-mail frsm String


address

FROM: frot String


Other email address

PP ppgn String
Union of ppdn, ppea,
ppsm & ppot. Per
Procurationem (by
delegation to) person
on whose behalf
document has been
written or message
has been sent

PP ppdn String
Display/friendly
name

PP ppea String
Exchange email
address. Union of
ppsm, ppot

PP ppsm String
SMTP email address

PP ppot String
Other email address

Name name String


Union of recp, auth

Name nadn String


Display/friendly
name. Union of redn
& audn
Enterprise Vault Properties 675
System properties

Table B-1 System properties

Description Name Type Search- Retriev- Multi- Fast Notes


able able Valued Sort-
able

Name naea String


Exchange email
address. Union of
reea & auea

Name nasm String


SMTP email address.
Union of resm &
ausm

Name naot String


Other email address.
Union of reot & auot

Text text String


Union of cont & subj

Event start date csrt Date Range 1 Jan 1970 to 31 Dec


E.g. Calendar meeting 2148
start date

Event end date cend Date Range 1 Jan 1970 to 31 Dec


E.g. Calendar meeting 2148
end date

Event location clon String


E.g. Calendar meeting
location

Task due date tddt Date Range 1 Jan 1970 to 31 Dec


2148

Task completed date tcdt Date Range 1 Jan 1970 to 31 Dec


2148

Task status tsts Integer Property value can be one of


the following:
0 = Not started
1 = In progress
2 = Completed
3 = Paused
4 = Deferred
676 Enterprise Vault Properties
System properties

Note 1
The ssid value returned for attachments is a concatenation of the SavesetId and
the attachment number (see anum), separated by a full stop.
For example, for the first attachment:
849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B
0.1
To use the Content Management API to retrieve the item, the SavesetId must be
extracted by removing the trailing full stop and attachment number:
849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B
0

Note 2
For a message, this is selected from the first of the following properties that is
present on the message:
Message Delivery Time (PR_MESSAGE_DELIVERY_TIME)
Original Message Delivery Time (PR_ORIGINAL_DELIVERY_TIME)
Submission Time (PR_CLIENT_SUBMIT_TIME)
Original Message Submission Time (PR_ORIGINAL_SUBMIT_TIME)
Message Transport Provider Submission Time (PR_PROVIDER_SUBMIT_TIME)
Last Modification Time (PR_LAST_MODIFICATION_TIME)
Creation Time (PR_CREATION_TIME)
Deferred Delivery Time (PR_DEFERRED_DELIVERY_TIME)
For an attachment to a message or a document, this is the created date of the
object (PR_CREATION_TIME).
In the extreme case that none of the above properties are available, then the
current time (archival time) is used.

Note 3
In the Search API, the value is the first 120 characters of the textual
representation of the content.

In the Content Management API, the value is the HTML representation of the
content to a maximum of 5 MB.
If the size is larger than 5 MB, no value is returned, but a content missing reason
property (comr) with value vmrVALUENOTOBTAINED is returned instead.
The 5 MB limit can be changed using the registry value,
HKEY_LOCAL_MACHINE
\Software
\KVS
\Enterprise Vault
\MaxIndexDataHTMLContentKB
Enterprise Vault Properties 677
System properties

Note 4
Predefined values for comr property:
enum EValueMissingReason
{
vmrNOREASON =0 No reason available
vmrVALUENOTFOUND =1 Content does not exist
vmrVALUENOTOBTAINED =2 Content could not be obtained
vmrVALUECORRUPT =3 Content is (or appears to be) corrupt
vmrNOCONVERTER =4 Not possible to convert content to
suitable format (i.e. no converter for this specific conversion)
vmrCONVERSIONFAILED =5 Conversion of content failed (i.e.
converter error)
vmrCONVERSIONTIMEDOUT =6 Conversion of content timed out
vmrFORMATEXCLUDED =7 Content requires conversion but its data
format is excluded from conversion
vmrCONVERSIONBYPASS =8 Content requires conversion but
conversion bypass has been set
vmrVALUEENCRYPTED =9 Content is encrypted
vmrCONVERTERUNINIT =10 Content requires conversion but
converters are not available, or have not been initialized
vmrADDITEMTOINDEX =11 Unable to add content to index
vmrFORMATNOTRECOGNISED =12 Converters did not recognize the file
type
vmrLARGEFILE =13 Conversion excluded for large files
vmrUNKNOWNCODEPAGE =14 Conversion excluded for codepages we
cannot detect (e.g. GB18030)

Note 5
The menv property contains the Message Envelope recipient and sender
information for journal messages, in XML format. The following is an example
of what it can contain:

<?xml version="1.0" encoding="utf-16?">


<MSGENV>
<RECP P1="true">
<TO>
<RC>
<DN>Joe User</DN>
<EA>[email protected]</EA>
</RC>
<DL>
<DN>Internal Users</DN>
<EA>[email protected]</EA>
<RC>
<DN>Administrator</DN>
<EA>[email protected]</EA>
</RC>
<RC>
<DN>CEO</DN>
678 Enterprise Vault Properties
System properties

<EA>[email protected]</EA>
</RC>
</DL>
</TO>
<CC />
<BCC>
<RC>
<DN>Jill User</DN>
<EA>[email protected]</EA>
</RC>
</BCC>
<ENV>
<RC>
<DN>John User</DN>
<EA>[email protected]</EA>
</RC>
</ENV>
</RECP>
<AUTH>
<FROM><DN>Chris Davies</DN> <EA>[email protected]</EA>
</FROM>
<PP><DN>Bill Stephens</DN><EA>[email protected]
</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>[email protected]</EA>
</RC>
Enterprise Vault Properties 679
System properties

<DL>
<DN>Internal Users</DN>
<EA>[email protected]</EA>
<RC>
<DN>Administrator</DN>
<EA>[email protected]</EA>
</RC>
<RC>
<DN>CEO</DN>
<EA>[email protected]</EA>
</RC>
</DL>
</TO>
<CC />
<BCC />
</RECP>
<AUTH>
<FROM><DN>Chris Davies</DN> <EA>[email protected]</EA>
</FROM>
<PP><DN>Bill Stephens</DN>
<EA>[email protected]</EA>
</PP>
</AUTH>
</MSG>

This example is not exhaustive. The sere property follows the same schema as
the menv property, except that the root node is <MSG> rather than <MSGENV>.

Version information
■ The sere property is available in Enterprise Vault 6.0 SP5, Enterprise Vault
7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1,
Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.
■ <AUTH> element of the menv property is available in Enterprise Vault 6.0
SP5, Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See
“Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault
6.0 SP5” on page 31.
■ Missing content reasons returned in the missing content property, comr, are
available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1.
See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise
Vault 6.0 SP5” on page 31.
■ The event and task properties, csrt, cend, clon, tddt, tcdt and tsts are
available in Enterprise Vault 8.0 SP3 and later.
■ The shct property is not supported from Enterprise Vault 10.
680 Enterprise Vault Properties
Defined custom properties

Defined custom properties


The following list of custom properties are also defined in Enterprise Vault.

Table B-2 Defined custom properties

Description Name Type Search- Retriev- Notes


able able

For an item copied by Move Vault.CopiedFrom String See “Note 1”


Archive, provides the following If an archive has been
details: moved several times, there
will be a value for each
■ Time the item was copied move.
■ The source item archive
■ Saveset ID

If message is a journal message, Vault.JournalType String Currently defined values:


the type of journal message ■ E2007
■ E2003
■ E2007ClearText
E2007RMS
See “Note 2”

Message direction Vault.MsgDirection String 32-bit integer as a string.


Currently defined values:
0 - undefined
1 - internal
2 - external-in
3 - external-out

Type of the message. Vault.MsgType String Currently defined values:


■ EXCH
■ Bloomberg
■ IM.vendor
■ FAX.vendor
■ DXL

Note 1
Format is
<UTC_datetime_of_copy>,<source_archive_ID>,<source_item_Saveset_ID>
For example,
2009-11-17
13:37:01Z,16B3597E77206FB4690FB46573DA6D7081110000EVServer.domain.l
ocal,20081114
0000000~200811141011170000~Z~B082EF701FF8FB47509D5228C99D2B51
Enterprise Vault Properties 681
Defined custom FSA properties

Note 2
If the message is from Exchange Server 2010 with journal report decryption
enabled, then the message is in Exchange Server 2007 report format and
includes both an RMS-protected copy and a clear text copy of the message. Both
copies are stored in the saveset. The advanced setting in the Enterprise Vault
Exchange Journaling policy, ClearText copies of RMS Protected items,
determines whether Enterprise Vault uses the clear text copy or the
RMS-protected copy as the primary message during archiving. If the value of
Vault.JournalType is "E2007RMS", then the primary message is the
RMS-protected copy. A value of "E2007ClearText" indicates that the primary
message is the clear text copy.
See the Administrator’s Guide for more information on this policy setting.

Defined custom FSA properties


The following list of custom properties are defined in Enterprise Vault for FSA
items.

Table B-3 Defined custom FSA properties

Description Name Type Search- Retriev- Notes


able able

Original Name of file at the EVFSA.OriginalFileName String


point of archival

Indicator that item was EVFSADLMImport.DLM String Currently only


imported from DLM populated with
the string
"Imported"

Defined custom SharePoint properties


The following list of custom properties are defined in Enterprise Vault for
SharePoint items.

Table B-4 Defined custom SharePoint properties

Description Name Type Seach- Retriev- Notes


able able

Document title EVSP.Title String

SharePoint documentId EVSP.DocId String


682 Enterprise Vault Properties
Defined properties for Compliance Accelerator

Table B-4 Defined custom SharePoint properties

Description Name Type Seach- Retriev- Notes


able able

Document version EVSP.Version String

Check in comment EVSP.Comment String

Display name of document EVSP.Editor String


editor

Domain name (Windows EVSP.CreatedBy String


account name) of document
author

Domain name (Windows EVSP.ModifiedBy String


account name) of document
editor

SharePoint Site Id EVSP.SiteId String

SharePoint Site name EVSP.Site String

SharePoint Site Url EVSP.SiteUrl String

Customer configurable EVSPP.<Sharepoint String


properties - any SharePoint property name>
property

Defined properties for Compliance Accelerator


The following list of custom properties are defined in Enterprise Vault for items
processed by the Compliance Accelerator Journaling Connector.

Table B-5 Defined custom properties for Journaling Connector

Description Name Type Searchable Retrievable Multi- Notes


Valued

The set of CA KVSCA.DeptAuthor String CA Dept IDs


Department Ids
that the item's
author is a member
of
Enterprise Vault Properties 683
Defined properties for Compliance Accelerator

Table B-5 Defined custom properties for Journaling Connector

Description Name Type Searchable Retrievable Multi- Notes


Valued

The set of CA KVSCA.DeptRecips String CA Dept IDs


Department Ids
that the item's
recipients are
members of

The union of KVSCA.Department String CA Dept IDs


KVSCA.DeptAuthor
and
KVSCA.DeptRecips

Policies, defined in evtag.category String Policy names


the policy
management
software, which do
not affect capture
either way; they
only categorize
emails.

Policies, defined in evtag.exclusion String Policy names


the policy
management
software, which
either preclude
capture or advocate
non-capture.

Policies, defined in evtag.inclusion String Policy names


the policy
management
software, which
either demand or
suggest capture.

The policy action is Vault.PolicyAction String Defined values are:


the overall action ■ NOACTION
■ EXCLUDE
that should be
■ INCLUDE
taken on an item;
the sum result of all
the applied policies.
684 Enterprise Vault Properties
Defined properties for Compliance Accelerator
Appendix C
API return values
This appendix lists the Enterprise Vault API return values.

Content Management API return values


Table C-1 Content Management API return values

Return value Value Description

CONTENTMANAGEMENTAPI_E_UNAVAILABLE 0x80040300 Enterpise Vault is not running

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL 0x80040301 Time to create a new archive

CONTENTMANAGEMENTAPI_E_BUSY 0x80040302 Enterprise Vault is


temporarily unable to process
the request. The server is
busy, or has insufficient
resources, or is only able to
read data due to ongoing
backups. Wait and retry later.

CONTENTMANAGEMENTAPI_E_NO_ACCESS 0x80040303 Caller has insufficient


permissions to access the
vault store, archive, or item,
or archive is in a read-only
state.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 0x80040304 Problem with input


parameters

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER 0x80040305 An input parameter identifies


more than one object

CONTENTMANAGEMENTAPI_E_INTERNAL_FAILURE 0x80040306 An internal failure occurred


686 API return values
Retention API return values

Table C-1 Content Management API return values

Return value Value Description

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND 0x80040307 Item not found

CONTENTMANAGEMENTAPI_E_NOT_FOUND 0x80040308 Archive, Vault Store or


Retention Category does not
exist

CONTENTMANAGEMENTAPI_E_DELETION_BARRED 0x80040309 Deletion of the item is not


permitted

CONTENTMANAGEMENTAPI_E_NO_LICENSE 0x8004020A API is not correctly licensed

CONTENTMANAGEMENTAPI_E_LICENSE_EXPIRED 0x8004030B API license has expired

CONTENTMANAGEMENTAPI_E_INVALID_DEVICE 0x8004030C Not a compliance device

CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID 0x8004030D Attempting to


insert/copy/move item with
an Item Id that is not unique
in the target vault store.

CONTENTMANAGEMENTAPI_E_NOT_SUPPORTED 0x8004030E The operation is not


supported.

Retention API return values


The following return values are defined for the Retention API:

Table C-2 Retention API return values

Return value Value Description

RetentionCategoryAlreadyExists 0x800700b7 Returned when attempting to add a retention


category, and one already exists with the same
name.

RetentionCategoryNotExist 0x80070002 Returned when attempting to update a retention


category, and the RetentionCategoryId does not
exist in the Enterprise Vault directory.

SiteIdNotFound 0x800704BA Returned if the site specified by


DirectoryDNSAlias does not exist.
API return values 687
Search API return values

Search API return values


The following return values are defined for the Search API:

Table C-3 Search API return values

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

rvE_SERVER_UNAVAILABLE 0x800706BA The index server is not currently available

rvINDEXING_W_ARCHIVE_NOT_SET 0x80041C6B An archive has not been selected

rvINDEXING_W_CANT_ACCESS_DIRECTORY 0x80041C11 The Enterprise Vault Directory is not


available

rvINDEXING_E_ARCHIVE_NOT_FOUND 0xc0041C5C The archive does not exist

rvINDEXING_W_INDEXDISABLED 0x80041C84 The archive's index is current disabled

rvINDEXING_W_ARCHIVE_BEING_DELETED 0x80041C52 The archive is marked for deletion

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET 0x80041C6C The index volume set identity does not


belong to the currently selected archive

rvINDEXING_W_UNKNOWN_INDEX_VOLUME 0x80041C6D The index volume identity does not belong


to the currently selected archive

rvINDEXING_W_UNABLE_FAILED_VOLUME 0x80041C69 The search failed due to at least one index


volume being marked as failed

rvINDEXING_W_UNABLE_OFFLINE_VOLUME 0x80041C6A The search failed due to at least one index


volume being marked as offline

rvINDEXING_E_TOO_MANY_RESULTS 0xc0041C83 The search request was rejected because


too many search results were requested.
The maximum is defined by the
MaxSearchResultsPerVolumeSet
property.
688 API return values
External Filter API Event log messages

Table C-3 Search API return values

Return value Value Description

rvINDEXING_E_TOO_MANY_VOLUMES 0xc0041C82 The search request was rejected because


there are too many index volumes to
search. The maximum is defined by the
MaxSearchIndexVolumeSets property.

rvINDEXING_W_SERVICE_BUSY 0x80041C86 The search was rejected because the


indexing service is too busy

rvINDEXING_W_SERVER_STOPPING 0x80041C1A The search was rejected because the index


is being unloaded to allow another index
to be searched

rvINDEXING_W_SERVICE_STOPPING 0x80041C47 The search was rejected because the index


service is being shutdown

rvINDEXING_W_SEARCH_WOULD_BLOCK 0x80041C70 The search was rejected because the index


is currently overloaded with search
requests

rvINDEXING_W_SEARCH_TIMEDOUT 0x80041C71 The search failed because it took too long


to complete. The timeout is defined by the
Timeout property.

rvINDEXING_E_INVALID_QUERY 0xC0041C53 The search was rejected since the search


query was invalid.

rvINDEXING_E_ILLEGAL_WILDCARD_QUERY 0xC0041C5E The search was rejected since the search


query contained invalid wildcard terms.

rvINDEXING_E_FAILED_SEARCH_REQUEST 0xC0041C67 The search failed due to an internal error.


Check the Enterprise Vault event log on
the Enterprise Vault server.

rvINDEXING_E_INDEX_SEARCH_FAILED 0xC0041C0E The search failed due to a failure to search


one or more of the targeted index volumes
sets.

External Filter API Event log messages


The following events are written to the Enterprise Vault event log by the Task
Filter Controller.
API return values 689
External Filter API Event log messages

Exchange Server filtering


The following messages are written to the Enterprise Vault event log by the
Exchange Task Filter Controller.

Event Type Description Example

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

3263 Error Logged by the filter controller An error occurred processing the external filter
when an external filter returns '<filter prog id>'. No more filters will be processed.
an error when processing a Error: <error information>
message. (The filter’s
Mailbox: <mailbox DN>
ProcessFilter method returns a
Message Folder: <folder name>
non-zero return value). The Message Title: <message title>
filter controller stops
processing the message.

3146 Error Logged by the filter controller Failed to initialize the external filter with ProgId
when attempting to create an '<filter prog id>'. Either the ProgId is incorrect or
instance of an external filter. the DLL has not been registered.
Please check the ProgId or register the DLL for the
external filter.

3147 Error Logged by the filter controller An error has occurred initializing the external filter
when an external filter returns '<filter prog id>'.
an error when initializing. (The
Error: <error information>
filter’s Initialize method
returns a non-zero return
value).

3150 Error Logged by the filter controller Whilst processing external filters too many
when a stream of consecutive consecutive errors have occurred. This Task will
errors are encountered. now shut down.

45329 Informational Logged by the filter controller External Filter '<filter prog id>' initializing...
at the point of initializing each
external filter.

45330 Informational Logged by the filter controller External Filter '<filter prog id>' stopped.
at the point of stopping each
external filter.
690 API return values
External Filter API Event log messages

Domino Server filtering


The following messages are written to the Enterprise Vault event log by the
Domino Journaling Task Filter Controller.

Event Type Description Example

41086 Informational Logged by the filter controller The Domino external filter ‘<filter_name>’ has
at the point of initializing each started.
installed filter plug-in.

41087 Informational Logged by the filter controller The Domino external filter ‘<filter_name>’ has
at the point of de-initializing stopped.
each installed filter plug-in.

41088 Error Logged by the filter controller The Domino external filter '<filter_name>' failed to
if a filter plug-in raises an error process an item.
during processing. The reason
Reason: An applicable RuleSet has not been defined
for the error is contained in the for database 'symantec\db_name.nsf' and a default
message text.
Content Category has not been specified.

41036 Error Logged by the filter controller Unable to start the FilterController The following
if a filter plug-in raises an error error occurred:
during initialization. The
Unable to initialize() filter '<filter_name>'.
reason for the error is
contained in the message text. Reason: ...
Index

A Indexing items 517


Indexing levels 517
AddProperty method
IndexSearch2 object
ISearchQuery interface methods
Search API
SearchQuery object 552
SelectArchive method 588
AddQuery method
interface methods
ISearchQuery interface methods
AddProperty
SearchQuery object 558
SearchQuery object 552
AddQuery
C SearchQuery object 558
compressing items 517 SelectArchive
constants IndexSearch2 object 588
ESearchQueryFlags constant SetProperty
Search API 533 SearchQuery object 550
Converting items 517 ISearchQuery interface methods
Custom Filtering API AddProperty method 552
get_defaultRetentionCategoryId methods AddQuery method 558
IArchivingControl interface 445 SetProperty method 550
ProcessFilter method items
IExternalFilter interface 437 compressing 517
converting 517
E
Enterprise Vault documentation 15 M
ESearchQueryFlags constant methods
Search API 533 SelectArchive
IndexSearch2 object 588
F
flags P
ESearchQueryFlags constant ProcessFilter method
Search API 533 IExternalFilter interface
Custom Filtering API 437
G
get_defaultRetentionCategoryId methods S
IArchivingControl interface Search API
Custom Filtering API 445 ESearchQueryFlags constant 533
searches
overview of performing a search 524
I results, processing 527
Indexes SearchQuery object
updating 517 SearchQuery interface methods
692 Index

AddProperty 552
AddQuery 558
SetProperty 550
SelectArchive method
IndexSearch2 object
Search API 588
SetProperty method
ISearchQuery interface methods
SearchQuery object 550

You might also like